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

@liquid-labs/resource-item

v1.0.0-alpha.4

Published

Provides configurable 'Item' class to wrap plain data object for data protection and sanitization.

Downloads

7

Readme

resource-item

coverage: 91% Unit tests

Provides configurable 'Item' class to wrap plain data object for data protection and sanitization. This is useful when you have a bunch of plain data objects and you don't want to write specific classes for each type, but you do want to protect and/or sanitize the data.

'resource-item' can be used on it's own, but also works with 'resource-model' which defines ItemManager to manage a collection of Items and Model which can be used to group and coordinate multiple ItemManagers or sub-Models. Together, these projects provide a complete resource management infrastructure.

Installation

npm i @liquid-labs/resource-item

Usage

import { Item } from '@liquid-labs/resource-item'

// declare your data-type specific class
const Person = class extends Item {} // you must sub-class Item and cannot create Item's directly

// configure the class you just declared
Item.bindCreationConfig({
  itemClass : Foo, // the class to configure
  itemName  : 'person', // how singular items should be named
  itemsName : 'people', // how multiple items shoud be named
  keyField  : 'email', // the key field
  allowSet  : ['nickname']
})

const person = new Person({ email: '[email protected]', givenName: 'John', nickname: 'Johnny Boy' })

// all Items have an ID
console.log(person.id) // [email protected]
// you can access all data fields directly
console.log(person.givenName) // John
// you can set nickname because it's in tho 'allowSet' set
person.nickname = 'Johnny Johnny John John'
// the following, however, will raise an exeption becasue data is protected by default
person.email = '[email protected]'

Purpose and goals

The Item class is conceived of as the standard basis for a CRUD system dealing with multiple data types and user input data. The goals concrete of the of the Item class are:

  1. Provide a simple way to quickly emulate custom data wrapper classes.
  2. Protect the underlying data from change (default deny set operations and clone all object data in and out).
  3. Provide a consistent 'id' field across all classes.
  4. Provide a proxy layer to allow users to optionally inspect and intercept get/set operations.

Reference

constructor/new Items:
Items cannot be instantiated directly and must be sub-classed. Instantiating the subclass will result in the return of a Proxy object that wraps the underlying class. The proxy instance behaves just as the underlying class would in all cases except as noted in this documentation.

All 'get' operations:
Can access properties defined directly on the object and also properties in the plain data object used to initialize the class. Propertise defined directly on the object will override/hide properties of the same name in the data object. Any 'object' values are cloned to protect the underlying data from inadvertent change.

All 'set' operations:
Can only set properties directly defined on the object at instantiation or properties in the data object which have been configured writeble by allowSet in the Item.bindCreationConfig() configuration. You cannot add to or set properties on the underlying object that were not present at instaantiation. Object values are cloned so subsequent changes in the (now) external data will not affect the stored data.

Item.bindCreationConfig(config):
Takes a single object with the following fields:

  • itemClass: (req, Class) the class to bind the itemConfig configuration to
  • itemName: (req, string) how to refer to singular data items in user messages
  • itemsName: (req, string) how to refer to multiple data items in user messages
  • keyField:: (req, stirng) the name of the 'key field' in the data; if not 'id', an 'id' field will be created
  • dataCleaner (opt, function) a function to transforms data in preparation for display or export. E.g., to remove cached or ephemeral values. Signature: (data)
  • dataFlattener: (opt, function) a function to flatten nested data. E.g., when outputting data in a CSV (tabular) format. Signature: (data)
  • getWatchers: (opt, array of functions) an array of functions which are each executed at the proxy layer prior to returning from a get operation. Can be used to monitor access and also interrupt calls by raising an error. The function recieves a data object with fields: data (the underlying data objec), target (the target object), property (name or Symbol of the property to get), and receiver (either the proxy or an object that inherits from the proxy).
  • idNormalizer: (opt, function) a function taking a single argument—the unsatizide ID—and returns a "sanitized"/normalized ID. E.g., if we have a keyField : 'email' and we want all emails to be all lower case, then we would have idNormizer : (email) => email.toLowerCase(). Given email '[email protected]', then item.email would result in '[email protected]', but item.id would be '[email protected]'.
  • setWatchers: (opt, array of functions) an array of functions which are each executed at the proxy layer prior to updating data in a set operation. Can be used to monitor changes and also interrupt calls by raising an error. The function recieves a data object with fields: data (the underlying data objec), target (the target object), property (name or Symbol of the property to get), value (the new value), and receiver (either the proxy or an object that inherits from the proxy).