@pubid/pubid 0.1.3 → 0.1.5

package/dist/model/component.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The unified model's Components — the TS mirror of lib/pubid/components/.
+ * Semantics pinned in TODO.unified/01-study-pubid-core.md §6-7.
+ *
+ * Every component carries: plain fields, `render(context)` (the
+ * RenderingContext seam: "human" default, "urn" lowercases / year-only),
+ * `toWire()` (its serialized hash form), and degenerate-scalar support
+ * (a component holding only its single significant field collapses to
+ * that scalar in the canonical hash).
+ */
+export type RenderContext = "human" | "urn";
+/** Render a value that may be a component or a bare scalar (Renderers::Base#render_component). */
+export declare function renderComponent(value: unknown, context?: RenderContext): string | undefined;
+export declare abstract class Component {
+    /** The serialized hash form (lutaml to_hash of the component). */
+    abstract toWire(): Record<string, unknown>;
+    /** The render seam (context: human default, urn lowercases etc.). */
+    abstract render(context?: RenderContext): string | undefined;
+    /**
+     * The scalar this component degenerates to when `field` is its only
+     * significant value, else undefined (Pubid::Identifier#degenerate_scalar).
+     * A field holding another component never degenerates.
+     */
+    degenerateScalar(field: string): string | undefined;
+    /** True when `value` equals the field's declared default. */
+    protected fieldIsDefaulted(_name: string, _value: unknown): boolean;
+}
+/** Publication date (Components::Date). Human "YYYY[-MM[-DD]]", URN year only, "--" undated. */
+export declare class PubidDate extends Component {
+    readonly year?: string | undefined;
+    readonly month?: string | undefined;
+    readonly day?: string | undefined;
+    readonly undated: boolean;
+    constructor(attrs: Record<string, unknown>);
+    present(): boolean;
+    render(context?: RenderContext): string | undefined;
+    toWire(): Record<string, unknown>;
+    protected fieldIsDefaulted(name: string, value: unknown): boolean;
+}
+/** Publisher (Components::Publisher): body; URN render lowercases. */
+export declare class Publisher extends Component {
+    readonly body: string;
+    constructor(attrs: Record<string, unknown>);
+    render(context?: RenderContext): string;
+    toWire(): Record<string, unknown>;
+}
+/** Language (Components::Language): single-char CHAR_MAP codes; URN lowercases. */
+export declare class Language extends Component {
+    static readonly CHAR_MAP: Record<string, string>;
+    readonly code: string;
+    readonly originalCode?: string | undefined;
+    constructor(attrs: Record<string, unknown>);
+    render(context?: RenderContext): string;
+    toWire(): Record<string, unknown>;
+}
+/** Edition (Components::Edition): degenerates to its number. */
+export declare class Edition extends Component {
+    readonly number: string;
+    readonly phase?: string | undefined;
+    constructor(attrs: Record<string, unknown>);
+    render(context?: RenderContext): string | undefined;
+    toWire(): Record<string, unknown>;
+}
+/** Iteration (Components::Iteration): degenerate by construction. */
+export declare class Iteration extends Component {
+    readonly string: string;
+    constructor(attrs: Record<string, unknown>);
+    render(_context?: RenderContext): string | undefined;
+    toWire(): Record<string, unknown>;
+}

package/dist/model/component.js

@@ -0,0 +1,170 @@
+/**
+ * The unified model's Components — the TS mirror of lib/pubid/components/.
+ * Semantics pinned in TODO.unified/01-study-pubid-core.md §6-7.
+ *
+ * Every component carries: plain fields, `render(context)` (the
+ * RenderingContext seam: "human" default, "urn" lowercases / year-only),
+ * `toWire()` (its serialized hash form), and degenerate-scalar support
+ * (a component holding only its single significant field collapses to
+ * that scalar in the canonical hash).
+ */
+/** Render a value that may be a component or a bare scalar (Renderers::Base#render_component). */
+export function renderComponent(value, context) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (value instanceof Component)
+        return value.render(context);
+    return String(value);
+}
+export class Component {
+    /**
+     * The scalar this component degenerates to when `field` is its only
+     * significant value, else undefined (Pubid::Identifier#degenerate_scalar).
+     * A field holding another component never degenerates.
+     */
+    degenerateScalar(field) {
+        let found;
+        for (const [name, value] of Object.entries(this)) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            if (this.fieldIsDefaulted(name, value))
+                continue;
+            if (name === field) {
+                if (value instanceof Component)
+                    return undefined;
+                found = String(value);
+            }
+            else {
+                return undefined;
+            }
+        }
+        return found;
+    }
+    /** True when `value` equals the field's declared default. */
+    fieldIsDefaulted(_name, _value) {
+        return false;
+    }
+}
+const pad2 = (value) => value.padStart(2, "0");
+/** Publication date (Components::Date). Human "YYYY[-MM[-DD]]", URN year only, "--" undated. */
+export class PubidDate extends Component {
+    year;
+    month;
+    day;
+    undated;
+    constructor(attrs) {
+        super();
+        this.year = attrs["year"];
+        this.month = attrs["month"];
+        this.day = attrs["day"];
+        this.undated = attrs["undated"] ?? false;
+    }
+    present() {
+        if (this.undated)
+            return true;
+        return this.year !== undefined && this.year !== "";
+    }
+    render(context) {
+        if (this.undated && (this.year === undefined || this.year === ""))
+            return "--";
+        if (!this.present())
+            return undefined;
+        if (context === "urn")
+            return this.year;
+        if (this.month === undefined)
+            return this.year;
+        let result = `${this.year}-${pad2(this.month)}`;
+        if (this.day !== undefined)
+            result += `-${pad2(this.day)}`;
+        return result;
+    }
+    toWire() {
+        const wire = {};
+        if (this.year !== undefined)
+            wire["year"] = this.year;
+        if (this.month !== undefined)
+            wire["month"] = this.month;
+        if (this.day !== undefined)
+            wire["day"] = this.day;
+        if (this.undated)
+            wire["undated"] = true;
+        return wire;
+    }
+    fieldIsDefaulted(name, value) {
+        return name === "undated" && value === false;
+    }
+}
+/** Publisher (Components::Publisher): body; URN render lowercases. */
+export class Publisher extends Component {
+    body;
+    constructor(attrs) {
+        super();
+        this.body = attrs["body"];
+    }
+    render(context) {
+        return context === "urn" ? this.body.toLowerCase() : this.body;
+    }
+    toWire() {
+        return { body: this.body };
+    }
+}
+/** Language (Components::Language): single-char CHAR_MAP codes; URN lowercases. */
+export class Language extends Component {
+    static CHAR_MAP = {
+        R: "ru",
+        F: "fr",
+        E: "en",
+        A: "ar",
+        S: "es",
+        D: "de",
+    };
+    code;
+    originalCode;
+    constructor(attrs) {
+        super();
+        this.code = attrs["code"];
+        this.originalCode = (attrs["originalCode"] ?? attrs["original_code"]);
+    }
+    render(context) {
+        if (context === "urn")
+            return this.code.toLowerCase();
+        if (this.originalCode !== undefined) {
+            return this.originalCode.length === 1 ? this.code : this.originalCode;
+        }
+        return this.code;
+    }
+    toWire() {
+        return this.originalCode === undefined ? { code: this.code } : { code: this.code, original_code: this.originalCode };
+    }
+}
+/** Edition (Components::Edition): degenerates to its number. */
+export class Edition extends Component {
+    number;
+    phase;
+    constructor(attrs) {
+        super();
+        this.number = attrs["number"];
+        this.phase = attrs["phase"];
+    }
+    render(context) {
+        void context;
+        return this.phase === undefined ? this.number : `${this.number}${this.phase}`;
+    }
+    toWire() {
+        return this.phase === undefined ? { number: this.number } : { number: this.number, phase: this.phase };
+    }
+}
+/** Iteration (Components::Iteration): degenerate by construction. */
+export class Iteration extends Component {
+    string;
+    constructor(attrs) {
+        super();
+        this.string = attrs["string"];
+    }
+    render(_context) {
+        return this.string;
+    }
+    toWire() {
+        return { string: this.string };
+    }
+}

package/dist/model/identifier.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 type { AttributeTable, FieldMapping } from "./attribute.js";
+export interface IdentifierStatic {
+    new (attrs?: Record<string, unknown>): BaseIdentifier;
+    polymorphicName: string;
+    attributes: AttributeTable;
+    /** Optional mapping overrides; default = every attribute under its own name. */
+    mappings?: FieldMapping[];
+    /** Per-class shorter-wire hook (Ruby compact_hash); must invert in inflate. */
+    compactHash?: (model: BaseIdentifier, hash: Record<string, unknown>) => void;
+    /** Additional flat-scalar entries for this class. */
+    flatScalarComponents?: Record<string, string>;
+    /** The field each additional flat-scalar component degenerates to. */
+    flatScalarFields?: Record<string, string>;
+    fromHash(hash: Record<string, unknown>): BaseIdentifier;
+    /** The flavor's URN generator; undefined = the base template (Ruby resolve_urn_generator fallback). */
+    urnGenerator?: UrnGeneratorCtor;
+}
+export type UrnGeneratorCtor = new (identifier: BaseIdentifier) => {
+    generate(): string;
+};
+/** Register a concrete identifier class under its polymorphic _type (the *_TYPE_MAP role). */
+export declare function registerType(klass: IdentifierStatic): void;
+export declare function resolveType(type: string): IdentifierStatic | undefined;
+export declare abstract class BaseIdentifier {
+    static polymorphicName: string;
+    /** The human renderer body — the one method every flavor writes. */
+    abstract render(): string;
+    /** The root table; subclasses compose via extendAttributes(BaseIdentifier, …). */
+    static attributes: AttributeTable;
+    static mappings: FieldMapping[] | undefined;
+    static compactHash: ((model: BaseIdentifier, hash: Record<string, unknown>) => void) | undefined;
+    static flatScalarComponents: Record<string, string> | undefined;
+    ["constructor"]: IdentifierStatic;
+    constructor(attrs?: Record<string, unknown>);
+    /** The human form (Ruby render(format: :human) → the flavor renderer). */
+    toHuman(): string;
+    /** Ruby to_urn: the flavor's UrnGenerator, else the base template. */
+    toUrn(): string;
+    fromHash(hash: Record<string, unknown>): BaseIdentifier;
+    protected classAttributes(): AttributeTable;
+    /** Wire key for an attribute: custom mapping or the attribute name. */
+    protected wireKeyFor(name: string): {
+        wire: string;
+        toWire?: FieldMapping["toWire"];
+    };
+    protected attrValue(name: string): unknown;
+    /** Serialize one attribute's value (component → toWire, nested identifier → toHash, scalars as-is). */
+    protected serializeValue(value: unknown): unknown;
+    /** Nested serialization: same as toHash but with the unfiltered mappings. */
+    toHashNested(): Record<string, unknown>;
+    toHash(): Record<string, unknown>;
+    private toHashWith;
+    /**
+     * 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.
+     */
+    protected flattenScalars(hash: Record<string, unknown>): void;
+    static fromHash(hash: Record<string, unknown>): BaseIdentifier;
+    /** Re-nest flat scalars into component hashes (identifier.rb inflate_scalar_components). */
+    protected static inflateScalarComponents(data: Record<string, unknown>): Record<string, unknown>;
+    /** Apply custom `fromWire` converters to the inflated hash. */
+    protected static applyMappings(data: Record<string, unknown>): Record<string, unknown>;
+}

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);
+}
+export 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 {};