@pubid/pubid 0.1.33 → 0.1.35

package/dist/pubid-urn/decoder.js

@@ -0,0 +1,165 @@
+/**
+ * Reads the body of a pubid-scheme URN back into an identifier hash —
+ * the TS mirror of Pubid::PubidUrn::Decoder (lib/pubid/pubid_urn/decoder.rb).
+ * The inverse of Encoder; strict about structure. Canonical form (atom
+ * order, escapes, trailing "~") is checked by PubidUrn.parse, which
+ * re-encodes the result and compares.
+ */
+import { decode as escape, exactMatch } from "./escape.js";
+import { UrnParseError } from "./errors.js";
+import { put } from "./paths.js";
+import { Decoder as _Decoder } from "./decoder.js";
+import { flavorSchema, splitToken, splitTop, structural } from "./index.js";
+const FACET = /^(\d+)\.([a-z0-9]+)-(.*)/;
+const INTEGER = /^-?[0-9]+$/;
+const NULL = "~";
+export class Decoder {
+    body;
+    constructor(body) {
+        this.body = body;
+    }
+    /** The identifier hash (`_type` and `base` included). */
+    toIdentifierHash() {
+        const sep = this.body.indexOf(":");
+        const flavor = sep === -1 ? undefined : this.body.slice(0, sep);
+        const rest = sep === -1 ? undefined : this.body.slice(sep + 1);
+        if (rest === undefined || rest === "")
+            this.fail("no type segment");
+        return this.decodeIdentifier(rest, flavor);
+    }
+    decodeIdentifier(body, flavor) {
+        const tokens = splitTop(body, ":");
+        const nodes = [];
+        const schemas = [];
+        let i = 0;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            if (token === "f") {
+                this.decodeFacets(tokens.slice(i + 1), nodes, schemas);
+                break;
+            }
+            const schema = this.nodeSchema(token, flavor);
+            const node = { _type: schema.type };
+            i = this.decodeCore(tokens, i + 1, node, schema);
+            i = this.decodeAtoms(tokens, i, node, schema);
+            nodes.push(node);
+            schemas.push(schema);
+        }
+        if (nodes.length === 0)
+            this.fail("no identifier");
+        for (let k = 1; k < nodes.length; k++) {
+            nodes[k]["base"] = nodes[k - 1];
+        }
+        return nodes[nodes.length - 1];
+    }
+    nodeSchema(token, flavor) {
+        if (token === "type") {
+            this.fail("type-metadata URN names a type, not a document");
+        }
+        let schema;
+        if (structural(token)) {
+            const [owner, name] = splitToken(token, flavor);
+            schema = flavorSchema(owner)?.forToken(name);
+        }
+        if (schema === undefined) {
+            this.fail(`unknown type or segment ${JSON.stringify(token)}`);
+        }
+        return schema;
+    }
+    decodeCore(tokens, index, node, schema) {
+        let i = index;
+        for (let ci = 0; ci < schema.core.length; ci++) {
+            if (i >= tokens.length)
+                break;
+            const token = tokens[i];
+            if (structural(token))
+                break;
+            if (token !== NULL) {
+                put(node, schema.core[ci], this.coreValue(token, schema.coreKinds[ci]));
+            }
+            i += 1;
+        }
+        return i;
+    }
+    coreValue(token, kind) {
+        return kind === "int" ? this.integer(token) : escape(token);
+    }
+    decodeAtoms(tokens, index, node, schema) {
+        let last = -1;
+        let i = index;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            const position = schema.atomPosition(token);
+            if (position === undefined)
+                break;
+            if (position <= last) {
+                this.fail(`atom ${JSON.stringify(token)} is out of order or repeated`);
+            }
+            last = position;
+            const atom = schema.atoms[position];
+            const dash = token.indexOf("-");
+            const raw = dash === -1 ? "" : token.slice(dash + 1);
+            put(node, atom.parts, this.atomValue(raw, atom));
+            i += 1;
+        }
+        return i;
+    }
+    atomValue(raw, atom) {
+        if (atom.kind === "int")
+            return this.integer(raw);
+        if (atom.kind === "id")
+            return this.nested(raw);
+        if (atom.kind === "ids")
+            return splitTop(raw, ",").map((item) => this.nested(item));
+        return this.slotValue(raw, atom);
+    }
+    /** The value of a :string, :bool or list atom, or of a facet. */
+    slotValue(raw, slot) {
+        if (!slot.list)
+            return this.scalar(raw, slot);
+        return splitTop(raw, ",", true).map((item) => item === NULL ? null : this.scalar(item, slot));
+    }
+    scalar(raw, slot) {
+        return slot.element === "bool" ? this.boolean(raw) : escape(raw);
+    }
+    boolean(raw) {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        this.fail(`${JSON.stringify(raw)} is not a boolean`);
+    }
+    integer(raw) {
+        const m = INTEGER.exec(raw);
+        if (m === null || m[0].length !== raw.length) {
+            this.fail(`${JSON.stringify(raw)} is not an integer`);
+        }
+        return Number(raw);
+    }
+    nested(raw) {
+        if (!raw.startsWith("(") || !raw.endsWith(")")) {
+            this.fail(`nested identifier ${JSON.stringify(raw)} needs brackets`);
+        }
+        return new _Decoder(raw.slice(1, -1)).toIdentifierHash();
+    }
+    decodeFacets(tokens, nodes, schemas) {
+        if (tokens.length === 0)
+            this.fail("empty facet group");
+        for (const token of tokens) {
+            const match = exactMatch(FACET, token);
+            if (match === null)
+                this.fail(`bad facet ${JSON.stringify(token)}`);
+            const index = Number(match[1]);
+            const schema = schemas[index];
+            if (schema === undefined)
+                this.fail(`facet ${JSON.stringify(token)} has no node`);
+            const facet = schema.facet(match[2]);
+            if (facet === undefined)
+                this.fail(`bad facet ${JSON.stringify(token)}`);
+            put(nodes[index], facet.parts, this.slotValue(match[3], facet));
+        }
+    }
+    fail(message) {
+        throw new UrnParseError(`pubid URN ${JSON.stringify(this.body)}: ${message}`);
+    }
+}

package/dist/pubid-urn/encoder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Writes the pubid-scheme URN of an identifier hash — the TS mirror of
+ * Pubid::PubidUrn::Encoder (lib/pubid/pubid_urn/encoder.rb).
+ *
+ *   urn:pubid:<flavor>:<node>[:<node>…][:f:<facet>…]
+ *   <node> = <type>[:<core>…][:<prefix>-<value>…]
+ *
+ * The nodes go root first, along `base`: "ISO 9001:2015/Amd 1:2016" is
+ * "is:9001:year-2015:amd:1:year-2016", so every supplement of a document
+ * shares its slug prefix. A core value is positional; an absent one in
+ * the middle is "~", and absent ones at the end are dropped. An optional
+ * value is a prefixed atom, so it leaves no segment when it is absent.
+ */
+export declare class Encoder {
+    private readonly hash;
+    constructor(hash: Record<string, unknown>);
+    /** The body after "urn:pubid:". */
+    body(): string;
+    private encodeIdentifier;
+    /** The nodes from the root document to `hash` itself. */
+    private chain;
+    private token;
+    private coreSegments;
+    private atomSegments;
+    private atomValue;
+    /** The value of a :string, :bool or list atom, or of a facet. */
+    private slotValue;
+    private scalar;
+    private facetSegments;
+}

package/dist/pubid-urn/encoder.js

@@ -0,0 +1,197 @@
+/**
+ * Writes the pubid-scheme URN of an identifier hash — the TS mirror of
+ * Pubid::PubidUrn::Encoder (lib/pubid/pubid_urn/encoder.rb).
+ *
+ *   urn:pubid:<flavor>:<node>[:<node>…][:f:<facet>…]
+ *   <node> = <type>[:<core>…][:<prefix>-<value>…]
+ *
+ * The nodes go root first, along `base`: "ISO 9001:2015/Amd 1:2016" is
+ * "is:9001:year-2015:amd:1:year-2016", so every supplement of a document
+ * shares its slug prefix. A core value is positional; an absent one in
+ * the middle is "~", and absent ones at the end are dropped. An optional
+ * value is a prefixed atom, so it leaves no segment when it is absent.
+ */
+import { typeSchemaOrThrow, structural } from "./index.js";
+import { InvalidInputError } from "./errors.js";
+import { encode as escapeEncode, force } from "./escape.js";
+import { blank, deepDup, isNil, take } from "./paths.js";
+import { Encoder as _Encoder } from "./encoder.js";
+/** ruby's PubidUrn::NULL: the absent-slot marker. */
+const NULL = "~";
+export class Encoder {
+    hash;
+    constructor(hash) {
+        this.hash = hash;
+    }
+    /** The body after "urn:pubid:". */
+    body() {
+        const flavor = flavorSegmentOf(this.hash["_type"]);
+        return `${flavor}:${this.encodeIdentifier(this.hash, flavor)}`;
+    }
+    encodeIdentifier(hash, flavor) {
+        const segments = [];
+        const facets = [];
+        this.chain(hash).forEach((node, index) => {
+            const schema = typeSchemaOrThrow(node["_type"]);
+            const copy = deepDup(node);
+            delete copy["_type"];
+            segments.push(this.token(schema, flavor));
+            segments.push(...this.coreSegments(copy, schema));
+            segments.push(...this.atomSegments(copy, schema));
+            facets.push(...this.facetSegments(copy, schema, index));
+            checkPlaced(copy, schema);
+        });
+        if (facets.length > 0)
+            segments.push("f", ...facets);
+        return segments.join(":");
+    }
+    /** The nodes from the root document to `hash` itself. */
+    chain(hash) {
+        const nodes = [];
+        let node = hash;
+        while (node !== undefined && node !== null) {
+            if (typeof node !== "object" ||
+                Array.isArray(node) ||
+                typeof node["_type"] !== "string") {
+                throw new InvalidInputError(`a pubid URN base must be an identifier hash, got ${inspect(node)}`);
+            }
+            const copy = { ...node };
+            delete copy["base"];
+            nodes.unshift(copy);
+            node = node["base"];
+        }
+        return nodes;
+    }
+    token(schema, flavor) {
+        return schema.flavor === flavor ? schema.token : `${schema.flavor}.${schema.token}`;
+    }
+    coreSegments(node, schema) {
+        const values = schema.core.map((parts) => take(node, parts));
+        while (values.length > 0 && isNil(values[values.length - 1]))
+            values.pop();
+        return values.map((value, i) => {
+            if (isNil(value))
+                return NULL;
+            if (schema.coreKinds[i] === "int")
+                return coreInteger(value, schema, i);
+            return coreValue(value, schema);
+        });
+    }
+    atomSegments(node, schema) {
+        const segments = [];
+        for (const atom of schema.atoms) {
+            const value = take(node, atom.parts);
+            if (isNil(value))
+                continue;
+            segments.push(`${atom.prefix}-${this.atomValue(value, atom, schema)}`);
+        }
+        return segments;
+    }
+    atomValue(value, atom, schema) {
+        if (atom.kind === "int")
+            return String(typed(value, "number", atom, schema));
+        if (atom.kind === "id") {
+            return nested(typed(value, "hash", atom, schema));
+        }
+        if (atom.kind === "ids") {
+            return typed(value, "array", atom, schema)
+                .map((hash) => nested(hash))
+                .join(",");
+        }
+        return this.slotValue(value, atom, schema);
+    }
+    /** The value of a :string, :bool or list atom, or of a facet. */
+    slotValue(value, slot, schema) {
+        if (!slot.list)
+            return this.scalar(value, slot, schema);
+        return typed(value, "array", slot, schema)
+            .map((item) => (isNil(item) ? NULL : this.scalar(item, slot, schema)))
+            .join(",");
+    }
+    scalar(value, slot, schema) {
+        if (slot.element === "bool") {
+            if (value !== true && value !== false) {
+                throw typeError(value, slot, schema);
+            }
+            return String(value);
+        }
+        return escapeEncode(typed(value, "string", slot, schema));
+    }
+    facetSegments(node, schema, index) {
+        const segments = [];
+        for (const facet of schema.facets) {
+            const value = take(node, facet.parts);
+            if (isNil(value))
+                continue;
+            segments.push(`${index}.${facet.name}-${this.slotValue(value, facet, schema)}`);
+        }
+        return segments;
+    }
+}
+function nested(hash) {
+    return `(${new _Encoder(hash).body()})`;
+}
+/** A decimal never has the shape of structure, so it needs no escape. */
+function coreInteger(value, schema, index) {
+    if (typeof value === "number" && Number.isInteger(value))
+        return String(value);
+    throw new InvalidInputError(`${schema.type} ${schema.core[index]?.join(".")}: ${inspect(value)} is not int`);
+}
+/** A core value that has the shape of structure gets its first character
+ *  escaped. */
+function coreValue(value, schema) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new InvalidInputError(`core value of ${schema.type} must be a non-empty String, got ${inspect(value)}`);
+    }
+    const encoded = escapeEncode(value);
+    if (!structural(encoded))
+        return encoded;
+    const chars = Array.from(value);
+    return force(chars[0]) + escapeEncode(chars.slice(1).join(""));
+}
+function typed(value, expected, slot, schema) {
+    let ok;
+    switch (expected) {
+        case "number":
+            ok = typeof value === "number" && Number.isInteger(value);
+            break;
+        case "string":
+            ok = typeof value === "string";
+            break;
+        case "hash":
+            ok = value !== null && typeof value === "object" && !Array.isArray(value);
+            break;
+        case "array":
+            ok = Array.isArray(value);
+            break;
+    }
+    if (ok)
+        return value;
+    throw typeError(value, slot, schema);
+}
+function typeError(value, slot, schema) {
+    return new InvalidInputError(`${schema.type} ${slot.path}: ${inspect(value)} is not ${slot.kind}`);
+}
+function checkPlaced(node, schema) {
+    const left = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (!blank(value))
+            left[key] = value;
+    }
+    if (Object.keys(left).length > 0) {
+        throw new InvalidInputError(`the pubid URN schema of ${schema.type} does not place ${inspect(left)}`);
+    }
+}
+function inspect(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function flavorSegmentOf(type) {
+    return typeof type === "string" ? type.split(":")[1] : undefined;
+}

package/dist/pubid-urn/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The error classes of the pubid-scheme URN codec — the TS mirror of
+ * Pubid::Errors::UrnParseError and Pubid::Errors::InvalidInputError
+ * (lib/pubid/errors.rb). A decode failure is ALWAYS one of these two,
+ * never a parser-internal error (pubid#670 item 3).
+ */
+/** A malformed, unknown or non-canonical pubid-scheme URN (ruby:
+ *  UrnParseError < StandardError). */
+export declare class UrnParseError extends Error {
+    constructor(message: string);
+}
+/** A non-String or over-long input (ruby: InvalidInputError < ArgumentError). */
+export declare class InvalidInputError extends Error {
+    constructor(message: string);
+}

package/dist/pubid-urn/errors.js

@@ -0,0 +1,21 @@
+/**
+ * The error classes of the pubid-scheme URN codec — the TS mirror of
+ * Pubid::Errors::UrnParseError and Pubid::Errors::InvalidInputError
+ * (lib/pubid/errors.rb). A decode failure is ALWAYS one of these two,
+ * never a parser-internal error (pubid#670 item 3).
+ */
+/** A malformed, unknown or non-canonical pubid-scheme URN (ruby:
+ *  UrnParseError < StandardError). */
+export class UrnParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UrnParseError";
+    }
+}
+/** A non-String or over-long input (ruby: InvalidInputError < ArgumentError). */
+export class InvalidInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidInputError";
+    }
+}

package/dist/pubid-urn/escape.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The value escape of the pubid-scheme URN — the TS mirror of
+ * Pubid::PubidUrn::Escape (lib/pubid/pubid_urn/escape.rb).
+ *
+ * The URN is also an HTTP path slug (relaton/relaton#441), so it cannot
+ * use "%": servers and proxies decode "%2F" before they route, or they
+ * refuse it. "~XX" (uppercase hex of one UTF-8 byte) has no meaning in a
+ * path, and "~" is an RFC 3986 unreserved character. Every byte outside
+ * SAFE is escaped, so ":" "," "(" ")" "~" never occur raw in a value and
+ * stay free for the structure of the URN.
+ */
+export declare function encode(value: string): string;
+/** Escape every byte of `char`. The codec uses it on the first character
+ *  of a core value that would otherwise read as structure ("amd" -> "~61md"). */
+export declare function force(char: string): string;
+export declare function decode(token: string): string;
+/** A pattern whose ruby twin ends in \z: the match must cover the whole
+ *  string (JS `$` alone would also match before one trailing "\n"). */
+export declare function exactMatch(re: RegExp, token: string): RegExpExecArray | null;

package/dist/pubid-urn/escape.js

@@ -0,0 +1,65 @@
+/**
+ * The value escape of the pubid-scheme URN — the TS mirror of
+ * Pubid::PubidUrn::Escape (lib/pubid/pubid_urn/escape.rb).
+ *
+ * The URN is also an HTTP path slug (relaton/relaton#441), so it cannot
+ * use "%": servers and proxies decode "%2F" before they route, or they
+ * refuse it. "~XX" (uppercase hex of one UTF-8 byte) has no meaning in a
+ * path, and "~" is an RFC 3986 unreserved character. Every byte outside
+ * SAFE is escaped, so ":" "," "(" ")" "~" never occur raw in a value and
+ * stay free for the structure of the URN.
+ */
+import { UrnParseError } from "./errors.js";
+const SAFE = /^[A-Za-z0-9._-]$/;
+const RAW_TOKEN = /^(?:[A-Za-z0-9._-]|~[0-9A-F]{2})*$/;
+const ESCAPE = /~([0-9A-F]{2})/g;
+export function encode(value) {
+    let out = "";
+    // ruby each_char walks code points, not UTF-16 units.
+    for (const char of String(value)) {
+        out += SAFE.test(char) ? char : force(char);
+    }
+    return out;
+}
+/** Escape every byte of `char`. The codec uses it on the first character
+ *  of a core value that would otherwise read as structure ("amd" -> "~61md"). */
+export function force(char) {
+    const bytes = new TextEncoder().encode(char);
+    let out = "";
+    for (const byte of bytes) {
+        out += `~${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return out;
+}
+export function decode(token) {
+    const raw = RAW_TOKEN.exec(token);
+    if (raw === null || raw[0].length !== token.length) {
+        throw new UrnParseError(`bad character or escape in pubid URN value ${JSON.stringify(token)}`);
+    }
+    const bytes = [];
+    let i = 0;
+    while (i < token.length) {
+        if (token[i] === "~") {
+            bytes.push(parseInt(token.slice(i + 1, i + 3), 16));
+            i += 3;
+        }
+        else {
+            bytes.push(token.charCodeAt(i));
+            i += 1;
+        }
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes));
+    }
+    catch {
+        throw new UrnParseError(`escape in pubid URN value ${JSON.stringify(token)} is not UTF-8`);
+    }
+    return decoded;
+}
+/** A pattern whose ruby twin ends in \z: the match must cover the whole
+ *  string (JS `$` alone would also match before one trailing "\n"). */
+export function exactMatch(re, token) {
+    const m = re.exec(token);
+    return m !== null && m[0].length === token.length ? m : null;
+}

package/dist/pubid-urn/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The pubid-scheme URN (pubid#656) — the TS mirror of
+ * Pubid::PubidUrn (lib/pubid/pubid_urn.rb). Pubid's own URN namespace,
+ * which carries the full typed model and always round-trips —
+ * `parsePubidUrn(generate(id.toHash())).toHash == id.toHash`.
+ *
+ * It is a different thing from the official URN (`toUrn()`, e.g.
+ * "urn:iso:std:…"), which follows the registered grammar of the
+ * organization and may be lossy. relaton uses the pubid-scheme URN as
+ * its HTTP path slug (relaton/relaton#441), so the form is also
+ * path-safe: no "/", "%", "?", "#" and no empty segment.
+ *
+ *   urn:pubid:iso:is:9001:year-2015:amd:1:year-2016
+ *
+ * The shape of each identifier type is declared in its flavor's schema
+ * (src/pubid-urn/schemas/<flavor>.ts), through {@linkcode define}. A
+ * flavor with no schema cannot emit one yet.
+ */
+import { FlavorSchema, type TypeSchema } from "./schema.js";
+import { exactMatch } from "./escape.js";
+import type { BaseIdentifier } from "../model/identifier.js";
+import { toSlug, fromSlug } from "./slug.js";
+export { toSlug, fromSlug };
+export { Atom, Facet, FlavorSchema, TypeSchema } from "./schema.js";
+export type { AtomKind, FacetKind, CoreKind, CoreSpec, AtomSpec, FacetSpec, TypeDeclaration } from "./schema.js";
+export { Encoder } from "./encoder.js";
+export { Decoder } from "./decoder.js";
+export { UrnParseError, InvalidInputError } from "./errors.js";
+export { encode, force, decode } from "./escape.js";
+export { take, put, blank } from "./paths.js";
+export declare const PREFIX = "urn:pubid:";
+/** An absent core value in the middle of the core, or an absent element
+ *  of a list. Distinct from an escape, which always has two hex digits. */
+export declare const NULL = "~";
+/** Pubid::MAX_INPUT_LENGTH (1000) — the printed-identifier guard. */
+export declare const MAX_INPUT_LENGTH = 1000;
+export declare const MAX_LENGTH: number;
+/** Declare the schema of a flavor. `flavor` is the flavor segment of its
+ *  `_type` ("iso", "cencenelec", "3gpp"). The callback plays ruby's
+ *  instance_eval: it receives the schema and declares atoms/facets/types. */
+export declare function define(flavor: string, body: (schema: FlavorSchema) => void): FlavorSchema;
+/** The pubid-scheme URN of an identifier hash (ruby generate(identifier):
+ *  the hash is Identifier#to_hash's output). */
+export declare function generate(hash: Record<string, unknown>): string;
+/** Parse a pubid-scheme URN back into an identifier, through the
+ *  canonical gate: the decoded identifier must re-encode to exactly the
+ *  input, so one identifier has exactly one URN. */
+export declare function parse(urn: string): BaseIdentifier;
+/** True for "urn:pubid:…" (the NID is case-insensitive, RFC 8141). */
+export declare function isPubidUrn(urn: string): boolean;
+/** "iso" in "pubid:iso:technical-report". */
+export declare function flavorSegment(type: unknown): string | undefined;
+export declare function flavorSchema(flavor: string): FlavorSchema | undefined;
+/** @raise InvalidInputError when no schema places `type`. */
+export declare function typeSchemaOrThrow(type: unknown): TypeSchema;
+/** Does `token` (a raw, still escaped segment) read as structure? */
+export declare function structural(token: string): boolean;
+/** A type token is "<token>" of the URN's own flavor, or
+ *  "<flavor>.<token>" for a node of another flavor. */
+export declare function splitToken(token: string, flavor: string): [string, string];
+/** Split `body` at `separator` outside brackets. `allowEmpty` is true for
+ *  the items of a list, where an empty item is an empty String; a ":"
+ *  segment is never empty. */
+export declare function splitTop(body: string, separator: string, allowEmpty?: boolean): string[];
+export { exactMatch };