@pubid/pubid 0.1.3 → 0.1.4

package/dist/model/builder.js

@@ -0,0 +1,124 @@
+/**
+ * BaseBuilder — the TS mirror of Pubid::Builder::Base
+ * (TODO.unified/01 §5). The shared build loop: flatten the parslet tree
+ * (array of hashes → merged hash), ask selectClass for the concrete
+ * class, then assign each tree key through cast(); unknown keys are
+ * silently skipped; cast may return a hash to fan out.
+ */
+import { PubidDate } from "./component.js";
+import { Language } from "./component.js";
+export class BaseBuilder {
+    /** Override to dispatch by data shape (type token, supplement marker…). */
+    selectClass(_data) {
+        return this.defaultIdentifierClass();
+    }
+    /**
+     * Override to convert raw parsed values to components. Return a hash to
+     * assign multiple attributes, a single value, or null/undefined to skip.
+     */
+    cast(_key, value) {
+        return value;
+    }
+    /** Override for non-attribute side effects; return true when consumed. */
+    handleKey(_identifier, _key, _value) {
+        return false;
+    }
+    build(data) {
+        const flat = this.flattenArray(data);
+        const IdentifierClass = this.selectClass(flat);
+        const identifier = new IdentifierClass();
+        this.assignAttributes(identifier, flat);
+        return identifier;
+    }
+    flattenArray(data) {
+        if (Array.isArray(data)) {
+            return Object.assign({}, ...data);
+        }
+        return data;
+    }
+    assignAttributes(identifier, data) {
+        const attrs = identifier.constructor.attributes;
+        for (const [key, value] of Object.entries(data)) {
+            const realized = this.cast(key, value);
+            if (realized === null || realized === undefined)
+                continue;
+            if (this.handleKey(identifier, key, realized))
+                continue;
+            const target = identifier;
+            if (typeof realized === "object" && !Array.isArray(realized)) {
+                for (const [k, v] of Object.entries(realized)) {
+                    if (k in attrs)
+                        target[k] = v;
+                }
+            }
+            else if (key in attrs) {
+                target[key] = realized;
+            }
+        }
+    }
+    // Shared helpers (Builder::Base private API).
+    parseDate(value) {
+        const str = String(value);
+        const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?$/.exec(str);
+        if (m) {
+            return new PubidDate({ year: m[1], month: m[2], day: m[3] });
+        }
+        if (/^\d{4}$/.test(str))
+            return new PubidDate({ year: str });
+        throw new Error(`Invalid date format: ${str}`);
+    }
+    parseLanguages(value) {
+        return String(value)
+            .replaceAll("/", ",")
+            .split(",")
+            .map((lang) => {
+            const original = lang.trim();
+            const code = Language.CHAR_MAP[original] ?? original;
+            return new Language({ code, originalCode: original });
+        });
+    }
+    static ROMAN = {
+        I: 1, V: 5, X: 10, L: 50, C: 100, D: 500, M: 1000,
+    };
+    convertRomanToInteger(roman) {
+        const str = String(roman);
+        if (!/^[IVXLCDM]+$/i.test(str))
+            return str;
+        let result = 0;
+        let prev = 0;
+        for (const char of str.toUpperCase().split("").reverse()) {
+            const value = BaseBuilder.ROMAN[char];
+            result += value < prev ? -value : value;
+            prev = value;
+        }
+        return String(result);
+    }
+    /**
+     * "1234-1-2" → {number, part?, subpart?}; roman parts convert to
+     * integers; normalizeNumberWithPart / extractLegacyYear are hooks.
+     */
+    parseNumberWithPart(value) {
+        const normalized = this.normalizeNumberWithPart(String(value));
+        const parts = normalized.split("-").filter((p) => p !== "");
+        const number = parts.shift();
+        let part = parts.shift()?.trim();
+        const subpart = parts.length > 0 ? parts.join("-") : undefined;
+        const legacy = this.extractLegacyYear(number, part);
+        if (legacy)
+            return legacy;
+        if (part !== undefined)
+            part = this.convertRomanToInteger(part);
+        const out = { number };
+        if (part !== undefined)
+            out["part"] = part;
+        if (subpart !== undefined)
+            out["subpart"] = subpart;
+        return out;
+    }
+    normalizeNumberWithPart(value) {
+        return value;
+    }
+    extractLegacyYear(_number, _part) {
+        return undefined;
+    }
+}

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,83 @@
+/**
+ * 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 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>;
+}