npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@tablelist/tablelist-js-sdk

v2.39.0

Published

Tablelist Javascript SDK

Downloads

40

Readme

Coverage Status

#Javascript SDK

##Table of Contents

  1. Getting Started
  2. Usage
  3. Contributing *Code Style Guidelines *Tests *Publishing *Code Quality *Versioning *JsDoc *Gulp *Demo App *Admin Only Functionality

###Getting Started

  1. Clone the repo
  2. Run npm install

###Usage

  1. Add the NPM dependency tablelist-js-sdk to your package.json
  2. Add the Js SDK script to your html file, and add Js SDK dependencies to your html file:
<script src="../node_modules/angular/angular.min.js"></script>
<script src="../node_modules/angular-resource/angular-resource.min.js"></script>
<script src="../node_modules/angular-cookies/angular-cookies.min.js"></script>

#Contributing ###Code Style Guidelines

  1. Always add JSDoc attributes
  2. Use ES6 wherever possible
  3. Use single quotes instead of double quotes
  4. Always use camel-case for file names and directories. Ex. jsSdk.js not js-sdk.js
  5. Always namespace services, factories, etc... with jsdSdk. Ex. jsSdk.venueService or jsSdk.config
  6. When using Angular's ng-resource always return the promise object Ex.
  login(email, password) {
    return auth.login().$promise;
  }

###Tests

  • Run npm test

###Building

$ gulp release

###Publishing

To publish a new version of SDK to NPM follow these steps:

  1. Make your changes the SDK
  2. Bump the version number in package.json
  3. Write Unit Tests to verify your new code is working properly.

You can also run the Demo App (gulp run-demo) and add new pages to the demo app if you'd like to test any code within an actual browser. Usually testing with Unit Tests will be sufficient, but sometimes it's nice to verify things are working in a real browser/app setting.

  1. That's it! The build system will build and test your code. If the build passes your code will be deployed and published to NPM automagically. The JsDocs will also be regenerated and published to http://tablelist-js-sdk.herokuapp.com/

###Testing

$ gulp test

To run a subset of the tests, use fdescribe. This will skip all other tests.

Just put an f before the group of tests/test you want to run, such that the test block begins with fdescribe(...)

Files must have -test in the name. For example: create-test.js.

Alternatively, you can replace the function describe(.... with describe.only(.....

###Code Quality

  • Run gulp jsquality - this will run jshint and jscs. The build will fail if this task fails.

###Naming Conventions

If an endpoint requires an ID/input of an object that isn't of the current service. Please specify that in the name. For example, to list all venues in a given city:

eventService.listByCityId(cityId)

However, we do not need to specify in the .read function, since it requires the ID of an event.

eventService.read(eventId)

###Versioning

Documentation

Use the JSDocs format for adding documentation

JsDocs can be generated to view all the classes and methods available in the project

  • Run gulp jsdoc to generate the docs
  • Run gulp open-jsdoc to open the results in your browser

Documenting Modules

Example:

/**
 * Booking Service
 *
 * @module booking
 * @submodule booking-service
 */

Documenting Methods

JSDocs format for methods:

Example:

/**
 * Read a booking object
 *
 * @param {String} id - Booking ID to read
 * @param {Object} options
 * @return {Promise}
 */

More info on JSDocs format for methods.

Example: Note the addition of optional fields and

/*
 * Create an organization member
 *
 * @param {Object} options
 * @param {String} options.organizationId - ID of organization to add member in
 * @param {String} options.email - email of member to add
 * @param {String} [options.name] - first name of member to add (optional)
 * @param {String[]} options.venueIds - array of venue IDs member has access to
 * @return {Promise<OrganizationMember>} newly created organization member
 */

You can define return types like Promise<Object> or in this example - a kind of a fake type Promise<OrganizationMember>

###Gulp

  • Run gulp ? to list all Gulp tasks

###Demo App

  • Run gulp run-demo to start a demo app. This can be helpful for debugging issues with the SDK and is a good starting point for applications using the SDK.

###Admin Only Functionality Multiple builds of the SDK are generated. 1 for non-admin, and 1 for admins. The build generated for admins includes functionality that is only available to Tablelist admins. The way this is controlled is by decorating functions with special comments to tell the build process to exclude/include depending on the build type.

Example:

//removeIf(NON_ADMIN_BUILD)

/** @method */
/**
 * @param {Object} options
 * @return {Promise}
 */
create(options) {
  if (!options) throw new Error('jsSdk.commonService - create() - options is required');

  return this._resource.create({}, options).$promise;
}

//endRemoveIf(NON_ADMIN_BUILD)

This function will only be included in the tablelist-js-sdk.admin.js build.

###Adding New Resources When adding new resources follow this pattern:

angular
  .module('jsSdk').service('jsSdk.venue.resource', [
    'jsSdk.resourceFactory', (resourceFactory) => {

      const ENDPOINT = '/venue/:id';
      const PARAM_DEFAULTS = {
        id: '@id'
      };

      let Venue = resourceFactory(ENDPOINT, PARAM_DEFAULTS, {});

      return Venue;
    }
  ]);

The endpoint for your resource should always include the id param, and be sure to specify the id param in PARAM_DEFAULTS.

###Caching

js-sdk includes support for caching API calls at the Angular.js Resource level. Use the cacheConfigProvider, and call .cacheResourceEndpoints to specify which endpoints to cache. Example:

angular.module('angularApp').config([
 'jsSdk.cacheConfigProvider',
 (cacheConfigProvider) => {
   cacheConfigProvider
     .cacheResourceEndpoints('jsSdk.venue.resource', [
       'list'
     ]);
 }
]);