@datumesh/verify 0.0.0-stage → 0.2.0

package/dist/esm/uri.js

@@ -0,0 +1,204 @@
+// Cell URIs (SPEC.md section 5).
+import { fail } from './errors.js';
+import { isObject, sortedKeys, toJson } from './json.js';
+import { LIMITS, checkArgName, checkInstant, checkName, checkNamespace, checkTypedValue, isTypeName } from './lexical.js';
+import { utf8Decode, utf8Encode } from './utf8.js';
+import { validate } from './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))
+                fail('E_CANON_PERCENT', 'percent-encoding must be % and two uppercase hex digits', path);
+            const b = parseInt(h, 16);
+            if (isLiteral(String.fromCharCode(b)))
+                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);
+            fail('E_CANON_PERCENT', `${JSON.stringify(String.fromCodePoint(cp))} must be percent-encoded`, path);
+        }
+    }
+    const s = utf8Decode(Uint8Array.from(bytes));
+    if (s === null)
+        fail('E_CANON_PERCENT', 'percent-encoded bytes are not UTF-8', path);
+    return s;
+}
+function encodeValue(s) {
+    let out = '';
+    for (const b of utf8Encode(s)) {
+        const c = String.fromCharCode(b);
+        out += isLiteral(c) ? c : `%${b.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return out;
+}
+/**
+ * SPEC 5.4: the signature is taken as given (it comes from a descriptor already checked under
+ * section 7); only the declared argument names and types are used. Something that is not a
+ * signature at all is a programmer error.
+ */
+function readSignature(signature) {
+    let sig;
+    try {
+        sig = toJson(signature);
+    }
+    catch {
+        throw new TypeError('parseUri needs the function signature (descriptor.signature) as JSON');
+    }
+    if (!isObject(sig) || !isObject(sig.args))
+        throw new TypeError('parseUri needs the function signature (descriptor.signature): an object with args');
+    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.
+ */
+export 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('#'))
+        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 === '')
+        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('@'))
+        fail('E_PARSE_URI', 'a cell URI has no userinfo', '$');
+    if (authority.includes(':'))
+        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)
+            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)
+        fail('E_CANON_NAME', 'missing namespace', 'uri.path');
+    const ns = path.slice(0, slash);
+    const fn = path.slice(slash + 1);
+    checkNamespace(ns, 'uri.path');
+    checkName(fn, 'uri.path');
+    if (path.length > LIMITS.function_name)
+        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)
+                fail('E_CANON_ARG_ORDER', 'asof appears once, as the last parameter', at(p.name));
+            if (i !== params.length - 1)
+                fail('E_CANON_ARG_DUPLICATE', 'asof repeated', at(p.name));
+            return;
+        }
+        checkArgName(p.name, at(p.name));
+        if (prev !== null && p.name === prev)
+            fail('E_CANON_ARG_DUPLICATE', `argument ${JSON.stringify(p.name)} repeated`, at(p.name));
+        if (prev !== null && p.name < prev)
+            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 > LIMITS.args)
+        fail('E_CANON_LIMIT', `more than ${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))
+            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 sortedKeys(declared)) {
+        if (!present.has(n))
+            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 decl = declared[p.name];
+        const type = (isObject(decl) ? decl.type : undefined);
+        const s = decodeValue(p.value, at(p.name));
+        // The signature is not validated (5.4), but a value is read by its declared type: a
+        // declaration without a string type is E_SCHEMA, an unknown type name E_CANON_TYPE.
+        if (typeof type !== 'string')
+            fail('E_SCHEMA', `the signature declares ${p.name} without a string type`, `signature.args.${p.name}`);
+        if (!isTypeName(type))
+            fail('E_CANON_TYPE', `unknown type ${JSON.stringify(type)} in the signature`, `signature.args.${p.name}.type`);
+        if (type === 'boolean') {
+            if (s !== 'true' && s !== 'false')
+                fail('E_CANON_TYPE', 'boolean must be true or false', at(p.name));
+            args[p.name] = { type, value: s === 'true' };
+        }
+        else {
+            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'));
+        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. */
+export function formatUri(ref) {
+    const v = toJson(ref);
+    validate(v, 'ref');
+    const o = v;
+    const args = o.args;
+    const parts = [];
+    for (const k of sortedKeys(args)) {
+        const a = args[k];
+        if (a === '*')
+            parts.push(`${k}=*`);
+        else if (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). */
+export function httpsUrl(uri, mesh) {
+    if (!uri.startsWith(SCHEME))
+        fail('E_PARSE_URI', 'not a cell URI', '$');
+    return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
+}

package/dist/esm/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/esm/utf8.js

@@ -0,0 +1,96 @@
+// 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.
+/** Encode a well-formed string as UTF-8. Lone surrogates must have been rejected already. */
+export 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. */
+export 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.
+ */
+export 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/esm/validate.d.ts

@@ -0,0 +1,25 @@
+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;
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+export declare function returnType(sig: JsonObject): string;
+/** 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;
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md 3). Order: the cell (structure, canonical
+ * form), fn_hash against the descriptor (E_FN_HASH_MISMATCH), the descriptor (structure,
+ * canonical form), then substitution.
+ */
+export declare function cellUnit(desc: JsonValue, cell: JsonValue, fnHash: (d: JsonValue) => string): string | null;
+/** 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'>;