@jaysalvat/smart-model

 ___  __  __    __    ____  ____  __  __  _____  ____  ____  __   
/ __)(  \/  )  /__\  (  _ \(_  _)(  \/  )(  _  )(  _ \( ___)(  )  
\__ \ )    (  /(__)\  )   /  )(   )    (  )(_)(  )(_) ))__)  )(__ 
(___/(_/\/\_)(__)(__)(_)\_) (__) (_/\/\_)(_____)(____/(____)(____)

SmartModel

Javascript object model.

• ~1.5Kb gzipped
• Value transformation
• Value format
• Value type validation
• Value content validation (required, custom rules)
• Default value
• Readonly properties
• Virtual property
• Throw exception (or not) if invalid
• Nested models
• Live cycle events
• Better documentation ^^

Works on modern browsers. Check if tests pass on your browser.

Install

Provided formats are IFFE, ESM, CJS and UMD, all minified.

NPM

npm install @jaysalvat/smart-model

import SmartModel from '@jaysalvat/smart-model'

Module from CDN

import SmartModel from 'https://unpkg.com/@jaysalvat/smart-model@latest/build/smart-model.esm.min.js'

The old way

<script src="https://unpkg.com/@jaysalvat/smart-model@latest/build/smart-model.min.js"></script>

Usage

Better documentation soon...

function readingTime(text) { /*...*/ }

const Post = SmartModel.create('Post', {
    title: {
      required: true,
      type: String,
    },
    body: {
      required: true,
      type: String,
      rule: {
        'tooShort': (value) => value.length < 100,
        'tooLong': (value) => value.length > 1000,
      }
    },
    createdAt: {
      type: Date,
      default: new Date(),
      transform: (value) => new Date(value),
      format: (value) => value.toLocaleString()
    },
    updatedAt: {
      type: Date,
      default: new Date(),
      transform: (value) => new Date(value),
      format: (value) => value.toLocaleString()
    },
    // Nested model
    author: {
      required: true,
      type: {
        firstname: {
          required: true,
          type: String
        },
        lastname: {
          required: true,
          type: String,
          transform: (value) => value.toUpperCase()
        },
        fullname: (author) => author.firstname + ' ' + author.lastname
      }
    },
    // Virtual properties
    bodyLength: (post) => post.body.length, 
    readingTime: (post) => readingTime(post.body)
  }, 
  // Settings
  {
    strict: true,
    exceptions: true,
    // Events
    methods: {
      $onUpdate() {
        this.updatedAt = new Date()
      }
    }
  }
)

const post = new Post({
  title: 'My new post',
  body: 'Very long post...',
  author: {
    firstname: 'James',
    lastname: 'Hetfield'
  }
})

console.log(post)

Post {
  createdAt: 2020-01-31T09:50:00.000Z,
  updatedAt: 2020-01-31T09:50:00.000Z,
  title: 'My new post',
  body: 'Very long post...',
  author: Author {  
    firstname: 'James', 
    lastname: 'Hetfield' 
  }
}

console.log(post.author.fullname)
console.log(post.createdAt)
console.log(post.readingTime)

James HETFIELD
01/31/2020, 9:50:00 AM
12 minutes

Documentation

Schema

Options for property:

Option	Type	Description
default	any	Default value if the property is undefined
format	fn	Function to format the value when its read
readonly	bool	Boolean to prevent a value to be overwritten
required	bool	Boolean to prevent a value to be empty
rule	object	Object which contains the validation rules
transform	fn	Function to transform the value when its written
type	any	Required type of a value

default

The default value if the property is undefined.

format

A function to format the value when its read.

const Event = SmartModel.create('Event', {
  name: { 
    type: String 
  },
  date: {
    type Date,
    format: (value) => new Date(value).toLocaleString()
  }
})

** Use with caution **, it could be unexpected effects when object are copied (the formated value becomes the new value). Consider using a computed property instead.

readonly

The value can't be overwritten after init.

required

The value is required. See settings.empty for the empty value check function.

rule

An object which contains the validation rules Multiple rules of validation can be set on a property.

const Discount = SmartModel.create('Discount', {
  percent: {
    type: Number,
    rule: {
      'min': {value) => value < 0,
      'max': {value) => value > 100
    }
  }
})

An exception is throw with the rule code when the condition if true.

transform

Function to transform the value when its written.

const Event = SmartModel.create('Event', {
  name: { 
    type: String 
  },
  date: {
    type Date,
    transform: (value) => new Date(value)
  }
})

type

The required type of a value. Type can be Array, Boolean, Date, Function, Object, String or a class. If a schema is set as a type, a nested model will be created.

const Post = SmartModel.create('Post', {
  title: { 
    type: String 
  },
  body: { 
    type: String 
  },
  Date: { 
    type: Date 
  },
  author: {
    type {
      firstname: {
        type: String
      },
      lastname: {
        type: String
      }
    }
  }
})

An existing model can be set as a type in order to nest this model.

const Author = SmartModel.create('Author', {
  firstname: {
    type: String
  },
  lastname: {
    type: String
  }
})

const Post = SmartModel.create('Post', {
  title: { 
    type: String 
  },
  body: { 
    type: String 
  },
  Date: { 
    type: Date 
  },
  body: { 
    type: string 
  },
  author: {
    type: Author
  }
})

Settings

Option	Type	Default	Description
empty	fn	fn	Function to check if a value is empty if required
exceptions	bool/object	object	Object of exceptions settings
methods	object	object	Object of custom methods
strict	bool	false	Boolean to set only properties defined in the schema

empty

The function to check if a value is empty or not. Default function is the function below.

(value) => value === '' || value === null || value === undefined

strict

If strictset to true, only properties defined in the schema will be set.

exceptions

Any type of thrown exceptions can be set individually. By default the exceptions settings is an object these default values:

Option	Type	Default
readonly	bool	false
required	bool	true
rule	bool	true
strict	bool	false
type	bool	true

If exceptions is set to true, all types of exceptions will be thrown. If exceptions is set to false, all types of exceptions will be thrown.

methods

Custom methods can be added to model. Those methods will be accessible in any instances of the model.

const Article = SmartModel.create('Article', {
  body: {
    type: String
  }
}, {
  methods: {
    excerpt(limit = 10) {
      return this.body.substr(0, limit) + '…'
    }
  }
})

Native methods

$get

Returns standard JSON from the model content.

const article = new Article()

const json = article.$get()

$post / $put

Replaces the model properties. Existing properties are deleted. An exception is thrown if the properties are required.

const article = new Article()

article.$put({
  title: 'My article'
})

$patch

Same as $post / $put, but only passed properties are updated.

$delete

Delete a or muliple properties of the model. An exception is thrown if the properties are required.

const article = new Article()

article.$delete([ 'title', 'body' ])

$check

Static method. Returns an array of potential errors if a payload where passed to the model.

const errors = Article.$check(payload)

$hydrate

Static method. Turns an object or an array of objects into models. Useful with API responses.

fetch('https://api.com/post')
  .then(response => response.json())
  .then(response => Post.$hydrate(response))
  .then(response) => { /* Array of hydrated Post models */ }

fetch('https://api.com/post/1234')
  .then(response => response.json())
  .then(response => Post.$hydrate(response))
  .then(response) => { /* Hydrated Post  model */ }

Hooks

Hooks are triggered before and after properties are set, get, updated or deleted.

const User = SmartModel.create('User', {
  username: {
    type: String
  }
}, {
  methods: {
    $onBeforeDelete() {}
    $onBeforeGet() {}
    $onBeforeSet() {}
    $onBeforeUpdate() {}
    $onDelete() {}
    $onGet() {}
    $onSet() {}
    $onUpdate() {}
  }
})

Dev

Dev mode

npm run dev

Build

npm run build

Lint

npm run lint

Fix lint errors

npm run lint:fix

Tests

npm run test

npm run test:watch

npm run test:browser

Bump version and publish to NPM

npm run release

npm run release:patch

npm run release:minor

npm run release:major