v0.5.0

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased][unreleased]
 
+<!--
+- Calculated fields module
+- Typescript + JSDOC generation module -->
+
+## [0.5.0][] - 2023-11-05
+
+- Readme enhancement
+- JSDOC documentation
+
 ## [0.4.0][] - 2023-11-05
 
 - Support latest:21 node version
@@ -77,7 +86,9 @@
 - Default exotic types: Any, Undefined, JSON
 - Custom Errors
 
-[unreleased]: https://github.com/astrohelm/metaforge/compare/v0.3.0...HEAD
+[unreleased]: https://github.com/astrohelm/metaforge/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/astrohelm/metaforge/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/astrohelm/metaforge/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/astrohelm/metaforge/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/astrohelm/metaforge/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/astrohelm/metaforge/releases/tag/v0.1.0

README.md

@@ -1,10 +1,25 @@
-<h1 align="center">MetaForge v0.4.0 🕵️</h1>
+<h1 align="center">MetaForge v0.5.0 🕵️</h1>
+
+## Describe your data structures by subset of JavaScript and:
+
+- 📝 Generate data relational structures (types, jsdoc, diagrams, migrations, etc.)
+- 🔎 Validate it in runtime with strict & partial validations
+- 👀 Send it to other server to validate data consistency
+- 🛠️ Handle it with custom modules
+- 💉 Calculate fields
+
+## Installation
+
+```bash
+npm i metaforge --save
+```
 
 ## Usage example
 
 ```js
 const userSchema = new Schema({
   $id: 'userSchema',
+  $meta: { name: 'user', description: 'schema for users testing' },
   phone: { $type: 'union', types: ['number', 'string'] }, //? anyof tyupe
   name: { $type: 'set', items: ['string', '?string'] }, //? set tuple
   mask: { $type: 'array', items: 'string' }, //? array
@@ -32,21 +47,30 @@ const sample = [
     options: { notifications: true, lvls: [2, '["admin", "user"]'] },
     adress: 'Pushkin street',
   },
-  {
-    phone: 79999999999,
-    type: 'guest',
-    mask: ['255', '255', '255', '0'],
-    name: new Set(['Alexander', 'Ivanov']),
-    options: { notifications: false, lvls: [2, '["admin", "user"]'] },
-    adress: 'Pushkin street',
-  },
+  //...
 ];
 
+systemSchema.warnings; // inspect after build warnings
 systemSchema.test(sample); // Shema validation
+systemSchema.toTypescript('system'); // Typescript generation
 systemSchema.pull('userSchema').test(sample[0]); // Subschema validation
 systemSchema.pull('userSchema').test({ phone: 123 }, 'root', true); // Partial validation
+systemSchema.pull('userSchema'); // Metadata: {..., name: 'user', description: 'schema for users testing'}
 ```
 
+## Docs
+
+- [About modules](./docs/modules.md#modules-or-another-words-plugins)
+  - [Handyman](./modules/handyman/README.md) | quality of life module
+  - [Metatest](./modules/test/README.md) | adds prototype testing
+  - [Metatype](./modules/types/README.md) | generate typescript:JSDOC from schema
+  - [Writing custom modules](./docs/prototypes.md#writing-custom-modules)
+- [About prototypes](./docs/prototypes.md#readme-map)
+  - [Schemas contracts](./docs/prototypes.md#schemas-contracts)
+  - [How to build custom prototype](./docs/prototypes.md#writing-custom-prototypes)
+
+## Copyright & contributors
+
 <p align="center">
 Copyright © 2023 <a href="https://github.com/astrohelm/metaforge/graphs/contributors">Astrohelm contributors</a>.
 This library is <a href="./LICENSE">MIT licensed</a>.<br/>

docs/modules.md

@@ -0,0 +1,53 @@
+# Modules or another words Plugins
+
+You can extend schema functionality using modules;
+
+## Default Modules
+
+- [Handyman](../modules/handyman/README.md) | quality of life module
+- [Metatest](../modules/test/README.md) | adds prototype testing
+- [Metatype]('../modules/types/README.md') | generate typescript:JSDOC from schema
+
+## Writing custom modules
+
+First, create your module:
+
+```js
+const module = (schema, options, plan) => {};
+```
+
+It will receive as parameters **Schema instance**, **options** witch used to create schema and
+**plan**; You can use it for extend schema or prototypes functionality;
+
+```js
+const module = (schema, options, plan) => {
+  const { forge, tools } = schema;
+  // Define variables
+  this.forge.attach('after', { createdAt: new Date() });
+  // Define default variables (will be replaced if exists in other prototype)
+  this.forge.attach('before', { myVariable: 1 });
+  // Update existed prototype chains or create new chain
+  this.forge.attach('custromProto', { createdAt: 'now', myVariable: 'Hello' });
+  // Return builded Prototype chain as ForgePrototype
+  this.forge.get('string'); // { ..., myVariable: 1, createdAt: Date }
+  this.forge.get('customProto'); // { ..., myVariable: 'Hello', createdAt: Date }
+  // Create new functionality for schemas
+  this.schema.from = plan => new Schema(plan); /
+  // Extend prototype tooling
+  tools.isRequired = plan => plan.$required ?? true;
+};
+```
+
+Finally, you can register your module
+
+```js
+const schema = new Schema(plan, { modules: new Map() }); // To replace global modules
+schema.register('MyModule', module); // To define your module to single instance
+Schema.modules.set('MyModule', module); // To define your module globally
+```
+
+> - You can push prototype to the wrappers (before - the lowest priority & after - the highest
+>   priority)
+> - If you want to attach prototype to chain - prototype **must starts** with lower case
+> - If prototype already exists your prototype will be pushed at the end of prototype chain (higher
+>   priority properties)