@pubid/pubid 0.1.3 → 0.1.4

package/dist/model/identifier.js

@@ -0,0 +1,270 @@
+/**
+ * BaseIdentifier — the TS mirror of Pubid::Identifier's declaration and
+ * canonical-serialization core. Semantics pinned in
+ * TODO.unified/01-study-pubid-core.md §2-3:
+ *
+ * toHash: `_type` first, mapped attributes, then canonicalization
+ * (drop empty / default-valued attributes, recursively), then
+ * degenerate-component flattening (`date: {year: "2024"}` → `year:
+ * "2024"`, `edition: {number: "2"}` → `edition: "2"`), then the class's
+ * compactHash hook.
+ *
+ * fromHash: dispatch on `_type` through the registered type map,
+ * re-inflate flat scalars into component hashes (unless the flavor has a
+ * converter for the key or declares the flat name as its own attribute),
+ * construct with type coercion.
+ *
+ * Flavors NEVER hand-roll a hash here — they declare attributes and
+ * mappings; the only imperative wire code is a converter pair.
+ */
+import { FLAT_SCALAR_COMPONENTS, FLAT_SCALAR_FIELDS, BASE_ATTRIBUTES } from "./attribute.js";
+import { Component } from "./component.js";
+import { BaseUrnGenerator } from "./urn-generator.js";
+const TYPE_REGISTRY = new Map();
+/** Register a concrete identifier class under its polymorphic _type (the *_TYPE_MAP role). */
+export function registerType(klass) {
+    TYPE_REGISTRY.set(klass.polymorphicName, klass);
+}
+function resolveType(type) {
+    return TYPE_REGISTRY.get(type);
+}
+function isScalarType(t) {
+    return typeof t === "string";
+}
+function coerce(value, spec) {
+    if (value === undefined || value === null)
+        return value;
+    if (spec.collection) {
+        const list = Array.isArray(value) ? value : [value];
+        return list.map((v) => coerceOne(v, spec));
+    }
+    return coerceOne(value, spec);
+}
+function coerceOne(value, spec) {
+    if (isScalarType(spec.type)) {
+        if (spec.type === "integer")
+            return Number(value);
+        if (spec.type === "boolean")
+            return Boolean(value);
+        return typeof value === "object" && value !== null ? value : String(value);
+    }
+    if (value instanceof spec.type)
+        return value;
+    // A cross-flavor identifier instance (e.g. an IEC id nested in an IEEE
+    // adoption) is complete already; coercing through the declared flavor's
+    // fromHash would rebuild it as the wrong (abstract) class.
+    if (value instanceof BaseIdentifier)
+        return value;
+    if (typeof value === "object" && value !== null) {
+        // Identifier-typed attributes (oiml supplement `base`) dispatch
+        // polymorphically through the registered type map.
+        if (typeof spec.type === "function" && spec.type.prototype instanceof BaseIdentifier) {
+            const idCtor = spec.type;
+            const v = value;
+            return "_type" in v ? idCtor.fromHash(v) : idCtor.fromHash({ ...v, _type: idCtor.polymorphicName });
+        }
+        return new spec.type(value);
+    }
+    return value;
+}
+/** Utils.empty?: nil is NOT empty here (nil is dropped earlier); "" and [] are. */
+function isEmptyValue(value) {
+    if (value === "")
+        return true;
+    if (Array.isArray(value) && value.length === 0)
+        return true;
+    return false;
+}
+function resolveDefault(spec) {
+    return typeof spec.default === "function" ? spec.default() : spec.default;
+}
+export class BaseIdentifier {
+    /** The root table; subclasses compose via extendAttributes(BaseIdentifier, …). */
+    static attributes = BASE_ATTRIBUTES;
+    constructor(attrs = {}) {
+        for (const [name, spec] of Object.entries(this.classAttributes())) {
+            const value = attrs[name];
+            if (value !== undefined) {
+                this[name] = coerce(value, spec);
+            }
+            else if (spec.initializeEmpty && spec.collection) {
+                this[name] = [];
+            }
+        }
+    }
+    /** The human form (Ruby render(format: :human) → the flavor renderer). */
+    toHuman() {
+        return this.render();
+    }
+    /** Ruby to_urn: the flavor's UrnGenerator, else the base template. */
+    toUrn() {
+        const Generator = this.constructor.urnGenerator ?? BaseUrnGenerator;
+        return new Generator(this).generate();
+    }
+    fromHash(hash) {
+        return this.constructor.fromHash(hash);
+    }
+    classAttributes() {
+        return this.constructor.attributes;
+    }
+    /** Wire key for an attribute: custom mapping or the attribute name. */
+    wireKeyFor(name) {
+        const mappings = this.constructor.mappings;
+        const found = mappings?.find((m) => m.to === name);
+        return found ?? { wire: name };
+    }
+    attrValue(name) {
+        return this[name];
+    }
+    /** Serialize one attribute's value (component → toWire, nested identifier → toHash, scalars as-is). */
+    serializeValue(value) {
+        // A nested identifier serializes through the NESTED mapping list: a
+        // class whose top-level wire deletes derived keys (the Ruby reference
+        // drops JointDevelopment's derived publisher/copublisher only on the
+        // public to_hash — lutaml's nested transform reads the accessors and
+        // keeps them) must keep them here.
+        if (value instanceof BaseIdentifier)
+            return value.toHashNested();
+        if (value instanceof Component)
+            return value.toWire();
+        if (Array.isArray(value))
+            return value.map((v) => this.serializeValue(v));
+        return value;
+    }
+    /** Nested serialization: same as toHash but with the unfiltered mappings. */
+    toHashNested() {
+        const ctor = this.constructor;
+        if (ctor.mappingsNested === undefined)
+            return this.toHash();
+        return this.toHashWith(ctor.mappingsNested);
+    }
+    toHash() {
+        return this.toHashWith(this.constructor.mappings);
+    }
+    toHashWith(mappings) {
+        const hash = { _type: this.constructor.polymorphicName };
+        // A flavor's explicit mapping list is a WHITELIST (lutaml key_value):
+        // unmapped attributes never serialize — that is how un keeps its
+        // runtime `date` out of the hash while the URN still reads it.
+        const emitted = mappings
+            ? mappings.map((m) => [m.to, m.wire, m.toWire])
+            : Object.keys(this.classAttributes()).map((name) => [name, name, undefined]);
+        for (const [name, wire, toWire] of emitted) {
+            const value = this.attrValue(name);
+            // nil never serializes; empty and default-valued attributes are
+            // dropped by canonicalization (TODO.unified/01 §2.2).
+            if (value === undefined || value === null)
+                continue;
+            const spec = this.classAttributes()[name];
+            if (spec && isEmptyValue(value))
+                continue;
+            if (spec?.default !== undefined && deepEqual(value, resolveDefault(spec)))
+                continue;
+            const serialized = toWire ? toWire(this) : this.serializeValue(value);
+            if (serialized === undefined || serialized === null)
+                continue;
+            hash[wire] = serialized;
+        }
+        this.flattenScalars(hash);
+        this.constructor.compactHash?.(this, hash);
+        return hash;
+    }
+    /**
+     * Degenerate single-field components collapse to their scalar
+     * (identifier.rb flatten_scalar_components): `date` RENAMES to `year`,
+     * `edition` keeps its name; guards: never overwrite an emitted wire
+     * key, never rename onto a declared attribute name.
+     */
+    flattenScalars(hash) {
+        const table = { ...FLAT_SCALAR_COMPONENTS, ...this.constructor.flatScalarComponents };
+        for (const [attrName, flatKey] of Object.entries(table)) {
+            const key = attrName in hash ? attrName : undefined;
+            if (key === undefined)
+                continue;
+            const value = hash[key];
+            const field = FLAT_SCALAR_FIELDS[attrName] ?? this.constructor.flatScalarFields?.[attrName];
+            if (field === undefined)
+                continue;
+            const model = this.attrValue(attrName);
+            if (Array.isArray(value) && Array.isArray(model)) {
+                if (model.every((c) => c instanceof Component) && model.length === value.length) {
+                    const scalars = model.map((c) => c.degenerateScalar(field));
+                    if (scalars.every((s) => s !== undefined))
+                        hash[key] = scalars;
+                }
+                continue;
+            }
+            if (!(model instanceof Component))
+                continue;
+            const scalar = model.degenerateScalar(field);
+            if (scalar === undefined)
+                continue;
+            if (flatKey !== key) {
+                if (flatKey in hash || flatKey in this.classAttributes())
+                    continue;
+                delete hash[key];
+                hash[flatKey] = scalar;
+            }
+            else {
+                hash[key] = scalar;
+            }
+        }
+    }
+    static fromHash(hash) {
+        const klass = typeof hash["_type"] === "string" ? resolveType(hash["_type"]) : undefined;
+        if (klass && klass !== this) {
+            return klass.fromHash(hash);
+        }
+        const inflated = this.inflateScalarComponents(hash);
+        return new this(this.applyMappings(inflated));
+    }
+    /** Re-nest flat scalars into component hashes (identifier.rb inflate_scalar_components). */
+    static inflateScalarComponents(data) {
+        const klass = this;
+        if (!klass.attributes)
+            return data;
+        const convertedKeys = new Set((klass.mappings ?? []).map((m) => m.wire));
+        const out = { ...data };
+        for (const [attrName, flatKey] of Object.entries({ ...FLAT_SCALAR_COMPONENTS, ...klass.flatScalarComponents })) {
+            const spec = klass.attributes[attrName];
+            if (!spec || typeof spec.type === "string")
+                continue; // component attributes only
+            if (convertedKeys.has(flatKey))
+                continue;
+            if (flatKey !== attrName && flatKey in klass.attributes)
+                continue;
+            const value = out[flatKey];
+            if (value === undefined || value === null || typeof value === "object")
+                continue;
+            const field = FLAT_SCALAR_FIELDS[attrName];
+            if (Array.isArray(value))
+                continue; // scalar-list collections keep their name
+            delete out[flatKey];
+            out[attrName] = { [field]: String(value) };
+        }
+        return out;
+    }
+    /** Apply custom `fromWire` converters to the inflated hash. */
+    static applyMappings(data) {
+        const klass = this;
+        const mappings = klass.mappings;
+        if (!mappings)
+            return data;
+        const out = { ...data };
+        for (const m of mappings) {
+            if (m.fromWire && m.wire in out) {
+                const value = m.fromWire(out);
+                if (value !== undefined && value !== null)
+                    out[m.to] = value;
+            }
+            else if (m.wire !== m.to && m.wire in out) {
+                out[m.to] = out[m.wire];
+                delete out[m.wire];
+            }
+        }
+        return out;
+    }
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/model/urn-generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * BaseUrnGenerator — the TS mirror of Pubid::UrnGenerator::Base
+ * (TODO.unified/01 §4). Flavors with a Ruby `urn_generator.rb` subclass
+ * and override hooks; flavors without one (doi, isbn, omg, un, gb) use
+ * this template directly, and the parts are derived from their declared
+ * attributes — never hand-assembled per flavor.
+ */
+import type { BaseIdentifier } from "./identifier.js";
+type UrnableIdentifier = BaseIdentifier;
+export declare class BaseUrnGenerator<T extends UrnableIdentifier = UrnableIdentifier> {
+    protected readonly identifier: T;
+    constructor(identifier: T);
+    generate(): string;
+    /** Template methods — override in subclasses (Ruby precedent). */
+    protected urnNamespace(): string;
+    /** Reads a DECLARED attribute only (Base#maybe) — constants never appear. */
+    protected maybe(name: string): unknown;
+    protected urnPublisher(): string | undefined;
+    protected urnType(): string | undefined;
+    protected urnNumber(): string | undefined;
+    protected urnPart(): string | undefined;
+    protected urnSubpart(): string | undefined;
+    protected urnYear(): string | undefined;
+    protected urnEdition(): string | undefined;
+    protected urnLanguage(): string | undefined;
+}
+export {};

package/dist/model/urn-generator.js

@@ -0,0 +1,91 @@
+/**
+ * BaseUrnGenerator — the TS mirror of Pubid::UrnGenerator::Base
+ * (TODO.unified/01 §4). Flavors with a Ruby `urn_generator.rb` subclass
+ * and override hooks; flavors without one (doi, isbn, omg, un, gb) use
+ * this template directly, and the parts are derived from their declared
+ * attributes — never hand-assembled per flavor.
+ */
+import { renderComponent } from "./component.js";
+export class BaseUrnGenerator {
+    identifier;
+    constructor(identifier) {
+        this.identifier = identifier;
+    }
+    generate() {
+        const parts = ["urn", this.urnNamespace()];
+        const push = (v) => {
+            if (v !== undefined && v !== null && v !== "")
+                parts.push(v);
+        };
+        push(this.urnPublisher());
+        push(this.urnType());
+        push(this.urnNumber());
+        push(this.urnPart());
+        push(this.urnSubpart());
+        push(this.urnYear());
+        push(this.urnEdition());
+        push(this.urnLanguage());
+        return parts.join(":");
+    }
+    /** Template methods — override in subclasses (Ruby precedent). */
+    urnNamespace() {
+        // Pubid::<Flavor>::… → flavor name downcased; derived from _type.
+        const [, flavor] = this.identifier.constructor.polymorphicName.split(":");
+        return flavor ?? "unknown";
+    }
+    /** Reads a DECLARED attribute only (Base#maybe) — constants never appear. */
+    maybe(name) {
+        const attributes = this.identifier.constructor.attributes;
+        if (!attributes || !(name in attributes))
+            return undefined;
+        return this.identifier[name];
+    }
+    urnPublisher() {
+        const pub = this.maybe("publisher");
+        if (pub === undefined || pub === null)
+            return undefined;
+        return renderComponent(pub, "urn");
+    }
+    urnType() {
+        return undefined;
+    }
+    urnNumber() {
+        const val = this.maybe("number") ?? this.maybe("code");
+        return val === undefined || val === null ? undefined : renderComponent(val, "urn");
+    }
+    urnPart() {
+        const val = this.maybe("part");
+        return val === undefined || val === null ? undefined : `-${renderComponent(val, "urn")}`;
+    }
+    urnSubpart() {
+        const val = this.maybe("subpart");
+        return val === undefined || val === null ? undefined : `-${renderComponent(val, "urn")}`;
+    }
+    urnYear() {
+        const date = this.maybe("date");
+        if (date !== undefined && date !== null && typeof date === "object" && "render" in date) {
+            const rendered = date.render("urn");
+            return rendered ?? undefined;
+        }
+        if (date !== undefined && date !== null)
+            return String(date);
+        const year = this.maybe("year");
+        return year === undefined || year === null ? undefined : String(year);
+    }
+    urnEdition() {
+        const ed = this.maybe("edition");
+        if (ed === undefined || ed === null)
+            return undefined;
+        const num = typeof ed === "object" && "number" in ed ? ed.number : ed;
+        return num === undefined || num === null || num === "" ? undefined : `ed.${String(num)}`;
+    }
+    urnLanguage() {
+        const langs = this.maybe("languages");
+        if (!Array.isArray(langs) || langs.length === 0)
+            return undefined;
+        return langs
+            .map((l) => renderComponent(l, "urn"))
+            .filter((s) => s !== undefined)
+            .join(",");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pubid/pubid",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "TypeScript PubID identifiers: resolution, normalization and canonical hashes for every identifier in the pubid-testsuite corpus (41 standards bodies), with a conformance runner mirroring the Ruby reference",
   "type": "module",
   "license": "MIT",