baijijs / entity

Expose API fields for endpoint user

Baiji Entity

An elegance way to restrict API outputs for any web frameworks.

Baiji Entity gives you a simple schema for declaring JSON structures thats beats manipulating giant javascript object structures. This is particularly helpful when the generation process is fraught with conditionals and loops.

Installation

npm install baiji-entity

# or

yarn add baiji-entity

Example

const Entity = require('baiji-entity');

// Presume we have a article object that needs to parse
let article = {
  id: 1,
  content: 'article content ...',
  likesCount: 42,
  wordsCount: 12422,
  favoritesCount: 23,
  commentsCount: 578,
  visitors: 15,
  createdAt: 1530003456793,
  updatedAt: 1530008548865,
  author: {
    id: 789,
    name: 'Felix',
    email: '[email protected]',
    articlesCount: 65,
    password: 'xxxxxxx'
  },
  comments: [
    {
      content: 'Hello everyone!',
      createdAt: '2018-03-29T20:45:28-08:00'
    },
    {
      content: 'To you my good sir!',
      createdAt: '2018-04-16T20:23:24-08:00'
    }
  ]
}

// Define an article entity
let articleEntity = new Entity({
  id: Number,
  content: String,
  visitors: Number,
  createdAt: Date,
  updatedAt: Date,
  author: {
    name: String,
    email: String,
  },
  comments: [{
    content: String,
    createdAt: Date
  }]
});

// Parse article data
articleEntity.parse(article);

// Outputs =>
{ id: 1,
  content: 'article content ...',
  visitors: 15,
  createdAt: '2018-06-26T08:57:36.793Z',
  updatedAt: '2018-06-26T10:22:28.865Z',
  author: {
    name: 'Felix',
    email: '[email protected]'
  },
  comments: [
    {
      content: 'Hello everyone!',
      createdAt: '2018-03-30T04:45:28.000Z'
    },
    {
      content: 'To you my good sir!',
      createdAt: '2018-04-17T04:23:24.000Z'
    }
  ]
}

// See, only those fields specified will be exposed and formatted as we expect

Usage

General configurations

Entity provide two global options that will help to simplify the entity definition.

Entity.types

Set default value to different types. Defaults are undefined for all kinds of types.

NOTE: Only date type has format property, all types have default property.

And format property have two limit options: iso and timestamp.

Example:

Entity.types = {
  string: { default: '' },
  number: { default: 0 },
  boolean: { default: false },
  date: { format: 'iso', default: '' },
  object: { default: {} }
};

Entity.renames

Set default config to alter one key's name to another.

Example:

Entity.renames = { _id: 'id' };

const entity = new Entity({
  _id: String
});

console.log(entity.parse({}));

// output => { id: '' }

Same effect as:

const entity = new Entity({
  _id: { type: 'string', as: 'id', default: '' }
});

console.log(entity.parse({}));

// output => { id: '' }

Defining Entities

Normal Definition

const Entity = require('baiji-entity');

const entity = new Entity({
  name: { type: 'string' },
  sex: { type: 'number', as: 'gender' },
  age: { type: 'number', default: 18 },
  isAdult: {
    type: 'boolean',
    get(obj) {
      return obj.age >= 18 ? true : false;
    }
  },
  girlfriend: {
    type: 'boolean',
    default: true,
    if: function(obj) {
      return obj.age >= 16 ? true : false;
    }
  },
  social: {
    type: 'object',
    using: SomeEntity,
    get(obj, options) {
      return {};
    }
  }
});

Simpler Definition

You can use the simpler syntax to define an entity. Attention please set Global config at project initialization.

const Entity = require('baiji-entity');
const entity = new Entity({
  // like: { type: 'string', as: 'id', default: '' }
  _id: String,
  // like: { type: 'string', default: '' }
  name: String,
  // like: { type: 'number', default: 0 }
  age: Number,
  // like: { type: 'date', format: 'iso', default: '' }
  birthday: Date
});

// Or you can have a different default value
const entity = new Entity({
  // like: { type: 'string', default: 'baiji' }
  name: 'baiji',
  // like: { type: 'number', default: 10 }
  age: 10,
});

Static methods

Entity.isEntity(entity)

Check if an entity object is instance of Entity object

Entity.isEntity(entity);

Entity.clone(entity)

Clone provided Entity object

Entity.clone(entity);

Entity.copy(entity)

An alias for .clone method

Entity.copy(entity);

Entity.extend(entity, object)

Extend a new Entity object based on provided one and object

Entity.extend(entity, { name: true });

Instance methods

entity.isEntity(entity)

For Entity instance this always return true

entity.isEntity(entity);

entity.pick(string|object)

Pick specific fields from current entity, return a new entity

const entity = new Entity({
  id: String,
  name: String,
  age: Number,
  children: [{
    id: String,
    sex: Number
  }]
});

const pickedEntity = entity.pick('id name children{ id }');
/**
 * => entity
 * {
 *   id: String,
 *   name: String,
 *   children: [{ id: String }]
 * }
 */

entity.add(field1[, field2, ..., fieldn, options, fn])

Add fields with corresponding value or function for final exposure, method could be chained

Options:

• as: rename the field to exposure
• value: set specific value for field
• default: set default value for undefined field
• type: normalize field value according to type option, case ignored, see more at https://github.com/baijijs/normalizer
• format: only applied for valid Date value, which automatically turn type option to string, now support format of iso and timestamp, case ignored
• if: set a filter to determine if the field should be return, accept an object and return boolean
• using: use another Entity instance as the filed value
• get: function, for further manipulation of inputed object according to options

fn optional, for further manipulation of inputed object according to options

let entity = new Entity();
entity.add('name', { type: 'string' });
entity.add('name', { type: 'string', as: 'fullname' });
entity.add('sex', { type: 'number', value: 'male' });
entity.add('isAdult', { type: 'boolean' }, function(obj) { return obj && obj.age >= 18; });
entity.add('isAdult', { type: 'boolean', get(obj) { return obj && obj.age >= 18; } });
entity.add('activities', { using: myActivityEntity });
entity.add('extraInfo', { using: myExtraInfoEntity });
entity.add('condition', { if: function(obj, options) { return true } });

entity.safeAdd(field1[, field2, ..., fieldN, options, fn])

Same as .add function, return a new entity instead of modifying itself

entity.expose

An alias method for .add

entity.safeExpose

An alias method for .safeAdd

entity.unexpose

Unexpose certain field, used for extended entity

entity.parse(object[, options, converter])

Parse an input object according to Entity exposure definition

Options:

• overwrite: for fields with value of undefined, if default value is provided from Entity definition, then set this field value of input object with default value

// Require baiji-entity module
const Entity = require('baiji-entity');

// Define userEntity
const userEntity = new Entity({
  name: { type: 'string' },
  city: { type: 'string' },
  age: { type: 'number', default: 0 },
  gender: { type: 'string', default: 'unknown' },
  isAdult: [{ type: 'boolean', default: false }, function(obj, options) {
    return (obj && obj.age >= 18 ? true : false);
  }],
  points: { type: 'number', value: 100, if: function(obj, options) { return obj && obj.age >= 18; } },
  description: { as: 'introduction', type: 'string', default: '' },
  isSignedIn: {
    type: 'boolean',
    get(obj, options) {
      return (options && options.isSignedIn ? true : false);
    }
  },
  birthday: { default: '', type: 'date', format: 'iso' }
});

// Parse source data
userEntity.parse({
  name: 'Felix Liu',
  age: 18,
  city: 'Shanghai',
  birthday: new Date('2015-10-10 10:00:00'),
  description: 'A programmer who lives in Shanghai',
  password: 'xxxxxxx'
}, { isSignedIn: true });

// The parsed output will be as below ⬇️

{
  name: 'Felix Liu',
  city: 'Shanghai',
  age: 18,
  gender: 'unknown',
  isAdult: true,
  points: 100,
  introduction: 'A programmer who lives in Shanghai',
  isSignedIn: true,
  birthday: '2015-10-10T02:00:00.000Z'
}

License

MIT

entity's Issues

Todos

• Promise support
• Entity inheritance