manyfest 1.0.43 → 1.0.44

package/docs/schema-manipulation.md

@@ -0,0 +1,186 @@
+# Schema Manipulation
+
+Manyfest provides tools for remapping, merging and auto-generating schemas. These are useful when adapting a schema to different object shapes, combining schemas from multiple sources, or bootstrapping a schema from sample data.
+
+## Address Remapping
+
+### resolveAddressMappings
+
+Remap descriptors from one set of addresses to another. This permanently mutates the descriptor object.
+
+```javascript
+const descriptors = {
+    'Address.Of.a': { Hash: 'a', DataType: 'Number' },
+    'Address.Of.b': { Hash: 'b', DataType: 'String' }
+};
+
+const mapping = {
+    'a': 'New.Address.Of.a',
+    'b': 'New.Address.Of.b'
+};
+
+manifest.schemaManipulations.resolveAddressMappings(descriptors, mapping);
+// descriptors is now:
+// {
+//   'New.Address.Of.a': { Hash: 'a', DataType: 'Number' },
+//   'New.Address.Of.b': { Hash: 'b', DataType: 'String' }
+// }
+```
+
+The mapping keys can be either addresses or hashes. If a key matches a descriptor's address directly, that descriptor is moved. If a key matches a descriptor's hash, the descriptor at that hash's address is moved.
+
+If a mapping key matches neither an existing address nor a hash, a new descriptor is created with the key as its hash.
+
+### safeResolveAddressMappings
+
+The same operation, but returns a new object instead of mutating the original:
+
+```javascript
+const original = {
+    'old.path': { Hash: 'value', DataType: 'String' }
+};
+
+const remapped = manifest.schemaManipulations.safeResolveAddressMappings(original, {
+    'value': 'new.path'
+});
+
+// original is unchanged
+// remapped is: { 'new.path': { Hash: 'value', DataType: 'String' } }
+```
+
+## Merging Schemas
+
+### mergeAddressMappings
+
+Combine two sets of descriptors. The destination (first argument) takes precedence when both contain the same address:
+
+```javascript
+const base = {
+    'Name': { DataType: 'String' },
+    'Email': { DataType: 'String' }
+};
+
+const extra = {
+    'Email': { DataType: 'String', Required: true },
+    'Phone': { DataType: 'String' }
+};
+
+const merged = manifest.schemaManipulations.mergeAddressMappings(base, extra);
+// {
+//   'Name': { DataType: 'String' },
+//   'Email': { DataType: 'String' },         <-- base wins (no Required)
+//   'Phone': { DataType: 'String' }           <-- added from extra
+// }
+```
+
+Returns a new object. Neither input is mutated.
+
+## Auto-Generating Schemas
+
+### generateAddressses
+
+Generate a schema from a sample object. This recursively walks the object and produces a descriptor for every reachable address:
+
+```javascript
+const sample = {
+    name: 'Alice',
+    age: 30,
+    address: {
+        city: 'Portland',
+        zip: '97201'
+    },
+    tags: ['admin', 'user']
+};
+
+const generated = manifest.objectAddressGeneration.generateAddressses(sample);
+// {
+//   'name':        { Address: 'name',        Hash: 'name',        Name: 'name',        DataType: 'String', Default: 'Alice', InSchema: false },
+//   'age':         { Address: 'age',         Hash: 'age',         Name: 'age',         DataType: 'Number', Default: 30,      InSchema: false },
+//   'address':     { Address: 'address',     Hash: 'address',     Name: 'address',     DataType: 'Object',                   InSchema: false },
+//   'address.city':{ Address: 'address.city', Hash: 'address.city', Name: 'address.city', DataType: 'String', Default: 'Portland', InSchema: false },
+//   'address.zip': { Address: 'address.zip', Hash: 'address.zip', Name: 'address.zip', DataType: 'String', Default: '97201',    InSchema: false },
+//   'tags':        { Address: 'tags',        Hash: 'tags',        Name: 'tags',        DataType: 'Array',                    InSchema: false },
+//   'tags[0]':     { Address: 'tags[0]',     Hash: 'tags[0]',     Name: 'tags[0]',     DataType: 'String', Default: 'admin',  InSchema: false },
+//   'tags[1]':     { Address: 'tags[1]',     Hash: 'tags[1]',     Name: 'tags[1]',     DataType: 'String', Default: 'user',   InSchema: false }
+// }
+```
+
+Every generated descriptor has `InSchema: false`, which acts as a flag for tooling to prompt a developer to opt-in before including it in a final schema.
+
+Data types are inferred from JavaScript types:
+- `string` becomes `String`
+- `number` and `bigint` become `Number`
+- Arrays become `Array` (with each element also generated)
+- Objects become `Object` (with each property also generated)
+- `null` and `undefined` become `Any`
+- Functions and Symbols are skipped
+
+## Use Cases
+
+### Adapting a Schema to a Different API Shape
+
+```javascript
+const baseSchema = {
+    'user.name': { Hash: 'UserName', DataType: 'String' },
+    'user.email': { Hash: 'UserEmail', DataType: 'String' },
+    'user.role': { Hash: 'UserRole', DataType: 'String' }
+};
+
+// API v2 returns data in a flat shape
+const v2Mapping = {
+    'UserName': 'display_name',
+    'UserEmail': 'email_address',
+    'UserRole': 'access_level'
+};
+
+const v2Schema = manifest.schemaManipulations.safeResolveAddressMappings(baseSchema, v2Mapping);
+// v2Schema addresses are now: display_name, email_address, access_level
+// Hashes remain: UserName, UserEmail, UserRole
+```
+
+### Bootstrapping a Schema from Sample Data
+
+```javascript
+// Take a sample API response
+const sampleResponse = await fetch('/api/users/1').then(r => r.json());
+
+// Generate all possible addresses
+const generated = manifest.objectAddressGeneration.generateAddressses(sampleResponse);
+
+// Pick the ones you need and build a proper schema
+const schema = new libManyfest({
+    Scope: 'User',
+    Descriptors: {
+        'data.id': { ...generated['data.id'], InSchema: true, Required: true },
+        'data.name': { ...generated['data.name'], InSchema: true, Name: 'Display Name' },
+        'data.email': { ...generated['data.email'], InSchema: true, Name: 'Email' }
+    }
+});
+```
+
+### Combining Base and Extension Schemas
+
+```javascript
+const coreFields = {
+    'ID': { DataType: 'Integer', Required: true },
+    'Name': { DataType: 'String', Required: true },
+    'Created': { DataType: 'DateTime' }
+};
+
+const auditFields = {
+    'CreatedBy': { DataType: 'String' },
+    'ModifiedBy': { DataType: 'String' },
+    'Modified': { DataType: 'DateTime' }
+};
+
+const fullSchema = manifest.schemaManipulations.mergeAddressMappings(coreFields, auditFields);
+// Contains all six fields
+```
+
+## Notes
+
+- `resolveAddressMappings` mutates the input object; use `safeResolveAddressMappings` when you need to preserve the original
+- `mergeAddressMappings` gives precedence to the first (destination) argument on address conflicts
+- `generateAddressses` produces every reachable address including individual array elements -- the output can be large for complex objects
+- Generated schemas use `InSchema: false` as a signal that the descriptor was auto-generated and has not been reviewed
+- Symbols and functions in source objects are silently skipped during generation

package/docs/schema.md

@@ -0,0 +1,319 @@
+# Schema Definition
+
+A manyfest schema describes the structure, types and metadata for the elements of an object. Schemas power validation, default population and hash-based lookups.
+
+## Access
+
+```javascript
+const libManyfest = require('manyfest');
+
+// From a definition object
+const manifest = new libManyfest({
+    Scope: 'Animal',
+    Descriptors: {
+        'IDAnimal': { Name: 'Database ID', DataType: 'Integer', Default: 0 },
+        'Name': { Description: 'The species name.' }
+    }
+});
+
+// Or build one programmatically
+const manifest = new libManyfest();
+manifest.scope = 'Animal';
+manifest.addDescriptor('IDAnimal', { Name: 'Database ID', DataType: 'Integer', Default: 0 });
+manifest.addDescriptor('Name', { Description: 'The species name.' });
+```
+
+## Scope
+
+The scope is a label that identifies what kind of data this manifest describes. It is used in log messages and has no functional effect on address resolution.
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Invoice',
+    Descriptors: { /* ... */ }
+});
+
+manifest.scope;  // 'Invoice'
+```
+
+If no scope is provided, it defaults to `'DEFAULT'`.
+
+## Descriptors
+
+Each key in the `Descriptors` object is an address. The value is a descriptor object with metadata about that element.
+
+```javascript
+{
+    Scope: 'User',
+    Descriptors: {
+        'Email': {
+            Hash: 'email',
+            Name: 'Email Address',
+            NameShort: 'Email',
+            Description: 'The primary contact email for this user.',
+            DataType: 'String',
+            Required: true,
+            Default: ''
+        }
+    }
+}
+```
+
+### Descriptor Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| **Hash** | `string` | Short identifier for hash-based lookups. Defaults to the address if not set. |
+| **Name** | `string` | Human-readable name for the element. |
+| **NameShort** | `string` | Abbreviated name for compact displays (tables, charts, logs). |
+| **Description** | `string` | Longer description of what this element represents. |
+| **DataType** | `string` | The expected data type. Used for validation and default values. |
+| **Required** | `boolean` | When `true`, validation reports an error if this element is missing. |
+| **Default** | `any` | The value returned when the element is not present in an object. |
+| **Address** | `string` | Auto-populated with the descriptor's key if not explicitly set. |
+
+All properties are optional. A descriptor can be as minimal as an empty object:
+
+```javascript
+{
+    Descriptors: {
+        'Name': {}  // Valid -- address is 'Name', hash defaults to 'Name'
+    }
+}
+```
+
+## Data Types
+
+| DataType | JavaScript Type | Default Value | Description |
+|----------|----------------|---------------|-------------|
+| `String` | `string` | `""` | A text value |
+| `Integer` | `number` | `0` | A whole number (no decimal point) |
+| `Float` | `number` | `0.0` | A floating point number |
+| `Number` | `number` | `0` | Any numeric value |
+| `PreciseNumber` | `string` | `"0.0"` | Arbitrary precision number stored as a string |
+| `Boolean` | `boolean` | `false` | `true` or `false` |
+| `Binary` | `number` | `0` | A boolean represented as `1` or `0` |
+| `YesNo` | `string` | - | A boolean represented as `"Y"` or `"N"` |
+| `DateTime` | varies | `0` | A value parsable by JavaScript's `Date` constructor |
+| `Key` | varies | - | A two-part key with ID and GUID (see below) |
+| `Array` | `array` | `[]` | A JavaScript array |
+| `Object` | `object` | `{}` | A JavaScript object |
+| `Null` | `null` | `null` | An explicit null value |
+
+### The Key Data Type
+
+Keys represent a paired identifier: an integer ID and a string GUID. This is useful for database records that have both a local numeric identifier and a globally unique string identifier.
+
+```javascript
+{
+    Descriptors: {
+        'IDBook': {
+            Hash: 'IDBook',
+            Name: 'Book Identifier',
+            DataType: 'Key',
+            KeyRepresentation: 'ID',
+            GUIDAddress: 'GUIDBook',
+            IDAddress: 'IDBook'
+        },
+        'GUIDBook': {
+            Hash: 'GUIDBook',
+            Name: 'Book GUID',
+            DataType: 'Key',
+            KeyRepresentation: 'GUID',
+            GUIDAddress: 'GUIDBook',
+            IDAddress: 'IDBook'
+        }
+    }
+}
+```
+
+The `KeyRepresentation` indicates which half of the pair this descriptor points to. The `GUIDAddress` and `IDAddress` properties link the two together.
+
+## Adding Descriptors
+
+### addDescriptor
+
+Add a single descriptor to an existing manifest:
+
+```javascript
+manifest.addDescriptor('Profile.Phone', {
+    Name: 'Phone Number',
+    DataType: 'String',
+    Required: false
+});
+```
+
+If a descriptor already exists at that address, it is replaced. The `Address` property is auto-set if not provided. The `Hash` property defaults to the address if not provided.
+
+Returns `true` on success, `false` if the descriptor is not a valid object.
+
+## Retrieving Descriptors
+
+### getDescriptor
+
+Get a descriptor by its address:
+
+```javascript
+const desc = manifest.getDescriptor('Profile.Phone');
+// { Name: 'Phone Number', DataType: 'String', Required: false, Address: 'Profile.Phone', Hash: 'Profile.Phone' }
+```
+
+### getDescriptorByHash
+
+Get a descriptor by its hash:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Config',
+    Descriptors: {
+        'Database.Connection.Host': { Hash: 'DBHost', DataType: 'String' }
+    }
+});
+
+manifest.getDescriptorByHash('DBHost');
+// { Hash: 'DBHost', DataType: 'String', Address: 'Database.Connection.Host' }
+```
+
+### eachDescriptor
+
+Iterate over all descriptors:
+
+```javascript
+manifest.eachDescriptor((pDescriptor) => {
+    console.log(`${pDescriptor.Address}: ${pDescriptor.Name || '(unnamed)'}`);
+});
+```
+
+## Serialization
+
+### serialize
+
+Convert the manifest to a JSON string for storage or transmission:
+
+```javascript
+const json = manifest.serialize();
+// '{"Scope":"User","Descriptors":{...},"HashTranslations":{...}}'
+```
+
+### deserialize
+
+Load a manifest from a JSON string:
+
+```javascript
+const manifest = new libManyfest();
+manifest.deserialize(json);
+```
+
+### getManifest
+
+Get the manifest state as a plain object:
+
+```javascript
+const state = manifest.getManifest();
+// { Scope: 'User', Descriptors: {...}, HashTranslations: {...} }
+```
+
+### clone
+
+Create a deep copy of the manifest:
+
+```javascript
+const copy = manifest.clone();
+// Independent copy -- changes to one don't affect the other
+```
+
+## Default Values
+
+When a descriptor defines a `Default`, that value is returned by `getValueAtAddress` and `getValueByHash` if the element is missing from the object.
+
+When no explicit `Default` is set but a `DataType` is defined, the type's built-in default is used (see the table above).
+
+### Overriding Type Defaults
+
+The built-in defaults for each type can be overridden at construction time:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Custom',
+    defaultValues: {
+        String: '(empty)',
+        Integer: -1,
+        Boolean: true
+    },
+    Descriptors: {
+        'Name': { DataType: 'String' },
+        'Count': { DataType: 'Integer' }
+    }
+});
+
+manifest.getValueAtAddress({}, 'Name');   // '(empty)'
+manifest.getValueAtAddress({}, 'Count');  // -1
+```
+
+## Strict Mode
+
+When `strict` is set to `true`, every described element that is missing from an object is treated as an error during validation, regardless of the `Required` flag:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Config',
+    strict: true,
+    Descriptors: {
+        'Host': { DataType: 'String' },
+        'Port': { DataType: 'Integer' }
+    }
+});
+
+manifest.validate({});
+// Both Host and Port are reported as errors
+```
+
+Without strict mode, only elements with `Required: true` generate errors when missing.
+
+## Use Cases
+
+### API Response Schema
+
+```javascript
+const apiSchema = new libManyfest({
+    Scope: 'WeatherAPI',
+    Descriptors: {
+        'data.temperature': { Hash: 'Temp', Name: 'Temperature', DataType: 'Float' },
+        'data.humidity': { Hash: 'Humidity', Name: 'Humidity', DataType: 'Float' },
+        'data.wind.speed': { Hash: 'WindSpeed', Name: 'Wind Speed', DataType: 'Float' },
+        'metadata.station': { Hash: 'Station', Name: 'Station ID', DataType: 'String' }
+    }
+});
+
+// Different API, same hashes
+const response = fetchWeatherData();
+const temp = apiSchema.getValueByHash(response, 'Temp');
+```
+
+### Form Field Definitions
+
+```javascript
+const formSchema = new libManyfest({
+    Scope: 'ContactForm',
+    Descriptors: {
+        'FirstName': { Name: 'First Name', DataType: 'String', Required: true },
+        'LastName': { Name: 'Last Name', DataType: 'String', Required: true },
+        'Email': { Name: 'Email Address', DataType: 'String', Required: true },
+        'Phone': { Name: 'Phone Number', DataType: 'String' },
+        'Message': { Name: 'Message', DataType: 'String', Default: '' }
+    }
+});
+
+// Use descriptors to generate form labels
+formSchema.eachDescriptor((desc) => {
+    console.log(`<label>${desc.Name}${desc.Required ? ' *' : ''}</label>`);
+});
+```
+
+## Notes
+
+- The address (the key in `Descriptors`) is the canonical identifier for an element
+- Hashes provide an alias; if no hash is set, the address is used as the hash
+- Multiple descriptors can share the same hash, but the last one wins
+- Descriptors are stored by address, so two descriptors at the same address will overwrite
+- `reset()` clears all descriptors, hashes and the scope