scon-notation 1.0.0

package/src/schema-registry.js

@@ -0,0 +1,204 @@
+// src/schema-registry.js
+// Port of bX\Scon\SchemaRegistry — schema/response/security registration and resolution
+
+export class SchemaRegistry {
+
+    constructor() {
+        this.schemas = {};
+        this.responses = {};
+        this.security = {};
+        this.resolving = {}; // cycle detection
+    }
+
+    // Register a definition
+    register(type, name, definition) {
+        switch (type) {
+            case 's':   this.schemas[name] = definition; break;
+            case 'r':   this.responses[name] = definition; break;
+            case 'sec': this.security[name] = definition; break;
+            default: throw new Error(`Unknown definition type: ${type}`);
+        }
+    }
+
+    // Resolve a reference by type and name
+    resolve(type, name) {
+        const store = this._getStore(type);
+        if (!Object.hasOwn(store, name)) {
+            throw new Error(`Undefined reference: @${type}:${name}`);
+        }
+
+        const refKey = `${type}:${name}`;
+        if (Object.hasOwn(this.resolving, refKey)) {
+            // Circular reference — return marker for lazy resolution
+            return { '$ref': `#/definitions/${name}` };
+        }
+
+        this.resolving[refKey] = true;
+        const resolved = this._deepResolveRefs(store[name]);
+        delete this.resolving[refKey];
+
+        return resolved;
+    }
+
+    // Resolve with override (deep merge + dot-notation + field removal)
+    resolveWithOverride(type, name, overrides) {
+        let base = this.resolve(type, name);
+
+        // Process field removals first
+        const removals = [];
+        const merges = {};
+        for (const key of Object.keys(overrides)) {
+            if (key.startsWith('-')) {
+                removals.push(key.slice(1));
+            } else {
+                merges[key] = overrides[key];
+            }
+        }
+
+        // Apply removals
+        for (const field of removals) {
+            if (field.includes('.')) {
+                this._unsetDotPath(base, field);
+            } else {
+                delete base[field];
+            }
+        }
+
+        // Apply deep merges with dot-notation support
+        for (const [key, val] of Object.entries(merges)) {
+            if (key.includes('.')) {
+                this._setDotPath(base, key, val);
+            } else {
+                if (
+                    val !== null && typeof val === 'object' && !Array.isArray(val) &&
+                    Object.hasOwn(base, key) && typeof base[key] === 'object' && base[key] !== null && !Array.isArray(base[key])
+                ) {
+                    base[key] = this._deepMerge(base[key], val);
+                } else {
+                    base[key] = val;
+                }
+            }
+        }
+
+        return base;
+    }
+
+    // Resolve polymorphic references (oneOf with pipe)
+    resolvePolymorphic(refs) {
+        const schemas = refs.map(ref => this.resolve(ref.type, ref.name));
+        return { oneOf: schemas };
+    }
+
+    // Check if a definition exists
+    has(type, name) {
+        try {
+            const store = this._getStore(type);
+            return Object.hasOwn(store, name);
+        } catch {
+            return false;
+        }
+    }
+
+    // Get all definitions of a type (for encoding)
+    getAll(type) {
+        try {
+            return this._getStore(type);
+        } catch {
+            return {};
+        }
+    }
+
+    // Reset all definitions
+    reset() {
+        this.schemas = {};
+        this.responses = {};
+        this.security = {};
+        this.resolving = {};
+    }
+
+    // --- Private ---
+
+    _getStore(type) {
+        switch (type) {
+            case 's':   return this.schemas;
+            case 'r':   return this.responses;
+            case 'sec': return this.security;
+            default: throw new Error(`Unknown ref type: ${type}`);
+        }
+    }
+
+    // Deep-resolve any @ref markers within a definition
+    _deepResolveRefs(data) {
+        if (data === null || typeof data !== 'object') return data;
+        if (Array.isArray(data)) return data.map(item => this._deepResolveRefs(item));
+
+        const result = {};
+        for (const [key, val] of Object.entries(data)) {
+            if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+                if ('@ref' in val) {
+                    const ref = val['@ref'];
+                    if ('@overrides' in val) {
+                        result[key] = this.resolveWithOverride(ref.type, ref.name, val['@overrides']);
+                    } else {
+                        result[key] = this.resolve(ref.type, ref.name);
+                    }
+                } else if ('@polymorphic' in val) {
+                    result[key] = this.resolvePolymorphic(val['@polymorphic']);
+                } else {
+                    result[key] = this._deepResolveRefs(val);
+                }
+            } else {
+                result[key] = val;
+            }
+        }
+        return result;
+    }
+
+    // Set a value using dot-notation path (a.b.c = val)
+    _setDotPath(obj, path, val) {
+        const keys = path.split('.');
+        let ref = obj;
+        for (let i = 0; i < keys.length; i++) {
+            if (i === keys.length - 1) {
+                ref[keys[i]] = val;
+            } else {
+                if (!Object.hasOwn(ref, keys[i]) || typeof ref[keys[i]] !== 'object' || ref[keys[i]] === null) {
+                    ref[keys[i]] = {};
+                }
+                ref = ref[keys[i]];
+            }
+        }
+    }
+
+    // Unset a value using dot-notation path
+    _unsetDotPath(obj, path) {
+        const keys = path.split('.');
+        let ref = obj;
+        for (let i = 0; i < keys.length; i++) {
+            if (i === keys.length - 1) {
+                delete ref[keys[i]];
+            } else {
+                if (!Object.hasOwn(ref, keys[i]) || typeof ref[keys[i]] !== 'object' || ref[keys[i]] === null) {
+                    return;
+                }
+                ref = ref[keys[i]];
+            }
+        }
+    }
+
+    // Deep merge: objects merge recursively, arrays replace
+    _deepMerge(base, override) {
+        const result = { ...base };
+        for (const [key, val] of Object.entries(override)) {
+            if (
+                val !== null && typeof val === 'object' && !Array.isArray(val) &&
+                Object.hasOwn(result, key) && typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])
+            ) {
+                result[key] = this._deepMerge(result[key], val);
+            } else {
+                result[key] = val;
+            }
+        }
+        return result;
+    }
+}

package/src/scon.js

@@ -0,0 +1,121 @@
+// src/scon.js
+// S.C.O.N. — Schema-Compact Object Notation
+// Extension: .scon | Content-Type: text/scon; charset=utf-8
+//
+// WASM-accelerated: loads Rust tape decoder via WebAssembly when available,
+// falls back to pure JS implementation transparently.
+//
+// Performance comparison (OpenAPI 3.1 spec, 71 endpoints):
+//
+// Format           | Bytes   | Ratio | Gzip    |
+// -----------------|---------|-------|---------|
+// JSON             | 90,886  | 1.00x |  4,632  |
+// SCON             | 26,347  | 0.29x |  3,969  |
+// SCON (minified)  | 20,211  | 0.22x |  3,818  |
+//
+// SCON achieves ~71% reduction vs JSON by extracting repeated schema
+// definitions (s:, r:, sec:) and referencing them (@s:).
+
+import { Encoder } from './encoder.js';
+import { Decoder } from './decoder.js';
+import { Minifier } from './minifier.js';
+import { Validator } from './validator.js';
+
+// WASM module — lazy-loaded, null until init
+let wasmModule = null;
+let wasmInitPromise = null;
+
+async function loadWasm() {
+    try {
+        const wasm = await import('scon-wasm');
+        if (wasm.default && typeof wasm.default === 'function') {
+            await wasm.default();
+        }
+        wasmModule = wasm;
+    } catch {
+        wasmModule = null;
+    }
+}
+
+// Trigger WASM load on import (non-blocking)
+function ensureWasm() {
+    if (!wasmInitPromise) {
+        wasmInitPromise = loadWasm();
+    }
+    return wasmInitPromise;
+}
+
+// Start loading immediately
+ensureWasm();
+
+// Encode JS data to SCON string
+// Returns string (sync) or Promise<string> if options.autoExtract is true
+function encode(data, options = {}) {
+    // WASM fast path — no schema/response/security options (those are JS-only features)
+    if (wasmModule && !options.autoExtract && !options.schemas && !options.responses && !options.security) {
+        const indent = options.indent ?? 1;
+        return indent > 1
+            ? wasmModule.scon_encode_indent(data, indent)
+            : wasmModule.scon_encode(data);
+    }
+    const encoder = new Encoder(options);
+    const schemas = options.schemas || {};
+    const responses = options.responses || {};
+    const security = options.security || {};
+    return encoder.encode(data, schemas, responses, security);
+}
+
+// Decode SCON string to JS object
+function decode(sconString, options = {}) {
+    // WASM fast path — single crossing: tape→JSON string in WASM, JSON.parse in V8 native C++
+    if (wasmModule && !options.schemas && !options.responses && !options.security) {
+        return JSON.parse(wasmModule.scon_to_json(sconString));
+    }
+    const decoder = new Decoder(options);
+    return decoder.decode(sconString);
+}
+
+// Minify SCON string to single line
+function minify(sconString) {
+    if (wasmModule) {
+        return wasmModule.scon_minify(sconString);
+    }
+    return Minifier.minify(sconString);
+}
+
+// Expand minified SCON to indented format
+function expand(minifiedString, options = {}) {
+    const indent = options.indent ?? 1;
+    if (wasmModule) {
+        return wasmModule.scon_expand(minifiedString, indent);
+    }
+    return Minifier.expand(minifiedString, indent);
+}
+
+// Validate SCON data against rules (JS-only, no WASM equivalent)
+function validate(data, options = {}) {
+    const validator = new Validator(options);
+    return validator.validate(data);
+}
+
+// Wait for WASM to be ready (optional — operations work without it via fallback)
+async function ready() {
+    await ensureWasm();
+    return wasmModule !== null;
+}
+
+const SCON = Object.freeze({
+    encode,
+    decode,
+    minify,
+    expand,
+    validate,
+    ready,
+    // Aliases estilo JSON
+    parse: decode,
+    stringify: encode,
+});
+
+export default SCON;
+export { SCON, Encoder, Decoder, Minifier, Validator };
+export { SchemaRegistry } from './schema-registry.js';

package/src/tree-hash.js

@@ -0,0 +1,227 @@
+// src/tree-hash.js
+// Port of bX\TreeHash — structural hashing via xxh128 (hash-wasm)
+
+import { createXXHash128 } from 'hash-wasm';
+
+let hasherInstance = null;
+
+// Initialize hash-wasm xxh128 (lazy, once)
+async function getHasher() {
+    if (!hasherInstance) {
+        hasherInstance = await createXXHash128();
+    }
+    return hasherInstance;
+}
+
+// Compute xxh128 hex digest of a string
+async function xxh128(str) {
+    const hasher = await getHasher();
+    hasher.init();
+    hasher.update(str);
+    return hasher.digest('hex');
+}
+
+// Sync xxh128 — only works after init (for fingerprint fallback)
+function xxh128Sync(str) {
+    if (!hasherInstance) {
+        throw new Error('TreeHash not initialized. Call await TreeHash.hash() first or await TreeHash.init()');
+    }
+    hasherInstance.init();
+    hasherInstance.update(str);
+    return hasherInstance.digest('hex');
+}
+
+function isSequential(arr) {
+    if (!Array.isArray(arr)) return false;
+    if (arr.length === 0) return true;
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr)) return false;
+    }
+    return true;
+}
+
+function recursiveKsort(data) {
+    if (!Array.isArray(data) && typeof data === 'object' && data !== null) {
+        const sorted = {};
+        const keys = Object.keys(data).sort();
+        for (const k of keys) {
+            sorted[k] = recursiveKsort(data[k]);
+        }
+        return sorted;
+    }
+    if (Array.isArray(data)) {
+        return data.map(item => {
+            if (typeof item === 'object' && item !== null) return recursiveKsort(item);
+            return item;
+        });
+    }
+    return data;
+}
+
+function collectHashesHybrid(data, path, index, minKeys) {
+    for (const [key, val] of Object.entries(data)) {
+        if (val === null || typeof val !== 'object') continue;
+
+        const childPath = path === '' ? String(key) : `${path}.${key}`;
+
+        if (Array.isArray(val)) {
+            // Traverse lists to find sub-objects
+            for (let i = 0; i < val.length; i++) {
+                const item = val[i];
+                if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
+                    const itemPath = `${childPath}.[${i}]`;
+                    const itemKeys = Object.keys(item);
+                    if (itemKeys.length >= minKeys) {
+                        const json = JSON.stringify(item);
+                        const hash = xxh128Sync(json);
+                        if (Object.hasOwn(index, hash)) {
+                            index[hash].count++;
+                        } else {
+                            index[hash] = { count: 1, path: itemPath, data: item };
+                        }
+                    }
+                    collectHashesHybrid(item, itemPath, index, minKeys);
+                }
+            }
+        } else {
+            // Associative object
+            const valKeys = Object.keys(val);
+            if (valKeys.length >= minKeys) {
+                const json = JSON.stringify(val);
+                const hash = xxh128Sync(json);
+                if (Object.hasOwn(index, hash)) {
+                    index[hash].count++;
+                } else {
+                    index[hash] = { count: 1, path: childPath, data: val };
+                }
+            }
+            collectHashesHybrid(val, childPath, index, minKeys);
+        }
+    }
+}
+
+// --- Fingerprint internals (sync, for equals/diff) ---
+
+function primitiveFP(val) {
+    if (val === null) return '\x00';
+    if (val === true) return '\x01\x01';
+    if (val === false) return '\x01\x00';
+    if (typeof val === 'number') {
+        if (Number.isInteger(val)) return '\x02' + String(val);
+        return '\x03' + String(val);
+    }
+    if (typeof val === 'string') return '\x04' + val;
+    return '\x04' + String(val);
+}
+
+function fingerprint(data) {
+    if (data === null || typeof data !== 'object') {
+        return primitiveFP(data);
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0) return xxh128Sync('A:0');
+        let buf = 'A:' + data.length;
+        for (const item of data) {
+            buf += '|' + fingerprint(item);
+        }
+        return xxh128Sync(buf);
+    }
+    // Object
+    const keys = Object.keys(data).sort();
+    if (keys.length === 0) return xxh128Sync('A:0');
+    let buf = 'O:' + keys.length;
+    for (const key of keys) {
+        buf += '|' + key + ':' + fingerprint(data[key]);
+    }
+    return xxh128Sync(buf);
+}
+
+export class TreeHash {
+
+    // Initialize hash-wasm (call once, or auto-inits on first use)
+    static async init() {
+        await getHasher();
+    }
+
+    // Hash any value → string hex 32 chars (xxh128) — async
+    static async hash(data) {
+        await getHasher(); // ensure init
+        const fp = fingerprint(data);
+        if (fp.length === 32 && /^[0-9a-f]+$/.test(fp)) return fp;
+        return xxh128Sync(fp);
+    }
+
+    // Hash a tree with frequency index for dedup — async
+    // normalize=true: ksort keys for cross-source dedup
+    static async hashTree(data, basePath = '', minKeys = 2, normalize = true) {
+        await getHasher(); // ensure init
+
+        if (normalize) {
+            data = recursiveKsort(data);
+        }
+
+        const index = {};
+        collectHashesHybrid(data, basePath, index, minKeys);
+
+        const json = JSON.stringify(data);
+        const rootHash = await xxh128(json);
+
+        return { root_hash: rootHash, index };
+    }
+
+    // Compare two structures: are they identical? — async (needs init)
+    static async equals(a, b) {
+        if (a === b) return true;
+        await getHasher();
+        return fingerprint(a) === fingerprint(b);
+    }
+
+    // Structural diff: returns paths where they differ — async (needs init)
+    static async diff(a, b, path = '') {
+        await getHasher();
+        return TreeHash._diffSync(a, b, path);
+    }
+
+    static _diffSync(a, b, path) {
+        if (a === b) return [];
+        if (fingerprint(a) === fingerprint(b)) return [];
+
+        if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null || Array.isArray(a) || Array.isArray(b)) {
+            return [{ path, type: 'changed', old: a, new: b }];
+        }
+
+        const diffs = [];
+        const allKeys = [...new Set([...Object.keys(a), ...Object.keys(b)])];
+
+        for (const key of allKeys) {
+            const currentPath = path === '' ? String(key) : `${path}.${key}`;
+
+            if (!(key in a)) {
+                diffs.push({ path: currentPath, type: 'added', value: b[key] });
+                continue;
+            }
+            if (!(key in b)) {
+                diffs.push({ path: currentPath, type: 'removed', value: a[key] });
+                continue;
+            }
+
+            const valA = a[key];
+            const valB = b[key];
+
+            if (valA === valB) continue;
+            if (fingerprint(valA) === fingerprint(valB)) continue;
+
+            if (
+                typeof valA === 'object' && typeof valB === 'object' &&
+                valA !== null && valB !== null &&
+                !Array.isArray(valA) && !Array.isArray(valB)
+            ) {
+                diffs.push(...TreeHash._diffSync(valA, valB, currentPath));
+            } else {
+                diffs.push({ path: currentPath, type: 'changed', old: valA, new: valB });
+            }
+        }
+
+        return diffs;
+    }
+}

package/src/validator.js

@@ -0,0 +1,131 @@
+// src/validator.js
+// Port of bX\Scon\Validator — SCON data validation
+
+const ENFORCE_RULES = {
+    'openapi:3.1': {
+        required: ['openapi', 'info', 'paths'],
+        'info.required': ['title', 'version'],
+    },
+    'openapi:3.0': {
+        required: ['openapi', 'info', 'paths'],
+        'info.required': ['title', 'version'],
+    },
+};
+
+export class Validator {
+
+    constructor(options = {}) {
+        this.mode = options.mode || 'warn';
+        this.enforce = options.enforce || null;
+        this.warnings = [];
+        this.errors = [];
+    }
+
+    // Validate data and return result
+    validate(data) {
+        this.warnings = [];
+        this.errors = [];
+
+        if (typeof data !== 'object' || data === null) {
+            this._addIssue('Root value must be an object or array');
+            return this._result();
+        }
+
+        // Apply enforce rules if configured
+        if (this.enforce !== null && this.enforce in ENFORCE_RULES) {
+            this._enforceSpec(data, ENFORCE_RULES[this.enforce]);
+        }
+
+        return this._result();
+    }
+
+    // Validate a schema definition
+    validateSchema(name, schema) {
+        this.warnings = [];
+        this.errors = [];
+
+        if (!schema || Object.keys(schema).length === 0) {
+            this._addIssue(`Schema '${name}' is empty`);
+        }
+
+        return this._result();
+    }
+
+    // Validate data against a schema (field presence)
+    validateAgainstSchema(data, schema, path = '') {
+        this.warnings = [];
+        this.errors = [];
+
+        for (const [key, def] of Object.entries(schema)) {
+            const fieldPath = path ? `${path}.${key}` : key;
+            const isRequired = key.endsWith('!');
+            const cleanKey = key.replace(/!$/, '');
+
+            // PHP isset() returns false for null — match that behavior
+            if (isRequired && (data[cleanKey] === undefined || data[cleanKey] === null)) {
+                this._addIssue(`Missing required field: ${fieldPath}`);
+            }
+        }
+
+        // Check for extra fields
+        const schemaKeys = Object.keys(schema).map(k => k.replace(/!$/, ''));
+        if (this.mode === 'strict') {
+            for (const dataKey of Object.keys(data)) {
+                if (!schemaKeys.includes(dataKey)) {
+                    this._addIssue(`Extra field not in schema: ${path}.${dataKey}`);
+                }
+            }
+        } else if (this.mode === 'warn') {
+            for (const dataKey of Object.keys(data)) {
+                if (!schemaKeys.includes(dataKey)) {
+                    this.warnings.push(`Extra field: ${path}.${dataKey}`);
+                }
+            }
+        }
+
+        return this._result();
+    }
+
+    _enforceSpec(data, rules) {
+        if (rules.required) {
+            for (const field of rules.required) {
+                if (data[field] === undefined || data[field] === null) {
+                    this._addIssue(`Missing required field per ${this.enforce}: ${field}`);
+                }
+            }
+        }
+
+        // Check nested required fields (pattern: parent.required)
+        for (const [ruleKey, ruleFields] of Object.entries(rules)) {
+            if (ruleKey === 'required') continue;
+            if (ruleKey.endsWith('.required')) {
+                const parentKey = ruleKey.slice(0, -9);
+                if (data[parentKey] !== undefined && data[parentKey] !== null && typeof data[parentKey] === 'object') {
+                    for (const field of ruleFields) {
+                        if (data[parentKey][field] === undefined || data[parentKey][field] === null) {
+                            this._addIssue(`Missing required field per ${this.enforce}: ${parentKey}.${field}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    _addIssue(msg) {
+        if (this.mode === 'strict' || this.enforce !== null) {
+            this.errors.push(msg);
+        } else if (this.mode === 'warn') {
+            this.warnings.push(msg);
+        }
+    }
+
+    _result() {
+        return {
+            valid: this.errors.length === 0,
+            warnings: this.warnings,
+            errors: this.errors,
+            mode: this.mode,
+            enforce: this.enforce,
+        };
+    }
+}