@datumesh/verify 0.0.0-stage → 0.1.1

package/dist/cjs/unicode.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAssigned = isAssigned;
+exports.combiningClass = combiningClass;
+exports.nfc = nfc;
+exports.codePoints = codePoints;
+exports.isNFC = isNFC;
+exports.hasLoneSurrogate = hasLoneSurrogate;
+// Unicode 15.1 character checks for SPEC.md 3.5, from tables shipped with this library
+// (src/unicode-data.ts). Nothing here calls String.prototype.normalize or uses \p{...}
+// regular expressions, so results do not depend on the JavaScript engine's Unicode version.
+const unicode_data_js_1 = require("./unicode-data.js");
+/** True when the code point is assigned in Unicode 15.1 (General_Category != Cn). */
+function isAssigned(cp) {
+    let lo = 0;
+    let hi = unicode_data_js_1.ASSIGNED.length / 2 - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (cp < unicode_data_js_1.ASSIGNED[2 * mid])
+            hi = mid - 1;
+        else if (cp > unicode_data_js_1.ASSIGNED[2 * mid + 1])
+            lo = mid + 1;
+        else
+            return true;
+    }
+    return false;
+}
+let cccMap = null;
+let decompMap = null;
+let compMap = null;
+function tables() {
+    if (cccMap)
+        return;
+    const c = new Map();
+    for (const run of unicode_data_js_1.CCC.split(';')) {
+        const [a, b, k] = run.split(':');
+        const end = parseInt(b, 16);
+        for (let cp = parseInt(a, 16); cp <= end; cp++)
+            c.set(cp, Number(k));
+    }
+    const d = new Map();
+    for (const e of unicode_data_js_1.DECOMP.split(';')) {
+        const [cp, seq] = e.split(':');
+        d.set(parseInt(cp, 16), seq.split('.').map((h) => parseInt(h, 16)));
+    }
+    const m = new Map();
+    for (const e of unicode_data_js_1.COMP.split(';')) {
+        const [pair, cp] = e.split(':');
+        const [x, y] = pair.split('.').map((h) => parseInt(h, 16));
+        m.set(x * 0x110000 + y, parseInt(cp, 16));
+    }
+    cccMap = c;
+    decompMap = d;
+    compMap = m;
+}
+/** Canonical combining class (Unicode 15.1). */
+function combiningClass(cp) {
+    tables();
+    return cccMap.get(cp) ?? 0;
+}
+const SBASE = 0xac00;
+const LBASE = 0x1100;
+const VBASE = 0x1161;
+const TBASE = 0x11a7;
+const LCOUNT = 19;
+const VCOUNT = 21;
+const TCOUNT = 28;
+const NCOUNT = VCOUNT * TCOUNT;
+const SCOUNT = LCOUNT * NCOUNT;
+function decompose(cp, out) {
+    const s = cp - SBASE;
+    if (s >= 0 && s < SCOUNT) {
+        out.push(LBASE + Math.floor(s / NCOUNT), VBASE + Math.floor((s % NCOUNT) / TCOUNT));
+        if (s % TCOUNT)
+            out.push(TBASE + (s % TCOUNT));
+        return;
+    }
+    const d = decompMap.get(cp);
+    if (d)
+        out.push(...d);
+    else
+        out.push(cp);
+}
+function compose(a, b) {
+    const l = a - LBASE;
+    if (l >= 0 && l < LCOUNT) {
+        const v = b - VBASE;
+        if (v >= 0 && v < VCOUNT)
+            return SBASE + (l * VCOUNT + v) * TCOUNT;
+        return undefined;
+    }
+    const s = a - SBASE;
+    if (s >= 0 && s < SCOUNT && s % TCOUNT === 0) {
+        const t = b - TBASE;
+        if (t > 0 && t < TCOUNT)
+            return a + t;
+        return undefined;
+    }
+    return compMap.get(a * 0x110000 + b);
+}
+/** Normalization Form C of a code point sequence (UAX #15), using Unicode 15.1 data. */
+function nfc(cps) {
+    tables();
+    const d = [];
+    for (const cp of cps)
+        decompose(cp, d);
+    // Canonical ordering: stable sort of each run of non-starters by combining class.
+    for (let i = 1; i < d.length; i++) {
+        const cc = combiningClass(d[i]);
+        if (cc === 0)
+            continue;
+        let j = i;
+        while (j > 0) {
+            const pc = combiningClass(d[j - 1]);
+            if (pc <= cc)
+                break;
+            const t = d[j];
+            d[j] = d[j - 1];
+            d[j - 1] = t;
+            j--;
+        }
+    }
+    // Canonical composition.
+    const res = [];
+    let starter = -1;
+    let lastCC = 0;
+    for (const ch of d) {
+        const cc = combiningClass(ch);
+        if (starter >= 0) {
+            const adjacent = res.length - 1 === starter;
+            if (adjacent || (lastCC !== 0 && lastCC < cc)) {
+                const c = compose(res[starter], ch);
+                if (c !== undefined) {
+                    res[starter] = c;
+                    continue;
+                }
+            }
+        }
+        if (cc === 0)
+            starter = res.length;
+        lastCC = cc;
+        res.push(ch);
+    }
+    return res;
+}
+/** Code points of a string (lone surrogates come out as themselves). */
+function codePoints(s) {
+    const out = [];
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff) {
+                out.push(0x10000 + ((c - 0xd800) << 10) + (d - 0xdc00));
+                i++;
+                continue;
+            }
+        }
+        out.push(c);
+    }
+    return out;
+}
+/** True when the string is in NFC under Unicode 15.1. */
+function isNFC(s) {
+    const cps = codePoints(s);
+    // Below U+0300 every character is a starter with NFC_Quick_Check=Yes.
+    if (cps.every((c) => c < 0x300))
+        return true;
+    const n = nfc(cps);
+    if (n.length !== cps.length)
+        return false;
+    for (let i = 0; i < n.length; i++)
+        if (n[i] !== cps[i])
+            return false;
+    return true;
+}
+/** True when the string contains an unpaired surrogate. */
+function hasLoneSurrogate(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const d = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;
+            if (d >= 0xdc00 && d <= 0xdfff)
+                i++;
+            else
+                return true;
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff)
+            return true;
+    }
+    return false;
+}

package/dist/cjs/uri.d.ts

@@ -0,0 +1,31 @@
+import { type TypeName } from './lexical.js';
+/** A typed scalar (SPEC 4.1). */
+export interface TypedScalar {
+    type: TypeName;
+    value: string | boolean;
+}
+/** A cell reference (SPEC 4.3): what a cell URI denotes. `"*"` marks a slice. */
+export interface CellRef {
+    args: Record<string, TypedScalar | '*'>;
+    fn: string;
+    ns: string;
+    asof?: string;
+}
+/** A function descriptor's `signature` member (SPEC 7). */
+export interface Signature {
+    args: Record<string, {
+        type: TypeName;
+        valid: boolean;
+    }>;
+    returns: TypeName;
+}
+/**
+ * Parse a cell URI into a cell reference, taking argument types from the function's
+ * signature (SPEC 5.4). Checks run in the order of SPEC 5.4 and the first failure is thrown as
+ * a DatumeshError.
+ */
+export declare function parseUri(uri: string, signature: Signature | unknown): CellRef;
+/** Write the unique cell URI of a cell reference (SPEC 5.2). Throws DatumeshError if invalid. */
+export declare function formatUri(ref: CellRef | unknown): string;
+/** The HTTPS URL of a cell URI on mesh host `mesh` (SPEC 5.3). */
+export declare function httpsUrl(uri: string, mesh: string): string;

package/dist/cjs/uri.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUri = parseUri;
+exports.formatUri = formatUri;
+exports.httpsUrl = httpsUrl;
+// Cell URIs (SPEC.md section 5).
+const errors_js_1 = require("./errors.js");
+const json_js_1 = require("./json.js");
+const lexical_js_1 = require("./lexical.js");
+const utf8_js_1 = require("./utf8.js");
+const validate_js_1 = require("./validate.js");
+const SCHEME = 'cell://';
+function isLiteral(c) {
+    return /^[A-Za-z0-9\-._~:]$/.test(c);
+}
+function decodeValue(v, path) {
+    const bytes = [];
+    for (let i = 0; i < v.length;) {
+        const c = v[i];
+        if (c === '%') {
+            const h = v.slice(i + 1, i + 3);
+            if (!/^[0-9A-F]{2}$/.test(h))
+                (0, errors_js_1.fail)('E_CANON_PERCENT', 'percent-encoding must be % and two uppercase hex digits', path);
+            const b = parseInt(h, 16);
+            if (isLiteral(String.fromCharCode(b)))
+                (0, errors_js_1.fail)('E_CANON_PERCENT', `${JSON.stringify(String.fromCharCode(b))} must not be percent-encoded`, path);
+            bytes.push(b);
+            i += 3;
+        }
+        else if (isLiteral(c)) {
+            bytes.push(c.charCodeAt(0));
+            i++;
+        }
+        else {
+            const cp = v.codePointAt(i);
+            (0, errors_js_1.fail)('E_CANON_PERCENT', `${JSON.stringify(String.fromCodePoint(cp))} must be percent-encoded`, path);
+        }
+    }
+    const s = (0, utf8_js_1.utf8Decode)(Uint8Array.from(bytes));
+    if (s === null)
+        (0, errors_js_1.fail)('E_CANON_PERCENT', 'percent-encoded bytes are not UTF-8', path);
+    return s;
+}
+function encodeValue(s) {
+    let out = '';
+    for (const b of (0, utf8_js_1.utf8Encode)(s)) {
+        const c = String.fromCharCode(b);
+        out += isLiteral(c) ? c : `%${b.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return out;
+}
+function readSignature(signature) {
+    if (signature === null || signature === undefined)
+        throw new TypeError('parseUri needs the function signature (descriptor.signature)');
+    let sig;
+    try {
+        sig = (0, json_js_1.toJson)(signature);
+        (0, validate_js_1.structSignature)(sig, 'signature');
+        (0, validate_js_1.canonSignature)(sig, 'signature');
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.DatumeshError)
+            throw new errors_js_1.DatumeshError(e.code, `invalid signature: ${e.detail}`, e.path?.replace(/^\$/, 'signature') ?? 'signature');
+        throw e;
+    }
+    return sig;
+}
+/**
+ * Parse a cell URI into a cell reference, taking argument types from the function's
+ * signature (SPEC 5.4). Checks run in the order of SPEC 5.4 and the first failure is thrown as
+ * a DatumeshError.
+ */
+function parseUri(uri, signature) {
+    if (typeof uri !== 'string')
+        throw new TypeError('uri must be a string');
+    const sig = readSignature(signature);
+    const declared = sig.args;
+    // 1. Outer grammar.
+    if (!uri.startsWith(SCHEME) || uri.includes('#'))
+        (0, errors_js_1.fail)('E_PARSE_URI', 'not cell://<namespace>/<function>[?<query>] without fragment', '$');
+    const rest = uri.slice(SCHEME.length);
+    const q = rest.indexOf('?');
+    const path = q < 0 ? rest : rest.slice(0, q);
+    const query = q < 0 ? null : rest.slice(q + 1);
+    if (query === '')
+        (0, errors_js_1.fail)('E_PARSE_URI', 'empty query', '$');
+    // SPEC 5.1 lists userinfo and a port among outer-grammar failures (E_PARSE_URI). (The
+    // reference tool reports them as E_CANON_NAME; see DEFECTS.md.)
+    const authority = path.split('/')[0];
+    if (authority.includes('@'))
+        (0, errors_js_1.fail)('E_PARSE_URI', 'a cell URI has no userinfo', '$');
+    if (authority.includes(':'))
+        (0, errors_js_1.fail)('E_PARSE_URI', 'a cell URI has no port', '$');
+    const params = (query === null ? [] : query.split('&')).map((p) => {
+        const e = p.indexOf('=');
+        if (e < 0)
+            (0, errors_js_1.fail)('E_PARSE_URI', `parameter without '=': ${JSON.stringify(p)}`, '$');
+        return { name: p.slice(0, e), value: p.slice(e + 1) };
+    });
+    // 2. Namespace and function name.
+    const slash = path.lastIndexOf('/');
+    if (slash < 0)
+        (0, errors_js_1.fail)('E_CANON_NAME', 'missing namespace', 'uri.path');
+    const ns = path.slice(0, slash);
+    const fn = path.slice(slash + 1);
+    (0, lexical_js_1.checkNamespace)(ns, 'uri.path');
+    (0, lexical_js_1.checkName)(fn, 'uri.path');
+    if (path.length > lexical_js_1.LIMITS.function_name)
+        (0, errors_js_1.fail)('E_CANON_LIMIT', 'function name too long', 'uri.path');
+    // 3. Parameter names, left to right.
+    const at = (n) => `uri.query.${n}`;
+    // asof: when the last parameter is asof, that is the asof parameter and any earlier asof is a
+    // repetition (E_CANON_ARG_DUPLICATE); otherwise an asof anywhere is out of place
+    // (E_CANON_ARG_ORDER). SPEC 5.2 does not say which applies when both do; this matches the
+    // reference tool (DEFECTS.md).
+    let prev = null;
+    const lastIsAsof = params.length > 0 && params[params.length - 1].name === 'asof';
+    params.forEach((p, i) => {
+        if (p.name === 'asof') {
+            if (!lastIsAsof)
+                (0, errors_js_1.fail)('E_CANON_ARG_ORDER', 'asof appears once, as the last parameter', at(p.name));
+            if (i !== params.length - 1)
+                (0, errors_js_1.fail)('E_CANON_ARG_DUPLICATE', 'asof repeated', at(p.name));
+            return;
+        }
+        (0, lexical_js_1.checkArgName)(p.name, at(p.name));
+        if (prev !== null && p.name === prev)
+            (0, errors_js_1.fail)('E_CANON_ARG_DUPLICATE', `argument ${JSON.stringify(p.name)} repeated`, at(p.name));
+        if (prev !== null && p.name < prev)
+            (0, errors_js_1.fail)('E_CANON_ARG_ORDER', 'arguments must be sorted by name', at(p.name));
+        prev = p.name;
+    });
+    const argParams = params.filter((p) => p.name !== 'asof');
+    // 4. Argument count.
+    if (argParams.length > lexical_js_1.LIMITS.args)
+        (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.LIMITS.args} arguments`, 'uri.query');
+    // 5. Against the signature: unknown arguments, then missing ones.
+    for (const p of argParams) {
+        if (!Object.prototype.hasOwnProperty.call(declared, p.name))
+            (0, errors_js_1.fail)('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(p.name)}`, at(p.name));
+    }
+    const present = new Set(argParams.map((p) => p.name));
+    for (const n of (0, json_js_1.sortedKeys)(declared)) {
+        if (!present.has(n))
+            (0, errors_js_1.fail)('E_ARG_MISSING', `argument ${JSON.stringify(n)} absent; use ${n}=* for a slice`, 'uri.query');
+    }
+    // 6. Values, left to right: percent-encoding, then the lexical form.
+    const args = {};
+    for (const p of argParams) {
+        if (p.value === '*') {
+            args[p.name] = '*';
+            continue;
+        }
+        const type = declared[p.name].type;
+        const s = decodeValue(p.value, at(p.name));
+        if (type === 'boolean') {
+            if (s !== 'true' && s !== 'false')
+                (0, errors_js_1.fail)('E_CANON_TYPE', 'boolean must be true or false', at(p.name));
+            args[p.name] = { type, value: s === 'true' };
+        }
+        else {
+            (0, lexical_js_1.checkTypedValue)(type, s, at(p.name));
+            args[p.name] = { type, value: s };
+        }
+    }
+    // 7. asof.
+    const ref = { args, fn, ns };
+    const asofParam = params.find((p) => p.name === 'asof');
+    if (asofParam) {
+        const s = decodeValue(asofParam.value, at('asof'));
+        (0, lexical_js_1.checkInstant)(s, at('asof'));
+        ref.asof = s;
+    }
+    return ref;
+}
+/** Write the unique cell URI of a cell reference (SPEC 5.2). Throws DatumeshError if invalid. */
+function formatUri(ref) {
+    const v = (0, json_js_1.toJson)(ref);
+    (0, validate_js_1.validate)(v, 'ref');
+    const o = v;
+    const args = o.args;
+    const parts = [];
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        const a = args[k];
+        if (a === '*')
+            parts.push(`${k}=*`);
+        else if ((0, json_js_1.isObject)(a) && typeof a.value === 'boolean')
+            parts.push(`${k}=${a.value ? 'true' : 'false'}`);
+        else
+            parts.push(`${k}=${encodeValue(a.value)}`);
+    }
+    if (typeof o.asof === 'string')
+        parts.push(`asof=${encodeValue(o.asof)}`);
+    return `${SCHEME}${o.ns}/${o.fn}${parts.length ? `?${parts.join('&')}` : ''}`;
+}
+/** The HTTPS URL of a cell URI on mesh host `mesh` (SPEC 5.3). */
+function httpsUrl(uri, mesh) {
+    if (!uri.startsWith(SCHEME))
+        (0, errors_js_1.fail)('E_PARSE_URI', 'not a cell URI', '$');
+    return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
+}

package/dist/cjs/utf8.d.ts

@@ -0,0 +1,10 @@
+/** Encode a well-formed string as UTF-8. Lone surrogates must have been rejected already. */
+export declare function utf8Encode(s: string): Uint8Array;
+/** Number of UTF-8 bytes in a well-formed string. */
+export declare function utf8Length(s: string): number;
+/**
+ * Decode strict UTF-8 (RFC 3629): no overlong forms, no surrogates, nothing above U+10FFFF,
+ * no truncated sequences. Returns null when the bytes are not UTF-8. A leading BOM is kept
+ * (as U+FEFF) so the caller can reject it.
+ */
+export declare function utf8Decode(b: Uint8Array): string | null;

package/dist/cjs/utf8.js

@@ -0,0 +1,101 @@
+"use strict";
+// Strict UTF-8 encoding and decoding, written out so results never depend on the host's
+// TextDecoder (BOM handling, replacement characters) or its ICU build.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8Encode = utf8Encode;
+exports.utf8Length = utf8Length;
+exports.utf8Decode = utf8Decode;
+/** Encode a well-formed string as UTF-8. Lone surrogates must have been rejected already. */
+function utf8Encode(s) {
+    const out = [];
+    for (let i = 0; i < s.length; i++) {
+        let c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff) {
+                c = 0x10000 + ((c - 0xd800) << 10) + (d - 0xdc00);
+                i++;
+            }
+        }
+        if (c < 0x80)
+            out.push(c);
+        else if (c < 0x800)
+            out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+        else if (c < 0x10000)
+            out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+        else
+            out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    }
+    return Uint8Array.from(out);
+}
+/** Number of UTF-8 bytes in a well-formed string. */
+function utf8Length(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff) {
+            n += 4;
+            i++;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+/**
+ * Decode strict UTF-8 (RFC 3629): no overlong forms, no surrogates, nothing above U+10FFFF,
+ * no truncated sequences. Returns null when the bytes are not UTF-8. A leading BOM is kept
+ * (as U+FEFF) so the caller can reject it.
+ */
+function utf8Decode(b) {
+    let out = '';
+    const parts = [];
+    for (let i = 0; i < b.length;) {
+        const x = b[i];
+        let cp;
+        let need;
+        let min;
+        if (x < 0x80) {
+            cp = x;
+            need = 0;
+            min = 0;
+        }
+        else if (x >= 0xc2 && x <= 0xdf) {
+            cp = x & 0x1f;
+            need = 1;
+            min = 0x80;
+        }
+        else if (x >= 0xe0 && x <= 0xef) {
+            cp = x & 0x0f;
+            need = 2;
+            min = 0x800;
+        }
+        else if (x >= 0xf0 && x <= 0xf4) {
+            cp = x & 0x07;
+            need = 3;
+            min = 0x10000;
+        }
+        else
+            return null;
+        for (let k = 1; k <= need; k++) {
+            const y = b[i + k];
+            if (y === undefined || (y & 0xc0) !== 0x80)
+                return null;
+            cp = (cp << 6) | (y & 0x3f);
+        }
+        if (cp < min || cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff))
+            return null;
+        out += String.fromCodePoint(cp);
+        if (out.length > 8192) {
+            parts.push(out);
+            out = '';
+        }
+        i += need + 1;
+    }
+    parts.push(out);
+    return parts.join('');
+}

package/dist/cjs/validate.d.ts

@@ -0,0 +1,17 @@
+import { type JsonObject, type JsonValue } from './json.js';
+export type Kind = 'scalar' | 'cell' | 'ref' | 'function' | 'receipt' | 'jcs';
+export declare const KINDS: readonly Kind[];
+export declare function structSignature(v: JsonValue, path: string): void;
+export declare function canonSignature(sig: JsonObject, path: string): void;
+/** Validate `v` as `kind` (steps 2-3; for receipts also step 4). Throws DatumeshError. */
+export declare function validate(v: JsonValue, kind: Kind, path?: string): void;
+/** Receipt step 2 only: true when the receipt has the right members and JSON types. */
+export declare function receiptStructure(v: JsonValue): void;
+/** Receipt steps 3 and 4, after receiptStructure has passed. */
+export declare function receiptCanonicalAndConsistent(v: JsonValue): void;
+/**
+ * Infer the kind of an object from its members when the caller gives none: a receipt has
+ * `sig`, `proto` or `computed_by`; a descriptor `signature` or `code`; a cell `fn_hash`; a cell
+ * reference `fn`, `ns` or `args`; a typed scalar `type` or `value`. Anything else is E_SCHEMA.
+ */
+export declare function inferKind(v: JsonValue): Exclude<Kind, 'jcs'>;