Naively Programmable Module

    jsonbox-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.4 • Public • Published

    jsonbox-client

    This is an isomorphic JavaScript module which includes all of the tools you need to help you interact with a jsonbox server (like jsonbox.io). It has first-class TypeScript support.

    Install

    npm install jsonbox-client

    Use

    Import

    Your module specifier depends on your environment. Examples are included below.

    import (ES modules)

    Environments: browser, Node.js >= 13.x.x using ES modules

    import {
      Jsonbox,
      combineFilters,
      generateApiKey,
      valueOf,
    } from 'MODULE_SPECIFIER_GOES_HERE';

    Specifier examples:

    • Browser (local): ./node_modules/jsonbox-client/dist/index.js (or another path to where you've placed the module file)
    • Browser (CDN): https://unpkg.com/jsonbox-client (or another URL which resolves the module code)
    • Node: jsonbox-client

    require (CommonJS)

    Environments: Node.js >=12.x.x using CommonJS modules

    const {
      Jsonbox,
      combineFilters,
      generateApiKey,
      valueOf,
    } = require('MODULE_SPECIFIER_GOES_HERE');

    Specifier examples:

    • Node >13.x.x: jsonbox-client
    • Node 12.x.x: jsonbox-client/commonjs

    Imports

    Jsonbox

    This is the main import. It helps you to send and receive data from your jsonbox server. To get started, pass your configuration options to create a new Jsonbox instance:

    import {Jsonbox} from 'jsonbox-client';

    Signatures

    new Jsonbox(boxIdstring); // -> Jsonbox class instance
     
    new Jsonbox(boxIdstring, {apiKey?: string, origin?: string}); // -> Jsonbox class instance

    Examples

    At minimum, you must provide a box ID:

    const boxId = 'box_2c846c501950dab86062';
    const jsonbox = new Jsonbox(boxId);

    You can also provide some options:

    const boxOptions = {
      apiKey: 'b8ceca96-ebb8-4a2a-9a21-758c12ca6b54', // only used with protected boxes
      origin: 'https://jsonbox.io', // this is the default, but you could also connect to a different jsonbox server
    };
     
    const jsonbox = new Jsonbox(boxId, boxOptions);

    If provided, the apiKey must be a valid UUID. To generate one, use the generateApiKey import.

    Jsonbox methods

    These are all async. In order to reduce boilerplate code in the documentation examples, they don't show the async context, but please take note of the use of await keywords.

    In the event of bad responses (no network connection / status.ok === false / etc.), these methods will reject with an error object containing an additional response property. The use of try/catch is recommended when using these methods in order to handle the possibility of such errors.

    const {create, meta, read, remove, update} = jsonbox;
    create

    Create one or more records (objects) in a jsonbox (an array of objects)

    const {create} = jsonbox;

    Signatures

    create(recordobject, collection?: string); // -> Promise resolving the record with metadata
     
    create(recordsobject[], collection?: string); // -> Promise resolving the array of records with metadata

    Examples

    Create a single record:

    const person = {name: 'Jacob'};
    const result = await create(person);
    // result
     
    {
      _id: '5e7ac65299ed160017dc2c81',
      name: 'Jacob',
      _createdOn: '2020-03-25T02:47:46.525Z'
    }

    Create a single record in a collection:

    const wizard = {name: 'Harry', house: 'Gryffindor', born: 1980};
    const collection = 'wizards';
    const result = await create(wizard, collection);
    // result
     
    {
      _id: '5e7ac67499ed160017dc2c82',
      name: 'Harry',
      house: 'Gryffindor',
      born: 1980,
      _createdOn: '2020-03-25T02:48:20.278Z'
    }

    Create multiple records at once in a collection:

    const wizards = [
      {name: 'Ron', house: 'Gryffindor', born: 1980},
      {name: 'Draco', house: 'Slytherin', born: 1980},
      {name: 'Cedric', house: 'Hufflepuff', born: 1977},
    ];
    const collection = 'wizards';
    const result = await create(wizards, collection);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z'
      },
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z'
      },
      {
        _id: '5e7ac69799ed160017dc2c85',
        name: 'Cedric',
        house: 'Hufflepuff',
        born: 1977,
        _createdOn: '2020-03-25T02:48:55.778Z'
      }
    ]
    update

    Update a record

    const {update} = jsonbox;

    Signatures

    update(idstring, recordobject); // -> Promise resolving an object with a status message

    Examples

    const id = '5e7ac69799ed160017dc2c85';
    const updatedWizard = {name: 'Cedric', house: 'Hufflepuff', born: 1977, died: 1995};
    const result = await update(id, updatedWizard);
    // result
     
    { message: 'Record updated.' }
    read

    Read one or more records

    const {read} = jsonbox;

    Signatures

    read(idstring); // -> Promise resolving a record with metadata
     
    read(); // -> Promise resolving an array of records with metadata
     
    read({collection?: string, filter?: string, limit?: number, skip?: number, sort?: string}); // -> Promise resolving an array of records with metadata

    Examples

    Read a single record by its ID:

    const id = '5e7ac69799ed160017dc2c83';
    const result = await read(id);
    // result
     
    {
      _id: '5e7ac69799ed160017dc2c83',
      name: 'Ron',
      house: 'Gryffindor',
      born: 1980,
      _createdOn: '2020-03-25T02:48:55.777Z',
      _collection: 'wizards'
    }

    Read all records:

    const result = await read();
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c85',
        name: 'Cedric',
        house: 'Hufflepuff',
        born: 1977,
        died: 1995,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _updatedOn: '2020-03-25T03:01:59.698Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac65299ed160017dc2c81',
        name: 'Jacob',
        _createdOn: '2020-03-25T02:47:46.525Z'
      }
    ]

    Read all records in a collection:

    const readOptions = {collection: 'wizards'};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z'
      },
      {
        _id: '5e7ac69799ed160017dc2c85',
        name: 'Cedric',
        house: 'Hufflepuff',
        born: 1977,
        died: 1995,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _updatedOn: '2020-03-25T03:01:59.698Z'
      },
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z'
      },
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z'
      }
    ]

    Limited number of records:

    const readOptions = {limit: 2};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c85',
        name: 'Cedric',
        house: 'Hufflepuff',
        born: 1977,
        died: 1995,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _updatedOn: '2020-03-25T03:01:59.698Z',
        _collection: 'wizards'
      }
    ]

    Skip some records:

    const readOptions = {skip: 2};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac65299ed160017dc2c81',
        name: 'Jacob',
        _createdOn: '2020-03-25T02:47:46.525Z'
      }
    ]

    Sort records by field:

    const readOptions = {sort: 'house'};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac65299ed160017dc2c81',
        name: 'Jacob',
        _createdOn: '2020-03-25T02:47:46.525Z'
      },
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c85',
        name: 'Cedric',
        house: 'Hufflepuff',
        born: 1977,
        died: 1995,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _updatedOn: '2020-03-25T03:01:59.698Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _collection: 'wizards'
      }
    ]

    Filter records by value(s):

    (See jsonbox#filtering for syntax details). For easier filter matching, use the provided imports combineFilters and valueOf.

    const readOptions = {filter: 'born:=1980,name:*a*'};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z',
        _collection: 'wizards'
      }
    ]

    Combine read options:

    const readOptions = {filter: 'house:Gryffindor', sort: 'name'};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac67499ed160017dc2c82',
        name: 'Harry',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:20.278Z',
        _collection: 'wizards'
      },
      {
        _id: '5e7ac69799ed160017dc2c83',
        name: 'Ron',
        house: 'Gryffindor',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.777Z',
        _collection: 'wizards'
      }
    ]
    delete / remove

    Delete one or more records

    jsonbox.delete and jsonbox.remove are the same method. jsonbox.remove is offered because the delete operator already exists in the global scope.

    const {remove} = jsonbox;

    Signatures

    remove(idstring); // -> Promise resolving an object with a status message
     
    remove(idsstring[]); // -> Promise resolving an array of objects with properties related to individual delete requests
     
    remove({filter: string}); // -> Promise resolving an object with a status message

    Examples

    Delete a single record by its ID:

    const id = '5e7ac69799ed160017dc2c85';
    const result = await remove(id);
    // result
     
    { message: 'Record removed.' }

    Delete multiple records by their IDs:

    This actually makes multiple concurrent delete requests using Promise.allSettled and returns the mapped results in an array. This is a unique call which does not reject even on network failure. Check the results for the status of the individual delete requests.

    const ids = [
      '5e7ac65299ed160017dc2c81',
      '5e7ac69799ed160017dc2c84',
    ];
    const result = await remove(ids);
    // result
     
    [
      { id: '5e7ac65299ed160017dc2c81', success: true },
      { id: '5e7ac69799ed160017dc2c84', success: true }
    ]

    Delete one or more records using a filter:

    const deleteOptions = {filter: 'house:Gryffindor'};
    const result = await remove(deleteOptions);
    // result
     
    { message: '2 Records removed.' }
    meta

    Read the metadata for your box

    const {meta} = jsonbox;

    Signatures

    meta(); // -> Promise resolving an object with the box's metadata

    Examples

    const result = await meta();
    // result
     
    {
      _count: 5,
      _createdOn: '2020-03-25T02:47:46.525Z',
      _updatedOn: '2020-03-25T03:01:59.698Z'
    }

    combineFilters and valueOf

    These are functions to help you compose filters using natural language instead of having to remember the jsonbox-specific syntax.

    import {combineFilters, valueOf} from 'jsonbox-client';

    Signatures

    combineFilters(...filtersstring[]); // -> A combined, jsonbox-formatted filter string
    // All of these return a jsonbox-formatted filter string
     
    valueOf(keystring).endsWith(valuestring);
     
    valueOf(keystring).includes(valuestring);
     
    valueOf(keystring).is(valueboolean | number | string);
     
    valueOf(keystring).isGreaterThan(valuenumber);
     
    valueOf(keystring).isGreaterThanOrEqualTo(valuenumber);
     
    valueOf(keystring).isLessThan(valuenumber);
     
    valueOf(keystring).isLessThanOrEqualTo(valuenumber);
     
    valueOf(keystring).startsWith(valuestring);

    Examples

    Single filter:

    const filter = valueOf('house').is('Gryffindor');
     
    filter === 'house:Gryffindor'; // -> true

    Combine multiple filters:

    const filter = combineFilters(
      valueOf('house').endsWith('in'),
      valueOf('name').includes('a'),
      valueOf('born').isGreaterThanOrEqualTo(1980),
    );
     
    filter === 'house:*in,name:*a*,born:>=1980'; // -> true
     
    const readOptions = {filter};
    const result = await read(readOptions);
    // result
     
    [
      {
        _id: '5e7ac69799ed160017dc2c84',
        name: 'Draco',
        house: 'Slytherin',
        born: 1980,
        _createdOn: '2020-03-25T02:48:55.778Z',
        _collection: 'wizards'
      }
    ]

    generateApiKey

    When using an API key, jsonbox requires it to be a valid UUID. This function generates a randomized, RFC 4122-compliant version-4 UUID.

    import {generateApiKey} from 'jsonbox-client';

    Signatures

    generateApiKey(); // -> random UUID in the format 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'

    Examples

    const apiKey = generateApiKey():
    // apiKey
     
    'fef67c1a-845a-4b7b-8a86-f6d70faadfd0'

    Install

    npm i jsonbox-client

    DownloadsWeekly Downloads

    5

    Version

    0.1.4

    License

    MIT

    Unpacked Size

    33.8 kB

    Total Files

    8

    Last publish

    Collaborators

    • jsejcksn