functional-models 2.0.7 → 2.0.11

package/README.md

@@ -4,66 +4,272 @@
 ![Feature Tests](https://github.com/monolithst/functional-models/actions/workflows/feature.yml/badge.svg?branch=master)
 [![Coverage Status](https://coveralls.io/repos/github/monolithst/functional-models/badge.svg?branch=master)](https://coveralls.io/github/monolithst/functional-models?branch=master)
 
-Love functional javascript but still like composing objects/models? This is the library for you.
-This library empowers the creation of pure JavaScript function based models that can be used on a client, a web frontend, and/or a backend all the same time. Use this library to create readable, read-only, models.
+Love functional javascript/typescript but still like composing objects/models? This is the library for you.
 
-## Example Usage
+This library empowers the creation of pure JavaScript function based models that can be used on a client, a web frontend, and/or a backend all the same time. Use this library to create models that can be reused everywhere.
+
+This library is fully supportive of both Typescript and Javascript. In fact, the typescript empowers some really sweet dynamic type checking, and autocomplete! It handles validation as well.
+
+Functional Models was born out of the enjoyment and power of working with Django models.
+
+# Primary Features
+- Define models that have properties, methods, and methods on the model itself.
+- Create instances of models 
+- Validate model instances
+- ORM ready via the functional-models-orm package, with DynamoDb, Mongo, in-memory datastores supported.
+- Many common properties out of the box.
+- Supports foreign keys, 1 to 1 as well as 1 to many (via an Array).
+- Supports custom primary key name. (id is used by default)
+
+## Simple JavaScript Example Usage
 
     const {
-      field,
-      constantValueField,
-      textField,
-      dateField,
-      integerField,
-      uniqueId,
-      createModel,
-      validation,
-    }= require('functional-models')
-
-    const Truck = createModel({
-      type: constantValueField('truck'),
-      id: uniqueId({required: true}),
-      make: textField({ maxLength: 20, minLength: 3, required: true}),
-      model: textField({ maxLength: 20, minLength: 3, required: true}),
-      color: textField({ maxLength: 10, minLength: 3, validators: [
-        validation.meetsRegex(/Red/),
-      ]}),
-      year: integerField({ maxValue: 2500, minValue: 1900}),
-      lastModified: dateField({ autoNow: true}),
+      BaseModel: Model,
+      DateProperty,
+      NumberProperty,
+      TextProperty,
+    } = require('functional-models')
+
+    // Create your model. Standard is to use a plural name.
+    const Trucks = Model('Trucks', {
+      properties: {
+        // id: UniqueId(), # this property is provided for free!
+        make: TextProperty({ maxLength: 20, minLength: 3, required: true}),
+        model: TextProperty({ maxLength: 20, minLength: 3, required: true}),
+        color: TextProperty({ 
+          maxLength: 10,
+          minLength: 3,
+          choices: ['red', 'green', 'blue', 'black', 'white'],
+        }),
+        year: NumberProperty({ maxValue: 2500, minValue: 1900}),
+        lastModified: DateProperty({ autoNow: true}),
+      }
     })
 
+    // Create an instance of the model.
+    const myTruck = Trucks.create({ make: 'Ford', model: 'F-150', color: 'white', year: 2013})
 
-    const myTruck = Truck({ make: 'Ford', model: 'F-150', color: 'White', year: 2013})
 
-    console.log(await myTruck.getId())     // a random uuid
-    console.log(await myTruck.getMake())   // 'Ford'
-    console.log(await myTruck.getModel())  // 'F-150'
-    console.log(await myTruck.getColor())  // 'White'
-    console.log(await myTruck.getYear())   // 2013
+    // Get the properties of the model instance.
+    console.log(await myTruck.get.id())     // a random uuid NOTE: this is a promise by default
+    console.log(myTruck.get.make())   // 'Ford'
+    console.log(myTruck.get.model())  // 'F-150'
+    console.log(myTruck.get.color())  // 'white'
+    console.log(myTruck.get.year())   // 2013
 
-    const asJson = await myTruck.functions.toJson()
-    console.log(asJson)
+    // Get a raw javascript object representation of the model.
+    const obj = await myTruck.toObj()
+    console.log(obj)
     /*
     {
       "id": "a-random-uuid",
       "make": "Ford",
       "model": "F-150",
-      "color": "White",
+      "color": "white",
       "year": 2013
     }
     */
 
-    const sameTruck = Truck(asJson)
-    console.log(await sameTruck.getId())     // same uuid as above
-    console.log(await sameTruck.getMake())   // 'Ford'
-    console.log(await sameTruck.getModel())  // 'F-150'
-    console.log(await sameTruck.getColor())  // 'White'
-    console.log(await sameTruck.getYear())   // 2013
+    // Create a copy of the model from the raw javascript object.
+    const sameTruck = Truck.create(obj)
+    console.log(await myTruck.get.id())     // same as above.
+    console.log(myTruck.get.make())   // 'Ford'
+    console.log(myTruck.get.model())  // 'F-150'
+    console.log(myTruck.get.color())  // 'white'
+    console.log(myTruck.get.year())   // 2013
 
-    // Validation
-    const errors = await sameTruck.functions.validate.model() // {}
+    // Validate the model. An empty object, means no errors.
+    const errors = await sameTruck.validate()
+    console.log(errors) // {}
 
-    const newTruck = Truck({ make: 'Ford', model: 'F-150', color: 'White', year: 20130})
-    const errors2 = await newTruck.functions.validate.model()
+    const newTruck = Truck({ make: 'Ford', model: 'F-150', color: 'white', year: 20130})
+    const errors2 = await newTruck.validate()
     console.log(errors2)
-    // {"year": 'Value is too long'}
+
+    // Key is the property's name, and an array of validation errors for that property.
+    // {"year": ['Value is too long']}
+
+
+## Simple TypeScript Example Usage
+While functional-mode3ls works very well and easy without TypeScript, using typescript empowers 
+modern code completion engines to show the properties/methods on models and model instances.
+Libraries built ontop of functional-models is encouraged to use TypeScript, while applications,
+may or may not be as useful, given the overhead of typing. NOTE: Behind the covers functional-models
+typing, is extremely strict, and verbose, which can make it somewhat difficult to work with, but
+it provides the backbone of expressive and clear typing.
+
+
+    import {
+      BaseModel as Model,
+      DateProperty,
+      NumberProperty,
+      TextProperty,
+    } from 'functional-models'
+
+    // Create your model's type
+    type TruckType = {
+      /*
+      * id: string # this property is provided for free. No need to put. If using a custom
+      *     primary key, the property needs to be explicit.
+      */
+      make: string,
+      model: string,
+      color: string,
+      year?: number, // NOTE: Clearly indicates a property is optional. 
+      lastModified: Date,
+    }
+
+    // Create your model. Standard is to use a plural name.
+    const Trucks = Model<TruckType>('Trucks', {
+      properties: {
+        // id: UniqueId(), # this property is provided for free!
+        make: TextProperty({ maxLength: 20, minLength: 3, required: true}),
+        model: TextProperty({ maxLength: 20, minLength: 3, required: true}),
+        color: TextProperty({ 
+          maxLength: 10,
+          minLength: 3,
+          choices: ['red', 'green', 'blue', 'black', 'white'],
+        }),
+        year: NumberProperty({ maxValue: 2500, minValue: 1900}),
+        lastModified: DateProperty({ autoNow: true}),
+      }
+    })
+
+    // Create an instance of the model.
+    const myTruck = Trucks.create({ make: 'Ford', model: 'F-150', color: 'white', year: 2013})
+
+    // Will cause a typescript error because "make" is a string, not a number.
+    const myTruck2 = Trucks.create({ make: 5, model: 'F-150', color: 'white', year: 2013})
+
+    // Will NOT cause a typescript error because year is optional.
+    const myTruck = Trucks.create({ make: 'Ford', model: 'F-150', color: 'white' })
+
+
+    // Will cause a typescript error because model is not implemented, even though its required.
+    const Trucks2 = Model<TruckType>('Trucks2', {
+      properties: {
+        make: TextProperty({ maxLength: 20, minLength: 3, required: true}),
+        color: TextProperty({ 
+          maxLength: 10,
+          minLength: 3,
+          choices: ['red', 'green', 'blue', 'black', 'white'],
+        }),
+        year: NumberProperty({ maxValue: 2500, minValue: 1900}),
+        lastModified: DateProperty({ autoNow: true}),
+      }
+    })
+
+
+## Validation
+Validation is baked into the functional-models framwork. Both individual properties as well as an entire model instance can be covered by validators. The following are the interfaces for a validator. Validation overall is a combination of property validator components as well as model validator components. These components combine together to create a complete validation picture of a model. 
+
+Here is an example of a model instance failing validation.
+
+    // Call .validate() on the model, and await its result.
+    const errors = await myModelInstance.validate()
+
+    console.log(errors)
+
+    /*
+    * {
+    *   "overall": [
+    *     "This is a custom model validator that failed for the entire model",
+    *     "Here is a second model failing message",
+    *   ],
+    *   "aDateProperty": [
+    *     "A value is required",
+    *     "Value is not a date",
+    *   ],
+    *   "anArrayProperty": [
+    *     "BadChoice is not a valid choice",
+    *   ],
+    *   // the 'otherProperty' did not fail, and therefore is not shown here.
+    * }
+    */
+
+
+### Property validators
+A property validator validates the value of a property. The inputs are the value, a model instance, the JavaScript object representation of the model, and optional configurations that are passed into the validator. The return can either be a string error or undefined if there are no errors. This function can be asynchronous, such as doing database lookups.
+
+    /**
+    * An example validator function that only allows the value of 5.
+    * @constructor
+    * @param {string} value - The value to be tested. 
+    * @param {string} instance - A model instance, which can be used for cross referencing.
+    * @param {string} instanceData - The JavaScript object representation of the model.
+    * @param {string} configurations - An optional configuration object passed in as part of validating.
+    * @return {string|undefined} - If error, returns a string, otherwise returns undefined.
+    */
+    const valueIsFiveValidator = (
+      value, // any kind of value.
+      instance, // A ModelInstance,
+      instanceData: JavaScript object representation,
+      configurations: {} 
+    ) =>  {
+      return value === 5
+        ? undefined
+        : 'Value is not 5'
+    }
+
+    /**
+    * An example async validator function that checks a database using an object passed into the configurations.
+    * @constructor
+    * @param {string} value - The value to be tested. 
+    * @param {string} instance - A model instance, which can be used for cross referencing.
+    * @param {string} instanceData - The JavaScript object representation of the model.
+    * @param {string} configurations - An optional configuration object passed in as part of validating.
+    * @return {Promise<string|undefined>} - Returns a promise, If error, returns a string, otherwise returns undefined.
+    */
+    const checkDatabaseError = async (
+      value, // any kind of value.
+      instance, // A ModelInstance,
+      instanceData: JavaScript object representation,
+      configurations: {} 
+    ) =>  {
+      const result = await configurations.someDatabaseObj.check(value)
+      if (result) {
+        return 'Some sort of database error'
+      }
+      return undefined 
+    }
+
+### Model Validators
+Model validators allows one to check values across a model, ensuring that multiple values work together. The inputs are the model instance, the JavaScript object representation, and optional configurations. The return can either be a string error or undefined if there are no errors. This function can be asynchronous, such as doing database lookups.
+
+    /**
+    * An example model validator that checks to see if two properties have the same value.
+    * @constructor
+    * @param {string} instance - A model instance, used for cross referencing.
+    * @param {string} instanceData - The JavaScript object representation of the model.
+    * @param {string} configurations - An optional configuration object passed in as part of validating.
+    * @return {string|undefined} - If error, returns a string, otherwise returns undefined.
+    */
+    const checkForDuplicateValues = (
+      instance, // A ModelInstance,
+      instanceData: JavaScript object representation,
+      configurations: {} 
+    ) =>  {
+      if(instanceData.firstProperty === instanceData.secondProperty) {
+        return 'Both properties must have different values'
+      }
+      return undefined 
+    }
+
+
+## Properties and Custom Properties
+There are numerous properties that are supported out of the box that cover most data modeling needs. It is also very easy to create custom properties that encapsulate unique choices
+validation requirements, etc.
+
+### List of Properties Out-Of-The-Box
+- UniqueId                        // A UUID property
+- DateProperty                    // A property for dates. Includes the ability to "autoNow".
+- ArrayProperty                   // An array property which can be used to limit types within it.
+- ModelReferenceProperty          // A property that references another property. (Think Foreign Key)
+- AdvancedModelReferenceProperty  // A more fuller/advanced property for referencing other properties.
+- IntegerProperty                 // A property for integers.
+- TextProperty                    // A text or string property.
+- ConstantValueProperty           // A property that contains a single, unchanging, static value. 
+- NumberProperty                  // A property for float/number types.
+- ObjectProperty                  // A property that has a JavaScript object. (Not a foreign key references)
+- EmailProperty                   // An email property.
+- BooleanProperty                 // A true or false value property.

package/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uDAAwC;AAW/B,8BAAS;AAVlB,iDAAkC;AAUd,wBAAM;AAT1B,yDAA0C;AASd,gCAAU;AARtC,+DAAgD;AAQR,sCAAa;AAPrD,+CAAgC;AAOuB,sBAAK;AAN5D,yDAA0C;AAMoB,gCAAU;AAJxE,2CAAwB;AACxB,+CAA4B;AAC5B,4CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uDAAwC;AAW/B,8BAAS;AAVlB,iDAAkC;AAUd,wBAAM;AAT1B,yDAA0C;AASd,gCAAU;AARtC,+DAAgD;AAQR,sCAAa;AAPrD,+CAAgC;AAOuB,sBAAK;AAN5D,yDAA0C;AAMoB,gCAAU;AAJxE,2CAAwB;AACxB,+CAA4B;AAC5B,4CAAyB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functional-models",
-  "version": "2.0.7",
+  "version": "2.0.11",
   "description": "A library for creating JavaScript function based models.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,7 +9,8 @@
     "test:coverage": "nyc npm run test",
     "feature-tests": "./node_modules/.bin/cucumber-js -p default",
     "coverage": "nyc --all --reporter=lcov npm test",
-    "dist": "tsc -p ./tsconfig.build.json && cp package.json ./dist && cp README.md ./dist && cd dist && npm publish"
+    "build": "tsc -p ./tsconfig.build.json && cp package.json ./dist && cp README.md ./dist",
+    "dist": "npm run build && cd dist && npm publish"
   },
   "repository": {
     "type": "git",
@@ -58,6 +59,7 @@
     "@types/proxyquire": "^1.3.28",
     "@types/sinon": "^10.0.6",
     "@typescript-eslint/eslint-plugin": "^5.6.0",
+    "@typescript-eslint/parser": "^5.3.0",
     "babel-eslint": "^10.1.0",
     "chai": "^4.3.0",
     "chai-as-promised": "^7.1.1",
@@ -73,7 +75,6 @@
     "typescript": "^4.4.4"
   },
   "dependencies": {
-    "@typescript-eslint/parser": "^5.3.0",
     "async-lock": "^1.3.0",
     "get-random-values": "^1.2.2",
     "lodash": "^4.17.21"

package/validation.d.ts

@@ -13,7 +13,7 @@ declare const isBoolean: ValuePropertyValidatorComponent<boolean>;
 declare const isString: ValuePropertyValidatorComponent<string>;
 declare const isArray: ValuePropertyValidatorComponent<readonly FunctionalValue[]>;
 declare const arrayType: <T extends FunctionalValue>(type: string) => ValuePropertyValidatorComponent<readonly T[]>;
-declare const meetsRegex: <T extends FunctionalValue>(regex: string | RegExp, flags?: string | undefined, errorMessage?: string) => ValuePropertyValidatorComponent<T>;
+declare const meetsRegex: <T extends FunctionalValue>(regex: string | RegExp, flags?: string, errorMessage?: string) => ValuePropertyValidatorComponent<T>;
 declare const choices: <T extends FunctionalValue>(choiceArray: readonly T[]) => ValuePropertyValidatorComponent<T>;
 declare const isDate: ValuePropertyValidatorComponent<Date>;
 declare const isRequired: ValuePropertyValidatorComponent<any>;