manyfest 1.0.43 → 1.0.44

package/docs/address-notation.md

@@ -0,0 +1,244 @@
+# Address Notation
+
+Addresses are the core of manyfest. They describe locations inside nested JavaScript objects using a compact string syntax. Every read, write, existence check and validation operation resolves through the address system.
+
+## Basic Dot Notation
+
+Dots separate levels of nesting:
+
+```javascript
+const manifest = new libManyfest();
+
+const data = {
+    user: {
+        profile: {
+            name: 'Alice'
+        }
+    }
+};
+
+manifest.getValueAtAddress(data, 'user');                  // { profile: { name: 'Alice' } }
+manifest.getValueAtAddress(data, 'user.profile');          // { name: 'Alice' }
+manifest.getValueAtAddress(data, 'user.profile.name');     // 'Alice'
+```
+
+Paths are case-sensitive. `user.Profile` and `user.profile` resolve to different locations.
+
+## Array Access
+
+Square brackets with a numeric index access array elements:
+
+```javascript
+const data = {
+    items: ['first', 'second', 'third'],
+    users: [
+        { name: 'Alice', scores: [95, 88] },
+        { name: 'Bob', scores: [72, 91] }
+    ]
+};
+
+manifest.getValueAtAddress(data, 'items[0]');             // 'first'
+manifest.getValueAtAddress(data, 'items[2]');             // 'third'
+manifest.getValueAtAddress(data, 'users[0].name');        // 'Alice'
+manifest.getValueAtAddress(data, 'users[1].scores[0]');   // 72
+```
+
+Indices are zero-based. Accessing an out-of-bounds index returns `undefined`.
+
+### Set Access
+
+Empty brackets access the full array:
+
+```javascript
+manifest.getValueAtAddress(data, 'users[]');
+// Returns all user objects
+```
+
+When combined with further path resolution, this produces an object keyed by each element's full address:
+
+```javascript
+manifest.getValueAtAddress(data, 'users[].name');
+// { 'users[0].name': 'Alice', 'users[1].name': 'Bob' }
+```
+
+## Boxed Properties
+
+Properties with special characters in their keys (dots, spaces, dashes) cannot use dot notation. Wrap them in brackets with quotes instead:
+
+```javascript
+const data = {
+    'my-key': 'value1',
+    'another key': 'value2',
+    nested: {
+        'some.dotted.key': 'value3'
+    }
+};
+
+manifest.getValueAtAddress(data, '["my-key"]');                 // 'value1'
+manifest.getValueAtAddress(data, "['another key']");            // 'value2'
+manifest.getValueAtAddress(data, 'nested["some.dotted.key"]');  // 'value3'
+```
+
+Single quotes, double quotes and backticks all work as the wrapping character.
+
+## Object Set Access
+
+The `{}` marker enumerates all keys of an object, resolving a sub-path on each:
+
+```javascript
+const data = {
+    departments: {
+        engineering: { budget: 50000, headcount: 12 },
+        marketing: { budget: 30000, headcount: 8 },
+        sales: { budget: 40000, headcount: 15 }
+    }
+};
+
+manifest.getValueAtAddress(data, 'departments{}.budget');
+// {
+//   'departments.engineering.budget': 50000,
+//   'departments.marketing.budget': 30000,
+//   'departments.sales.budget': 40000
+// }
+```
+
+This is useful for extracting a single field across all entries of an object-based collection.
+
+## Back-Navigation
+
+Double dots (`..`) navigate upward through the object hierarchy. Each dot beyond the first separator moves one level up from the current position:
+
+```javascript
+const data = {
+    Bundle: {
+        Contract: {
+            IDContract: 500
+        },
+        Project: {
+            IDProject: 42
+        }
+    }
+};
+
+// From IDContract, navigate back up to Bundle, then down into Project
+manifest.getValueAtAddress(data, 'Bundle.Contract.IDContract...Project.IDProject');
+// 42
+```
+
+The address resolves as:
+1. Navigate to `Bundle.Contract.IDContract`
+2. `..` means go up -- one dot goes back to `Contract`, the second goes back to `Bundle`
+3. Continue forward into `Project.IDProject`
+
+Back-navigation always resolves relative to the root object.
+
+## Function Calls
+
+If a property in the path is a function, it can be called using parentheses:
+
+```javascript
+const data = {
+    items: [10, 20, 30],
+    getTotal: function() {
+        return this.items.reduce((a, b) => a + b, 0);
+    }
+};
+
+manifest.getValueAtAddress(data, 'getTotal()');  // 60
+```
+
+### With Arguments
+
+Arguments inside the parentheses are resolved as addresses on the root object:
+
+```javascript
+const data = {
+    basePrice: 100,
+    taxRate: 0.08,
+    calculate: function(price, rate) {
+        return price + (price * rate);
+    }
+};
+
+manifest.getValueAtAddress(data, 'calculate(basePrice,taxRate)');  // 108
+```
+
+String literals can be passed by wrapping them in quotes:
+
+```javascript
+const data = {
+    greet: function(name) { return 'Hello, ' + name; }
+};
+
+manifest.getValueAtAddress(data, 'greet("World")');  // 'Hello, World'
+```
+
+Functions are called with `apply`, bound to their containing object so `this` works as expected.
+
+### Chained Function Calls
+
+A function's return value can be navigated further:
+
+```javascript
+const data = {
+    getUser: function() {
+        return { name: 'Alice', role: 'admin' };
+    }
+};
+
+manifest.getValueAtAddress(data, 'getUser().name');  // 'Alice'
+```
+
+## Address Linting
+
+Manyfest automatically cleans up common address issues before resolution:
+
+- Leading and trailing whitespace is trimmed
+- A trailing single `.` is removed (but `..` for back-navigation is preserved)
+
+```javascript
+manifest.getValueAtAddress(data, '  user.name  ');  // Works
+manifest.getValueAtAddress(data, 'user.name.');     // Trailing dot removed
+```
+
+## Writing with Addresses
+
+All of the notation above works for write operations too. Manyfest creates intermediate objects as needed:
+
+```javascript
+const data = {};
+
+manifest.setValueAtAddress(data, 'user.profile.name', 'Alice');
+// { user: { profile: { name: 'Alice' } } }
+
+manifest.setValueAtAddress(data, 'items[0]', 'first');
+// Also creates the items array if needed
+
+manifest.setValueAtAddress(data, '["special-key"]', 'value');
+// { 'special-key': 'value', user: { ... }, items: [...] }
+```
+
+## Address Syntax Summary
+
+| Syntax | Example | Description |
+|--------|---------|-------------|
+| `property` | `Name` | Direct property access |
+| `a.b.c` | `user.profile.name` | Nested property access |
+| `a[0]` | `items[0]` | Array element by index |
+| `a[].b` | `users[].name` | Property across all array elements |
+| `a["b"]` | `data["my-key"]` | Boxed property (special characters) |
+| `a{}.b` | `depts{}.budget` | Property across all object keys |
+| `a..b` | `x.y..z` | Back-navigation (up one level) |
+| `a()` | `getTotal()` | Function call |
+| `a(b)` | `calc(price)` | Function call with address argument |
+| `a("b")` | `greet("World")` | Function call with string literal |
+
+## Notes
+
+- Addresses are case-sensitive
+- Non-existent paths return `undefined` on read (no exceptions)
+- Non-existent intermediate objects are created on write
+- Array indices are zero-based
+- Function calls require the function to exist on the object at that path
+- Back-navigation resolves from the root object
+- The address system is shared by all operations: get, set, check, delete and validate

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Manyfest <small>1</small>
+
+> JSON Object Manifest for Data Description and Parsing
+
+- Safe read and write access to deeply nested objects
+- Schema-driven validation with data type checking
+- Hash-based lookups for friendly access to complex paths
+- Works in both Node.js and browser environments
+
+[GitHub](https://github.com/stevenvelozo/manyfest)
+[Get Started](#manyfest)

package/docs/hash-translation.md

@@ -0,0 +1,202 @@
+# Hash Translation
+
+Hash translation tables let you reuse the same schema structure while resolving hashes to different addresses. This is useful when the same logical data model maps to objects with different property names -- for instance, when two APIs return the same information in different shapes.
+
+## Core Concept
+
+Normally, a descriptor's `Hash` property maps to its `Address`:
+
+```javascript
+// Schema: Hash "Title" maps to address "metadata.title"
+manifest.getValueByHash(data, 'Title');  // resolves to data.metadata.title
+```
+
+A translation table adds a layer of indirection. It intercepts hash lookups and redirects them before the normal hash-to-address resolution runs:
+
+```
+Hash Lookup → Translation Table → Descriptor Hash Table → Address → Value
+```
+
+## Access
+
+Translation tables live on the `hashTranslations` property of a manifest instance:
+
+```javascript
+const manifest = new libManyfest({
+    Scope: 'Media',
+    Descriptors: {
+        'metadata.title': { Hash: 'Title', DataType: 'String' },
+        'metadata.creator': { Hash: 'Creator', DataType: 'String' }
+    }
+});
+
+// Add translations
+manifest.hashTranslations.addTranslation({
+    'Title': 'info.name',
+    'Creator': 'info.author'
+});
+```
+
+After adding translations, `getValueByHash(data, 'Title')` resolves to `data.info.name` instead of `data.metadata.title`.
+
+## Adding Translations
+
+### addTranslation
+
+Pass an object where each key is the source hash and each value is the destination hash or address:
+
+```javascript
+manifest.hashTranslations.addTranslation({
+    'SourceHash': 'DestinationHash',
+    'AnotherSource': 'AnotherDestination'
+});
+```
+
+Multiple calls are additive. Later calls can overwrite earlier translations for the same source hash.
+
+## Removing Translations
+
+### removeTranslation
+
+Remove by passing a string (single hash) or an object (multiple hashes):
+
+```javascript
+// Remove a single translation
+manifest.hashTranslations.removeTranslation('Title');
+
+// Remove multiple at once
+manifest.hashTranslations.removeTranslation({
+    'Title': 'info.name',
+    'Creator': 'info.author'
+});
+```
+
+When an object is passed, only the keys matter. The values are ignored.
+
+### clearTranslations
+
+Remove all translations at once:
+
+```javascript
+manifest.hashTranslations.clearTranslations();
+```
+
+## Checking the Table
+
+### translationCount
+
+```javascript
+manifest.hashTranslations.translationCount();  // Number of active translations
+```
+
+### translate
+
+Translate a single hash. Returns the original hash if no translation exists:
+
+```javascript
+manifest.hashTranslations.translate('Title');    // 'info.name' (if translated)
+manifest.hashTranslations.translate('Unknown');  // 'Unknown' (passthrough)
+```
+
+## Resolution Order
+
+When `getValueByHash` (or any hash-based method) resolves a hash, the following order is used:
+
+1. **Element hash table only** -- if the hash is in the descriptor table and not in the translation table, resolve normally
+2. **Translation table then element hash table** -- if the hash is in the translation table and the translated result is in the element hash table, resolve through both
+3. **Translation table only** -- if the hash is in the translation table but the translated result is not in the element hash table, use the translated value as a direct address
+4. **Passthrough** -- if the hash is in neither table, treat it as a direct address
+
+This means translations can override built-in descriptor hashes.
+
+## Use Cases
+
+### Multiple API Formats
+
+When two APIs return the same data in different shapes, one schema handles both:
+
+```javascript
+const mediaSchema = new libManyfest({
+    Scope: 'Media',
+    Descriptors: {
+        'title': { Hash: 'Title', DataType: 'String' },
+        'author': { Hash: 'Author', DataType: 'String' },
+        'year': { Hash: 'Year', DataType: 'Integer' }
+    }
+});
+
+// API A returns: { title: '...', author: '...', year: 2024 }
+// Works out of the box:
+mediaSchema.getValueByHash(apiAResponse, 'Title');
+
+// API B returns: { metadata: { name: '...', creator: '...' }, info: { published: 2024 } }
+// Add translations for API B's shape:
+mediaSchema.hashTranslations.addTranslation({
+    'Title': 'metadata.name',
+    'Author': 'metadata.creator',
+    'Year': 'info.published'
+});
+
+mediaSchema.getValueByHash(apiBResponse, 'Title');   // reads metadata.name
+mediaSchema.getValueByHash(apiBResponse, 'Author');  // reads metadata.creator
+```
+
+### Locale-Specific Field Names
+
+```javascript
+const formSchema = new libManyfest({
+    Scope: 'Form',
+    Descriptors: {
+        'firstName': { Hash: 'FirstName', DataType: 'String' },
+        'lastName': { Hash: 'LastName', DataType: 'String' }
+    }
+});
+
+// Japanese form data uses different field names
+formSchema.hashTranslations.addTranslation({
+    'FirstName': 'mei',
+    'LastName': 'sei'
+});
+
+const jpData = { mei: 'Taro', sei: 'Yamada' };
+formSchema.getValueByHash(jpData, 'FirstName');  // 'Taro'
+```
+
+### Temporary Overrides
+
+Apply translations for a specific operation, then clear them:
+
+```javascript
+manifest.hashTranslations.addTranslation({ 'Name': 'display_name' });
+
+const displayName = manifest.getValueByHash(record, 'Name');
+
+manifest.hashTranslations.clearTranslations();
+// Back to normal resolution
+```
+
+## Serialization
+
+Hash translations are included when you serialize a manifest:
+
+```javascript
+const state = manifest.getManifest();
+// { Scope: '...', Descriptors: {...}, HashTranslations: {...} }
+
+const json = manifest.serialize();
+// HashTranslations included in the JSON string
+```
+
+And restored when you clone:
+
+```javascript
+const copy = manifest.clone();
+// copy.hashTranslations contains the same translations
+```
+
+## Notes
+
+- Translations are checked before the built-in hash table, so they can override descriptor hashes
+- If a translation points to a hash that also has a translation, only one level of indirection is resolved
+- Translations work with all hash-based methods: `getValueByHash`, `setValueByHash`, `deleteValueByHash`, `checkAddressExistsByHash`, `getDescriptorByHash`
+- The translation table is a simple `{ source: destination }` object -- no nesting or chaining

package/docs/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Manyfest Documentation</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="description" content="Documentation for Manyfest - JSON Object Manifest for Data Description and Parsing" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0" />
+    <meta name="keywords" content="manyfest, manifest, json, object, schema, data, description, parsing, javascript" />
+    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" />
+    <style>
+      :root {
+        --theme-color: #42b983;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      window.$docsify = {
+        name: 'Manyfest',
+        repo: 'https://github.com/stevenvelozo/manyfest',
+        loadSidebar: '_sidebar.md',
+        subMaxLevel: 3,
+        auto2top: true,
+        coverpage: 'cover.md',
+        onlyCover: false,
+        search: {
+          placeholder: 'Search',
+          noData: 'No results found',
+          depth: 3
+        },
+        copyCode: {
+          buttonText: 'Copy',
+          successText: 'Copied'
+        }
+      };
+    </script>
+    <!-- Docsify v4 -->
+    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+    <!-- Syntax highlighting -->
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
+    <!-- Search plugin -->
+    <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+    <!-- Copy code plugin -->
+    <script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
+  </body>
+</html>