etched v1.0.0

@etchedjs/etched

Etches your JS objects in stone

A utility to easily create some immutable objects by a chainable derivation, without any dependencies.

Install

npm i @etchedjs/etched

Alternatively, in a browser, you can use it from the CDN:

import etched from 'https://unpkg.com/@etchedjs/etched@latest/etched.js'

Usage

Create a model

import etched from '@etchedjs/etched'

const model = etched.model(null, {
  withLink (link) {
    return etched.with(this, { link })
  },
  withName (name) {
    return etched.with(this, { name })
  }
})

Extend a model

const versioned = etched.model(model, {
  withVersion (version) {
    return etched.with(this, { version })
  }
})

Create a model instance with using the model methods

const module = model
  .withLink('https://www.npmjs.com/package/@etchedjs/etched')
  .withName('@etched/etched')

console.log(module)
/*
{
  link: "https://www.npmjs.com/package/@etchedjs/etched",
  name: "@etched/etched"
}
*/

Create a model instance from etched

const module = etched.from(model, {
  link: 'https://www.npmjs.com/package/@etchedjs/etched',
  name: '@etched/etched'
})

console.log(module)
/*
{
  link: "https://www.npmjs.com/package/@etchedjs/etched",
  name: "@etched/etched"
}
*/

Definition

The mutators

A mutator is a camel cased method, prefixed with a with method and followed by the property name added to the returned instance copy.

etched.model({
  withVersion (version) {
    return etched.with(this, { version })
  }
})

API

etched.model

Creates a new immutable model, based on optional prototype and/or mixin.

It also acts as an instance.

Use it to declare your mutators, properties and methods.

/**
 * @template prototype
 * @template mixin
 * @param {instance<Object>|null} [prototype=null]
 * @param {mixin<{}>} [mixin={}]
 * @return {Readonly<instance&mixin>}
 */
const model = etched.model(prototype, mixin)

etched.with

Creates a new immutable instance, based on a previous one, with any properties passed by the props object.

It ignores the properties that are already non-nullish and inherited from the model.

/**
 * @template target
 * @template props
 * @param {target<Object>} target
 * @param {props<{}>} [props={}]
 * @return {Readonly<target&props>}
 */
const instance = etched.with(target, props)

etched.from

Like the etched.with method, it provides a new instance by calling all the mutators related to the props properties.

It ignores the properties that are already non-nullish and inherited from the model.

/**
 * @template target
 * @template props
 * @param {target<Object>} target
 * @param {props<{}>} [props={}]
 * @return {Readonly<target&props>}
 */
const instance = etched.from(target, props)

Licence

MIT