api-ape 3.0.1 → 4.1.0

package/utils/jss/encode.js

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview JSS Encoder - Encodes JavaScript objects to JSS format
+ *
+ * This module provides the encoding functionality for JSON Super Set (JSS).
+ * It converts JavaScript objects containing extended types (Date, RegExp,
+ * Error, Map, Set, undefined) into a JSON-compatible format using tagged keys.
+ *
+ * ## Encoding Process
+ *
+ * The encoder traverses the object tree and:
+ * 1. Detects extended types using `Object.prototype.toString`
+ * 2. Converts them to primitive representations
+ * 3. Tags the key with a type indicator (e.g., `<!D>` for Date)
+ * 4. Tracks visited objects to handle circular references
+ *
+ * ## Tag System
+ *
+ * | Type      | Tag | Encoded Value                          |
+ * |-----------|-----|----------------------------------------|
+ * | Date      | `D` | Unix timestamp (milliseconds)          |
+ * | RegExp    | `R` | String representation (e.g., "/a/gi")  |
+ * | Error     | `E` | Array: [name, message, stack]          |
+ * | undefined | `U` | null                                   |
+ * | Map       | `M` | Object from entries                    |
+ * | Set       | `S` | Array of values                        |
+ * | Pointer   | `P` | Path array to referenced object        |
+ *
+ * ## Array Type Tags
+ *
+ * For arrays containing extended types, the tag includes all element types:
+ * ```javascript
+ * [new Date(), new Date()]  →  { "[D,D]": [timestamp1, timestamp2] }
+ * ```
+ *
+ * @module utils/jss/encode
+ * @see {@link module:utils/jss/decode} for decoding implementation
+ * @see {@link module:utils/jss} for main JSS module
+ *
+ * @example
+ * const { encode, stringify } = require('./encode')
+ *
+ * // Encode without stringifying (returns plain object)
+ * const encoded = encode({
+ *   created: new Date('2024-01-01'),
+ *   pattern: /test/i
+ * })
+ * // { "created<!D>": 1704067200000, "pattern<!R>": "/test/i" }
+ *
+ * // Stringify (encode + JSON.stringify)
+ * const str = stringify({ date: new Date() })
+ * // Ready for transmission
+ *
+ * @example
+ * // Circular reference handling
+ * const obj = { name: 'root' }
+ * obj.self = obj
+ *
+ * const encoded = encode(obj)
+ * // { name: 'root', 'self<!P>': [] }
+ * // The empty array [] is the path to the root object
+ */
+
+/**
+ * Lookup table mapping Object.prototype.toString results to type tags
+ *
+ * Used for fast type detection during encoding. Only types that require
+ * special handling are included - standard JSON types (string, number,
+ * boolean, null, array, object) are handled separately.
+ *
+ * @constant {Object.<string, string>}
+ * @private
+ *
+ * @example
+ * Object.prototype.toString.call(new Date())  // '[object Date]'
+ * tagLookup['[object Date]']                  // 'D'
+ */
+const { getAllPlugins } = require("./plugins");
+
+const tagLookup = {
+  /**
+   * RegExp objects - serialized as string pattern
+   */
+  "[object RegExp]": "R",
+
+  /**
+   * Date objects - serialized as Unix timestamp
+   */
+  "[object Date]": "D",
+
+  /**
+   * Error objects - serialized as [name, message, stack] array
+   */
+  "[object Error]": "E",
+
+  /**
+   * Undefined values - explicitly encoded (unlike JSON which omits them)
+   */
+  "[object Undefined]": "U",
+
+  /**
+   * Map objects - serialized as plain object from entries
+   */
+  "[object Map]": "M",
+
+  /**
+   * Set objects - serialized as array of values
+   */
+  "[object Set]": "S",
+};
+
+/**
+ * Encode a JavaScript object to JSS format
+ *
+ * Recursively traverses the object tree, converting extended types to
+ * their tagged representations. Handles circular references by tracking
+ * visited objects and replacing subsequent references with path pointers.
+ *
+ * ## Algorithm
+ *
+ * 1. Create a WeakMap to track visited objects and their paths
+ * 2. For each value in the object:
+ *    - If it's an extended type (Date, RegExp, etc.), encode it
+ *    - If it's an object/array, recurse (checking for circularity)
+ *    - If it's a primitive, pass through unchanged
+ * 3. Return the encoded object structure
+ *
+ * ## Circular Reference Detection
+ *
+ * When an object is first encountered, its path is stored in `visitedEncode`.
+ * If the same object is encountered again, a pointer (`P` tag) is created
+ * with the stored path.
+ *
+ * @param {any} obj - The object to encode
+ * @returns {Object} Encoded object with tagged keys for extended types
+ *
+ * @example
+ * // Simple types
+ * encode({ date: new Date('2024-01-01') })
+ * // { "date<!D>": 1704067200000 }
+ *
+ * @example
+ * // Nested structures
+ * encode({
+ *   user: {
+ *     name: 'Alice',
+ *     createdAt: new Date(),
+ *     roles: new Set(['admin', 'user'])
+ *   }
+ * })
+ * // {
+ * //   user: {
+ * //     name: 'Alice',
+ * //     "createdAt<!D>": 1704067200000,
+ * //     "roles<!S>": ['admin', 'user']
+ * //   }
+ * // }
+ *
+ * @example
+ * // Circular references
+ * const a = { name: 'a' }
+ * const b = { name: 'b', ref: a }
+ * a.ref = b
+ *
+ * encode({ a, b })
+ * // {
+ * //   a: { name: 'a', 'ref<!P>': ['b'] },
+ * //   b: { name: 'b', 'ref<!P>': ['a'] }
+ * // }
+ *
+ * @example
+ * // Error objects
+ * encode({ error: new TypeError('Invalid input') })
+ * // { "error<!E>": ['TypeError', 'Invalid input', 'TypeError: Invalid input\n    at ...'] }
+ *
+ * @example
+ * // Mixed array with extended types
+ * encode({ dates: [new Date(), new Date()] })
+ * // { "dates<![D,D]>": [1704067200000, 1704067300000] }
+ */
+function encode(obj) {
+  /**
+   * WeakMap tracking visited objects to detect circular references
+   * Maps each visited object to its path in the object tree
+   * @type {WeakMap<Object, Array<string|number>>}
+   */
+  const visitedEncode = new WeakMap();
+  visitedEncode.set(obj, []);
+
+  /**
+   * Recursively encode a value with circular reference tracking
+   *
+   * @param {any} value - The value to encode
+   * @param {Array<string|number>} path - Current path in the object tree
+   * @returns {[string, any]} Tuple of [tag, encodedValue]
+   * @private
+   */
+  function encodeValueWithVisited(value, path = []) {
+    const type = typeof value;
+    const tag = tagLookup[Object.prototype.toString.call(value)];
+
+    // Handle special types with known tags
+    if (tag !== undefined) {
+      if ("D" === tag) return [tag, value.valueOf()];
+      if ("E" === tag) return [tag, [value.name, value.message, value.stack]];
+      if ("R" === tag) return [tag, value.toString()];
+      if ("U" === tag) return [tag, null];
+      if ("S" === tag) return [tag, Array.from(value)];
+      if ("M" === tag) return [tag, Object.fromEntries(value)];
+    }
+
+    // Check custom plugins
+    for (const [customTag, plugin] of getAllPlugins()) {
+      const key = path.length > 0 ? path[path.length - 1] : undefined;
+      if (plugin.check(key, value)) {
+        return [customTag, plugin.encode(path, key, value, {})];
+      }
+    }
+
+    // Handle objects and arrays (potential circular references)
+    if (type === "object" && value !== null) {
+      // Check for circular reference
+      if (visitedEncode.has(value)) return ["P", visitedEncode.get(value)];
+
+      // Mark as visited with current path
+      visitedEncode.set(value, path);
+
+      const isArray = Array.isArray(value);
+      const objKeys = isArray
+        ? Array.from(Array(value.length).keys())
+        : Object.keys(value);
+      const result = isArray ? [] : {};
+      const typesFound = [];
+
+      // Process each property/element
+      for (let i = 0; i < objKeys.length; i++) {
+        const key = objKeys[i];
+        const [t, v] = encodeValueWithVisited(value[key], [...path, key]);
+
+        if (isArray) {
+          typesFound.push(t);
+          result.push(v);
+        } else if (value[key] !== undefined) {
+          // Add tag to key if value was special type
+          result[key + (t ? `<!${t}>` : "")] = v;
+        }
+      }
+
+      // For arrays with special types, create compound tag
+      if (isArray && typesFound.find((t) => !!t))
+        return [`[${typesFound.join()}]`, result];
+      return ["", result];
+    }
+    // Primitive values pass through unchanged
+    else {
+      return ["", value];
+    }
+  }
+
+  // Process root object properties
+  let keys = Array.isArray(obj)
+    ? Array.from(Array(obj.length).keys())
+    : Object.keys(obj);
+  const result = {};
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (obj[key] !== undefined) {
+      const [t, v] = encodeValueWithVisited(obj[key], [key]);
+      result[key + (t ? `<!${t}>` : "")] = v;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Stringify an object to JSS format
+ *
+ * Combines `encode()` with `JSON.stringify()` to produce a string
+ * representation suitable for transmission over WebSocket or storage.
+ *
+ * This is the high-level API - use this for most cases.
+ *
+ * @param {any} obj - The object to stringify
+ * @returns {string} JSS-encoded JSON string
+ *
+ * @example
+ * // Basic usage
+ * const str = stringify({
+ *   message: 'Hello',
+ *   timestamp: new Date(),
+ *   pattern: /world/i
+ * })
+ * // '{"message":"Hello","timestamp<!D>":1704067200000,"pattern<!R>":"/world/i"}'
+ *
+ * @example
+ * // With nested objects
+ * const str = stringify({
+ *   user: {
+ *     settings: new Map([['theme', 'dark']])
+ *   }
+ * })
+ *
+ * @example
+ * // Ready for WebSocket transmission
+ * socket.send(stringify({ type: '/chat', data: { text: 'Hi!' } }))
+ */
+function stringify(obj) {
+  return JSON.stringify(encode(obj));
+}
+
+module.exports = { encode, stringify };

package/utils/jss/files.md

@@ -0,0 +1,68 @@
+# JSS Sub-Modules Files
+
+This module contains the low-level encoding and decoding implementations for JSON Super Set (JSS). The encoder traverses objects to detect and tag extended types, while the decoder parses tagged keys and reconstructs the original JavaScript types.
+
+## Guidelines
+
+- **Tag consistency** — Encoding and decoding tags must match exactly; if you add a new tag to `encode.js`, add the corresponding decoder to `decode.js`
+- **Type detection** — Use `Object.prototype.toString.call()` for reliable type detection, not `instanceof`
+- **Circular reference tracking** — Both encoder and decoder must handle circular references via the `<!P>` path pointer tag
+- **Isomorphic code** — All code must work in both browser and Node.js/Bun/Deno environments
+- **Preserve error stacks** — Error encoding must preserve the original stack trace for debugging
+- **No external dependencies** — Pure JavaScript only; no external packages
+
+## Directory Structure
+
+```
+jss/
+├── encode.js   # JSS encoding (object → tagged JSON-compatible format)
+└── decode.js   # JSS decoding (tagged format → restored JavaScript types)
+```
+
+## Files
+
+### `encode.js`
+
+Converts JavaScript objects containing extended types into JSON-compatible format:
+
+- Detects types via `Object.prototype.toString`
+- Tags keys with type indicators (`<!D>`, `<!R>`, `<!E>`, `<!U>`, `<!M>`, `<!S>`, `<!P>`)
+- Converts Dates to timestamps, RegExps to strings, Errors to arrays
+- Tracks visited objects to handle circular references
+
+**Exports:**
+
+- `encode(obj)` — Returns JSS-encoded plain object (for inspection or custom serialization)
+- `stringify(obj)` — Returns JSS-encoded JSON string (encode + JSON.stringify)
+
+**Tag Reference:**
+
+| Tag | Type | Encoded Value |
+|-----|------|---------------|
+| `<!D>` | Date | Unix timestamp (milliseconds) |
+| `<!R>` | RegExp | String representation (e.g., "/test/gi") |
+| `<!E>` | Error | Array: [name, message, stack] |
+| `<!U>` | undefined | null |
+| `<!M>` | Map | Object from entries |
+| `<!S>` | Set | Array of values |
+| `<!P>` | Pointer | Path array to referenced object (circular refs) |
+
+### `decode.js`
+
+Restores JavaScript types from JSS-encoded format:
+
+- Parses tagged keys to identify encoded types
+- Reconstructs Date, RegExp, Error, Map, Set, and undefined
+- Resolves circular reference pointers to restore object cycles
+- Handles nested structures recursively
+
+**Exports:**
+
+- `decode(obj)` — Decodes JSS-encoded plain object back to original types
+- `parse(str)` — Parses JSS string and decodes (JSON.parse + decode)
+
+**Decoding Process:**
+
+1. First pass: Decode all values, storing pointer locations
+2. Second pass: Resolve `<!P>` pointers by following stored paths
+3. Return fully restored object with original types and circular references

package/utils/jss/plugins.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview JSS Plugin Registry
+ *
+ * This module provides the plugin registration system for JSS (JSON Super Set).
+ * It allows developers to register custom type handlers that extend JSS beyond
+ * its built-in types (Date, RegExp, Error, etc.).
+ *
+ * ## Plugin Architecture
+ *
+ * Plugins are registered with a single-character tag and provide:
+ * - `check(key, value)` - Determines if this plugin handles a value
+ * - `encode(path, key, value, context)` - Transforms value for serialization
+ * - `decode(value, path, context)` - Restores value from serialization
+ * - `onSend(path, key, value, context)` - Optional: handles external resources during send
+ * - `onReceive(path, key, value, context)` - Optional: handles external resources during receive
+ *
+ * ## Usage
+ *
+ * ```javascript
+ * const jss = require('./jss')
+ *
+ * jss.custom('X', {
+ *   check: (key, value) => value instanceof CustomType,
+ *   encode: (path, key, value, ctx) => value.toSerializable(),
+ *   decode: (value, path, ctx) => CustomType.fromSerializable(value)
+ * })
+ * ```
+ *
+ * @module utils/jss/plugins
+ * @see {@link module:utils/jss} for main JSS module
+ */
+
+/**
+ * Built-in type tags that cannot be overridden
+ * @constant {string[]}
+ */
+const builtInTags = ["D", "R", "E", "U", "M", "S", "P", "I"];
+
+/**
+ * Registry of custom plugins
+ * Maps tag character to plugin configuration
+ * @type {Map<string, PluginConfig>}
+ * @private
+ */
+const plugins = new Map();
+
+/**
+ * @typedef {Object} PluginConfig
+ * @property {function(string|number, any): boolean} check - Determines if plugin handles value
+ * @property {function(string[], string|number, any, Object): any} encode - Transforms for serialization
+ * @property {function(any, string[], Object): any} decode - Restores from serialization
+ * @property {function(string[], string|number, any, Object): {replace: any, cleanup?: function}=} onSend - Optional send hook
+ * @property {function(string[], string|number, any, Object): Promise<any>=} onReceive - Optional receive hook
+ */
+
+/**
+ * Register a custom type handler plugin
+ *
+ * Plugins extend JSS to handle custom types beyond the built-in set.
+ * Each plugin is identified by a single-character tag that appears in
+ * the serialized format (e.g., `"key<!X>": value`).
+ *
+ * ## Behavior Rules
+ *
+ * - **Check gates encode**: The `check` function determines if this plugin
+ *   should handle a value. If it returns true, encode is called.
+ * - **Error on conflict**: Throws if the tag conflicts with a built-in type
+ *   or an already-registered custom plugin.
+ *
+ * @param {string} tag - Single character tag identifier (e.g., 'X', 'Z')
+ * @param {PluginConfig} config - Plugin configuration object
+ * @throws {Error} If tag is not a single character
+ * @throws {Error} If tag conflicts with built-in type
+ * @throws {Error} If tag is already registered
+ * @throws {Error} If required functions are missing
+ *
+ * @example
+ * // Register a plugin for a custom Point type
+ * register('P', {
+ *   check: (key, value) => value instanceof Point,
+ *   encode: (path, key, value) => [value.x, value.y],
+ *   decode: (value) => new Point(value[0], value[1])
+ * })
+ *
+ * @example
+ * // Register a plugin with lifecycle hooks for external resources
+ * register('L', {
+ *   check: (key, value) => Buffer.isBuffer(value),
+ *   encode: (path, key, value) => '__pending__',
+ *   decode: (value) => value, // Hash returned as-is
+ *   onSend: (path, key, value, ctx) => {
+ *     const hash = generateHash(ctx.queryId, path.join('.'))
+ *     ctx.fileTransfer.registerDownload(hash, value, 'application/octet-stream', ctx.clientId)
+ *     return { replace: hash }
+ *   }
+ * })
+ */
+function register(tag, config) {
+  // Validate tag format
+  if (typeof tag !== "string" || tag.length !== 1) {
+    throw new Error(`Tag must be a single character, got: '${tag}'`);
+  }
+
+  // Check for built-in tag conflict
+  if (builtInTags.includes(tag)) {
+    throw new Error(`Tag '${tag}' conflicts with built-in type`);
+  }
+
+  // Check for duplicate registration
+  if (plugins.has(tag)) {
+    throw new Error(`Tag '${tag}' is already registered`);
+  }
+
+  // Validate required functions
+  if (typeof config.check !== "function") {
+    throw new Error("Plugin must provide a 'check' function");
+  }
+  if (typeof config.encode !== "function") {
+    throw new Error("Plugin must provide an 'encode' function");
+  }
+  if (typeof config.decode !== "function") {
+    throw new Error("Plugin must provide a 'decode' function");
+  }
+
+  // Validate optional functions if provided
+  if (config.onSend !== undefined && typeof config.onSend !== "function") {
+    throw new Error("Plugin 'onSend' must be a function if provided");
+  }
+  if (
+    config.onReceive !== undefined &&
+    typeof config.onReceive !== "function"
+  ) {
+    throw new Error("Plugin 'onReceive' must be a function if provided");
+  }
+
+  plugins.set(tag, config);
+}
+
+/**
+ * Get a plugin by its tag
+ *
+ * @param {string} tag - The tag character to look up
+ * @returns {PluginConfig|undefined} The plugin config or undefined if not found
+ *
+ * @example
+ * const plugin = getPlugin('X')
+ * if (plugin) {
+ *   const decoded = plugin.decode(value, path, context)
+ * }
+ */
+function getPlugin(tag) {
+  return plugins.get(tag);
+}
+
+/**
+ * Get all registered plugins
+ *
+ * Returns the internal Map for iteration during encoding.
+ *
+ * @returns {Map<string, PluginConfig>} Map of tag -> plugin config
+ *
+ * @example
+ * for (const [tag, plugin] of getAllPlugins()) {
+ *   if (plugin.check(key, value)) {
+ *     return [tag, plugin.encode(path, key, value, context)]
+ *   }
+ * }
+ */
+function getAllPlugins() {
+  return plugins;
+}
+
+/**
+ * Check if a tag has a registered plugin
+ *
+ * @param {string} tag - The tag to check
+ * @returns {boolean} True if a plugin is registered for this tag
+ *
+ * @example
+ * if (hasPlugin('X')) {
+ *   // Handle custom type
+ * }
+ */
+function hasPlugin(tag) {
+  return plugins.has(tag);
+}
+
+/**
+ * Clear all registered plugins
+ *
+ * Used primarily for testing to reset the registry between tests.
+ * Does not affect built-in types.
+ *
+ * @example
+ * beforeEach(() => {
+ *   clearPlugins()
+ * })
+ */
+function clearPlugins() {
+  plugins.clear();
+}
+
+module.exports = {
+  register,
+  getPlugin,
+  getAllPlugins,
+  hasPlugin,
+  clearPlugins,
+  builtInTags,
+};