manyfest 1.0.43 → 1.0.44

package/docs/validating.md

@@ -0,0 +1,344 @@
+# Validating Objects
+
+Manyfest validates objects against their schema definitions, checking for required elements, data type conformance, and missing properties. Validation never throws exceptions; results come back as well-formed JSON.
+
+## Access
+
+```javascript
+const libManyfest = require('manyfest');
+
+// Validation requires a schema with descriptors
+const manifest = new libManyfest({
+    Scope: 'Animal',
+    Descriptors: {
+        'IDAnimal': { Name: 'Database ID', DataType: 'Integer', Default: 0 },
+        'Name': { Description: 'The animal species name.' },
+        'Type': { Description: 'Whether the animal is wild, domesticated, etc.' }
+    }
+});
+```
+
+## Core Concepts
+
+### Validation Results
+
+The `validate` method returns a result object with three properties:
+
+```javascript
+{
+    Error: null,        // null when valid, true when errors exist
+    Errors: [],         // Array of human-readable error message strings
+    MissingElements: [] // Array of addresses for elements not found in the object
+}
+```
+
+A clean validation looks like this:
+
+```javascript
+const result = manifest.validate({ IDAnimal: 42, Name: 'Rabbit', Type: 'Wild' });
+// { Error: null, Errors: [], MissingElements: [] }
+```
+
+## Validating an Object
+
+### validate
+
+Pass an object to check it against the schema:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Animal',
+    Descriptors: {
+        'IDAnimal': { DataType: 'Integer', Required: true },
+        'Name': { DataType: 'String' },
+        'Weight': { DataType: 'Float' }
+    }
+});
+
+const animal = { IDAnimal: 8675309, Name: 'BatBrains', Weight: 2.5 };
+const result = manifest.validate(animal);
+// { Error: null, Errors: [], MissingElements: [] }
+```
+
+### Non-Object Input
+
+Passing a non-object produces an immediate error:
+
+```javascript
+const result = manifest.validate('not an object');
+// { Error: true, Errors: ['Expected passed in object to be type object but was passed in string'], MissingElements: [] }
+```
+
+## Required Elements
+
+Mark a descriptor as `Required: true` to produce an error when that property is missing:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'User',
+    Descriptors: {
+        'Email': { DataType: 'String', Required: true },
+        'Name': { DataType: 'String', Required: true },
+        'Bio': { DataType: 'String' }
+    }
+});
+
+const user = { Email: 'alice@example.com' };
+const result = manifest.validate(user);
+// {
+//   Error: true,
+//   Errors: ['Element at address "Name" is flagged REQUIRED but is not set in the object.'],
+//   MissingElements: ['Name', 'Bio']
+// }
+```
+
+Note that `Bio` appears in `MissingElements` but not in `Errors` because it is not required.
+
+## Strict Mode
+
+When `strict` is enabled, every described element that is missing from the object becomes an error, regardless of the `Required` flag:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Config',
+    strict: true,
+    Descriptors: {
+        'Host': { DataType: 'String' },
+        'Port': { DataType: 'Integer' },
+        'Debug': { DataType: 'Boolean' }
+    }
+});
+
+const config = { Host: 'localhost' };
+const result = manifest.validate(config);
+// {
+//   Error: true,
+//   Errors: [
+//     'Element at address "Port" is flagged REQUIRED but is not set in the object.',
+//     'Element at address "Debug" is flagged REQUIRED but is not set in the object.'
+//   ],
+//   MissingElements: ['Port', 'Debug']
+// }
+```
+
+## Data Type Checking
+
+When a descriptor specifies a `DataType`, the value is checked for type conformance.
+
+### Supported Types
+
+| DataType | Expected JavaScript Type | Notes |
+|----------|------------------------|-------|
+| String | `string` | |
+| Number | `number` | Any numeric value |
+| Integer | `number` | Must not contain a decimal point |
+| Float | `number` | Any numeric value |
+| PreciseNumber | `string` | A string that parses as a valid number |
+| DateTime | any | Must be parsable by `new Date()` |
+
+### Type Validation Examples
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Record',
+    Descriptors: {
+        'Name': { DataType: 'String' },
+        'Count': { DataType: 'Integer' },
+        'Price': { DataType: 'Float' },
+        'Precision': { DataType: 'PreciseNumber' },
+        'Created': { DataType: 'DateTime' }
+    }
+});
+```
+
+**Valid object:**
+
+```javascript
+manifest.validate({
+    Name: 'Widget',
+    Count: 10,
+    Price: 19.99,
+    Precision: '19.9900',
+    Created: '2024-01-15T10:30:00Z'
+});
+// { Error: null, Errors: [], MissingElements: [] }
+```
+
+**Type mismatches:**
+
+```javascript
+manifest.validate({
+    Name: 42,
+    Count: 10.5,
+    Price: 'free',
+    Precision: 19.99,
+    Created: 'not a date'
+});
+// Errors include:
+//   'Element at address "Name" has a DataType String but is of the type number.'
+//   'Element at address "Count" has a DataType Integer but has a decimal point in the number.'
+//   'Element at address "Price" has a DataType Float but is of the type string.'
+//   'Element at address "Precision" has a DataType PreciseNumber but is of the type number.'
+//   'Element at address "Created" has a DataType DateTime but is not parsable as a Date by Javascript.'
+```
+
+### Integer vs Float
+
+Both `Integer` and `Float` require a JavaScript `number` type. The distinction is that `Integer` additionally checks that the value does not contain a decimal point:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Test',
+    Descriptors: {
+        'WholeNumber': { DataType: 'Integer' },
+        'Decimal': { DataType: 'Float' }
+    }
+});
+
+manifest.validate({ WholeNumber: 10, Decimal: 3.14 });
+// No errors
+
+manifest.validate({ WholeNumber: 10.5, Decimal: 3.14 });
+// Error: 'Element at address "WholeNumber" has a DataType Integer but has a decimal point in the number.'
+```
+
+### PreciseNumber
+
+The `PreciseNumber` type is for numeric values stored as strings to preserve precision (useful for financial calculations). Validation checks that the value is a `string` that matches a valid number pattern:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Financial',
+    Descriptors: {
+        'Balance': { DataType: 'PreciseNumber' }
+    }
+});
+
+manifest.validate({ Balance: '1234567890.12' });  // Valid
+manifest.validate({ Balance: 'not a number' });   // Error: not a valid number
+manifest.validate({ Balance: 1234.56 });           // Error: expects string type
+```
+
+### Unrecognized Data Types
+
+If a `DataType` is specified but not recognized, it defaults to `String` checking:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Test',
+    Descriptors: {
+        'Value': { DataType: 'CustomType' }
+    }
+});
+
+manifest.validate({ Value: 'hello' });  // Valid (treated as String)
+manifest.validate({ Value: 42 });       // Error (expected string)
+```
+
+## Nested Object Validation
+
+Descriptors with dot-notation addresses validate nested properties:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'User',
+    Descriptors: {
+        'Profile.Name': { DataType: 'String', Required: true },
+        'Profile.Age': { DataType: 'Integer' },
+        'Contact.Email': { DataType: 'String', Required: true }
+    }
+});
+
+const user = {
+    Profile: { Name: 'Alice', Age: 30 },
+    Contact: { Email: 'alice@example.com' }
+};
+
+manifest.validate(user);
+// { Error: null, Errors: [], MissingElements: [] }
+```
+
+## Use Cases
+
+### API Input Validation
+
+```javascript
+const requestManifest = new libManyfest({
+    Scope: 'CreateUser',
+    Descriptors: {
+        'email': { DataType: 'String', Required: true },
+        'password': { DataType: 'String', Required: true },
+        'profile.displayName': { DataType: 'String', Required: true },
+        'profile.age': { DataType: 'Integer' }
+    }
+});
+
+function validateCreateUserRequest(requestBody) {
+    let result = requestManifest.validate(requestBody);
+    if (result.Error) {
+        return { valid: false, errors: result.Errors };
+    }
+    return { valid: true };
+}
+```
+
+### Configuration Verification
+
+```javascript
+const configManifest = new libManyfest({
+    Scope: 'AppConfig',
+    strict: true,
+    Descriptors: {
+        'Database.Host': { DataType: 'String' },
+        'Database.Port': { DataType: 'Integer' },
+        'Database.Name': { DataType: 'String' },
+        'Server.Port': { DataType: 'Integer' },
+        'Server.LogLevel': { DataType: 'String' }
+    }
+});
+
+function verifyConfig(config) {
+    let result = configManifest.validate(config);
+    if (result.Error) {
+        console.error('Configuration errors:', result.Errors);
+        process.exit(1);
+    }
+    if (result.MissingElements.length > 0) {
+        console.warn('Optional config missing:', result.MissingElements);
+    }
+}
+```
+
+### Schema Completeness Checks
+
+Use `MissingElements` to identify which properties are absent, even when validation passes:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Profile',
+    Descriptors: {
+        'Name': { DataType: 'String', Required: true },
+        'Bio': { DataType: 'String' },
+        'Avatar': { DataType: 'String' },
+        'Website': { DataType: 'String' }
+    }
+});
+
+const profile = { Name: 'Alice', Bio: 'Developer' };
+const result = manifest.validate(profile);
+// result.Error is null (no errors)
+// result.MissingElements is ['Avatar', 'Website']
+
+const completeness = 1 - (result.MissingElements.length / 4);
+// 50% complete
+```
+
+## Notes
+
+- Validation never throws exceptions; errors are returned as structured data
+- `Error` is `null` when no errors exist, `true` when errors are present
+- `MissingElements` tracks all absent schema elements, not just required ones
+- In strict mode, every missing element is treated as an error
+- Data type checking is case-insensitive (`"String"`, `"string"`, `"STRING"` all work)
+- `undefined` values and non-existent properties are both treated as missing
+- Unrecognized `DataType` values default to `String` validation

package/docs/writing.md

@@ -0,0 +1,300 @@
+# Writing Values to Objects
+
+Manyfest provides safe, address-based value assignment that automatically creates intermediate objects and arrays as needed. Write to any depth in an object without manually building the path.
+
+## Access
+
+```javascript
+const libManyfest = require('manyfest');
+
+// Create a manifest (schema optional for write operations)
+const manifest = new libManyfest();
+
+// Or with a schema definition
+const manifest = new libManyfest({
+    Scope: 'User',
+    Descriptors: {
+        'Name': { Hash: 'name', DataType: 'String' },
+        'Profile.Email': { Hash: 'email', DataType: 'String' }
+    }
+});
+```
+
+## Core Concepts
+
+### Automatic Structure Creation
+
+When setting a value at a nested address, manyfest creates any intermediate objects that do not yet exist:
+
+```javascript
+const data = {};
+
+manifest.setValueAtAddress(data, 'user.profile.name', 'Alice');
+// data is now: { user: { profile: { name: 'Alice' } } }
+```
+
+No need to manually initialize `data.user` or `data.user.profile` first.
+
+## Setting Values
+
+### setValueAtAddress
+
+Set a value at any depth using a dot-notation address:
+
+```javascript
+const data = {};
+
+manifest.setValueAtAddress(data, 'name', 'Alice');
+// { name: 'Alice' }
+
+manifest.setValueAtAddress(data, 'profile.age', 30);
+// { name: 'Alice', profile: { age: 30 } }
+
+manifest.setValueAtAddress(data, 'profile.address.city', 'Portland');
+// { name: 'Alice', profile: { age: 30, address: { city: 'Portland' } } }
+```
+
+Returns `true` if the value was set successfully, `false` otherwise.
+
+### setValueByHash
+
+Set a value using a hash rather than a direct address. When descriptors define hash-to-address mappings, this lets you use friendly short names:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Animal',
+    Descriptors: {
+        'MedicalStats.Temps.CET': { Hash: 'ComfET', DataType: 'Float' },
+        'MedicalStats.Temps.MaxET': { Hash: 'MaxET', DataType: 'Float' }
+    }
+});
+
+const animal = {};
+
+manifest.setValueByHash(animal, 'ComfET', 98.6);
+manifest.setValueByHash(animal, 'MaxET', 104.2);
+// animal is now: { MedicalStats: { Temps: { CET: 98.6, MaxET: 104.2 } } }
+```
+
+If the hash is not found in the descriptor table, manyfest treats it as a direct address and sets the value that way.
+
+### Overwriting Existing Values
+
+Setting a value at an address that already contains data replaces it:
+
+```javascript
+const data = { color: 'blue' };
+
+manifest.setValueAtAddress(data, 'color', 'red');
+// { color: 'red' }
+```
+
+Nested values work the same way:
+
+```javascript
+const data = { user: { name: 'Alice' } };
+
+manifest.setValueAtAddress(data, 'user.name', 'Bob');
+// { user: { name: 'Bob' } }
+```
+
+## Array Assignment
+
+Set values at specific array indices using bracket notation:
+
+```javascript
+const data = { items: [] };
+
+manifest.setValueAtAddress(data, 'items[0]', 'first');
+manifest.setValueAtAddress(data, 'items[1]', 'second');
+manifest.setValueAtAddress(data, 'items[2]', 'third');
+// data.items is ['first', 'second', 'third']
+```
+
+Nested array elements work as expected:
+
+```javascript
+const data = { users: [{ name: 'Alice' }, { name: 'Bob' }] };
+
+manifest.setValueAtAddress(data, 'users[0].score', 95);
+manifest.setValueAtAddress(data, 'users[1].score', 88);
+// data.users is [{ name: 'Alice', score: 95 }, { name: 'Bob', score: 88 }]
+```
+
+## Boxed Properties
+
+Write to properties with special characters in their keys using bracket notation with quotes:
+
+```javascript
+const data = {};
+
+manifest.setValueAtAddress(data, '["my-special-key"]', 'value1');
+manifest.setValueAtAddress(data, 'nested["some.dotted.key"]', 'value2');
+// data is: { 'my-special-key': 'value1', nested: { 'some.dotted.key': 'value2' } }
+```
+
+## Populating Defaults
+
+### populateDefaults
+
+Fill in default values for any descriptor that defines a `Default` property, without overwriting existing data:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Settings',
+    Descriptors: {
+        'Theme': { DataType: 'String', Default: 'dark' },
+        'FontSize': { DataType: 'Integer', Default: 14 },
+        'Language': { DataType: 'String', Default: 'en' }
+    }
+});
+
+const settings = { Theme: 'light' };
+
+manifest.populateDefaults(settings);
+// settings is now: { Theme: 'light', FontSize: 14, Language: 'en' }
+// Theme was not overwritten because it already existed
+```
+
+Pass `true` as the second argument to overwrite existing properties:
+
+```javascript
+manifest.populateDefaults(settings, true);
+// settings is now: { Theme: 'dark', FontSize: 14, Language: 'en' }
+// Theme was overwritten to its default
+```
+
+### populateObject
+
+Populate all values based on the schema, using type defaults even when no explicit `Default` is defined:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Record',
+    Descriptors: {
+        'Name': { DataType: 'String' },
+        'Count': { DataType: 'Integer' },
+        'Active': { DataType: 'Boolean' },
+        'Tags': { DataType: 'Array' }
+    }
+});
+
+const record = manifest.populateObject({});
+// record is: { Name: '', Count: 0, Active: false, Tags: [] }
+```
+
+A filter function can be passed to selectively populate:
+
+```javascript
+const record = manifest.populateObject({}, false,
+    (pDescriptor) => { return pDescriptor.DataType === 'String'; }
+);
+// Only String-typed descriptors are populated
+```
+
+## Deleting Values
+
+### deleteValueAtAddress
+
+Remove a value at an address:
+
+```javascript
+const data = { user: { name: 'Alice', age: 30 } };
+
+manifest.deleteValueAtAddress(data, 'user.age');
+// data is now: { user: { name: 'Alice' } }
+```
+
+### deleteValueByHash
+
+The hash-based equivalent:
+
+```javascript
+manifest.deleteValueByHash(data, 'email');
+```
+
+## Use Cases
+
+### Building Objects from Flat Data
+
+```javascript
+function buildUserFromForm(formFields) {
+    const manifest = new libManyfest();
+    const user = {};
+
+    for (let tmpField of formFields) {
+        manifest.setValueAtAddress(user, tmpField.path, tmpField.value);
+    }
+
+    return user;
+}
+
+const fields = [
+    { path: 'name.first', value: 'Alice' },
+    { path: 'name.last', value: 'Smith' },
+    { path: 'contact.email', value: 'alice@example.com' },
+    { path: 'contact.phone', value: '555-1234' }
+];
+
+buildUserFromForm(fields);
+// { name: { first: 'Alice', last: 'Smith' }, contact: { email: 'alice@example.com', phone: '555-1234' } }
+```
+
+### Data Transformation
+
+```javascript
+function transformData(source, mappings) {
+    const manifest = new libManyfest();
+    const result = {};
+
+    for (let [targetPath, sourcePath] of Object.entries(mappings)) {
+        let value = manifest.getValueAtAddress(source, sourcePath);
+        if (value !== undefined) {
+            manifest.setValueAtAddress(result, targetPath, value);
+        }
+    }
+
+    return result;
+}
+
+const apiData = {
+    data: { user: { display_name: 'Alice', contact: { primary_email: 'alice@example.com' } } }
+};
+
+transformData(apiData, {
+    'userName': 'data.user.display_name',
+    'userEmail': 'data.user.contact.primary_email'
+});
+// { userName: 'Alice', userEmail: 'alice@example.com' }
+```
+
+### Initializing Records with Schema Defaults
+
+```javascript
+const invoiceManifest = new libManyfest({
+    Scope: 'Invoice',
+    Descriptors: {
+        'InvoiceNumber': { DataType: 'String', Default: '' },
+        'Status': { DataType: 'String', Default: 'draft' },
+        'LineItems': { DataType: 'Array', Default: [] },
+        'Total': { DataType: 'Float', Default: 0.0 },
+        'Metadata.CreatedBy': { DataType: 'String', Default: 'system' }
+    }
+});
+
+function createNewInvoice() {
+    return invoiceManifest.populateDefaults({});
+}
+
+createNewInvoice();
+// { InvoiceNumber: '', Status: 'draft', LineItems: [], Total: 0, Metadata: { CreatedBy: 'system' } }
+```
+
+## Notes
+
+- Non-existent intermediate objects are created automatically during write operations
+- Setting a value at an address where an intermediate path resolves to a non-object (e.g. a string) will not overwrite that value
+- Array indices use bracket notation: `items[0]`
+- `populateDefaults` does not overwrite existing properties unless the second argument is `true`
+- `populateObject` without a filter populates every descriptor in the schema
+- Paths are case-sensitive

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "manyfest",
-    "version": "1.0.43",
+    "version": "1.0.44",
     "description": "JSON Object Manifest for Data Description and Parsing",
     "main": "source/Manyfest.js",
     "scripts": {

package/source/Manyfest-ObjectAddress-CheckAddressExists.js

@@ -244,7 +244,7 @@ class ManyfestObjectAddressResolverCheckAddressExists
 				{
 					let tmpArgumentValues = [];
 
-					let tmpRootObject = (typeof(pRootObject) == 'undefined') ? pObject : pRootObject;
+
 
 					// Now get the value for each argument
 					for (let i = 0; i < tmpFunctionArguments.length; i++)
@@ -351,9 +351,8 @@ class ManyfestObjectAddressResolverCheckAddressExists
 			}
 			else
 			{
-				// Create a subobject and then pass that
-				pObject[tmpSubObjectName] = {};
-				return this.checkAddressExists(pObject[tmpSubObjectName], tmpNewAddress, tmpRootObject);
+				// The sub-object doesn't exist, so the address doesn't exist
+				return false;
 			}
 		}
 	}

package/source/Manyfest-ObjectAddress-DeleteValue.js

@@ -5,6 +5,8 @@ let libSimpleLog = require('./Manyfest-LogToConsole.js');
 let fCleanWrapCharacters = require('./Manyfest-CleanWrapCharacters.js');
 let fParseConditionals = require(`../source/Manyfest-ParseConditionals.js`)
 
+let _MockFable = { DataFormat: require('./Manyfest-ObjectAddress-Parser.js') };
+
 /**
 * Object Address Resolver - DeleteValue
 *
@@ -74,11 +76,11 @@ class ManyfestObjectAddressResolverDeleteValue
 			tmpParentAddress = pParentAddress;
 		}
 
-		// TODO: Make this work for things like SomeRootObject.Metadata["Some.People.Use.Bad.Object.Property.Names"]
-		let tmpSeparatorIndex = pAddress.indexOf('.');
+		// Use enclosure-aware parser to find the first segment separator
+		let tmpAddressPartBeginning = _MockFable.DataFormat.stringGetFirstSegment(pAddress);
 
 		// This is the terminal address string (no more dots so the RECUSION ENDS IN HERE somehow)
-		if (tmpSeparatorIndex == -1)
+		if (tmpAddressPartBeginning.length == pAddress.length)
 		{
 			// Check if the address refers to a boxed property
 			let tmpBracketStartIndex = pAddress.indexOf('[');
@@ -201,8 +203,8 @@ class ManyfestObjectAddressResolverDeleteValue
 		}
 		else
 		{
-			let tmpSubObjectName = pAddress.substring(0, tmpSeparatorIndex);
-			let tmpNewAddress = pAddress.substring(tmpSeparatorIndex+1);
+			let tmpSubObjectName = tmpAddressPartBeginning;
+			let tmpNewAddress = pAddress.substring(tmpAddressPartBeginning.length+1);
 
 			// BOXED ELEMENTS
 			// Test if the tmpNewAddress is an array or object