@needle-tools/addressing 0.3.4 → 0.4.0

package/src/document/assets.ts

@@ -0,0 +1,77 @@
+import type { ProjectDocument, ProjectDocumentAsset, ProjectDocumentReference } from "./types.js";
+
+/** Asset keys and shared resource identities for one document assembly. */
+export class DocumentAssetAssembly {
+    private readonly assetBySrc = new Map<string, string>();
+    private readonly referenceById = new Map<string, ProjectDocumentReference>();
+    private readonly materialBySource = new Map<string, ProjectDocumentReference>();
+    private readonly baseMaterialBySource = new Map<string, ProjectDocumentReference>();
+
+    constructor(
+        private readonly assets: Record<string, ProjectDocumentAsset>,
+        private readonly references: ProjectDocumentReference[],
+        base?: ProjectDocument | null,
+    ) {
+        for (const [key, asset] of Object.entries(assets)) this.assetBySrc.set(asset.src, key);
+        for (const reference of references) {
+            this.referenceById.set(reference.id, reference);
+            const key = this.materialKey(reference, assets);
+            if (key) this.materialBySource.set(key, reference);
+        }
+        for (const reference of base?.references ?? []) {
+            const key = this.materialKey(reference, base?.assets ?? {});
+            if (key) this.baseMaterialBySource.set(key, reference);
+        }
+    }
+
+    addAsset(input: { src: string; name?: string; kind: string; identity?: { id: string; provider?: string } }): string {
+        const existing = this.assetBySrc.get(input.src);
+        if (existing !== undefined) return existing;
+        const filename = input.src.split("?")[0].split("/").pop() || "material";
+        const dot = filename.lastIndexOf(".");
+        const stem = input.name || (dot > 0 ? filename.substring(0, dot) : filename);
+        let key = stem;
+        let n = 2;
+        while (key in this.assets) key = `${stem}-${n++}`;
+        this.assets[key] = { src: input.src, kind: input.kind, ...(input.identity ? { asset: { ...input.identity } } : {}) };
+        this.assetBySrc.set(input.src, key);
+        return key;
+    }
+
+    materialEntity(asset: string, material: { id: string; name?: string }, entityId: string): string {
+        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
+        const key = JSON.stringify([this.assets[asset].src, material.id]);
+        const existing = this.materialBySource.get(key);
+        if (existing) return existing.id;
+        const base = this.baseMaterialBySource.get(key);
+        const reference: ProjectDocumentReference = base ? { ...base, asset } : {
+            id: entityId, asset, address: { type: "material", id: material.id, ...(material.name ? { name: material.name } : {}) },
+        };
+        this.addReference(reference);
+        this.materialBySource.set(key, reference);
+        return reference.id;
+    }
+
+    environmentEntity(asset: string, entityId: string): string {
+        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
+        this.addReference({ id: entityId, asset, address: { type: "hdr" } });
+        return entityId;
+    }
+
+    private addReference(reference: ProjectDocumentReference): void {
+        const existing = this.referenceById.get(reference.id);
+        if (existing) {
+            if (existing.asset !== reference.asset || existing.address?.type !== reference.address?.type || existing.address?.id !== reference.address?.id) {
+                throw new Error(`Document reference id '${reference.id}' already identifies another resource`);
+            }
+            return;
+        }
+        this.references.push(reference);
+        this.referenceById.set(reference.id, reference);
+    }
+
+    private materialKey(reference: ProjectDocumentReference, assets: Record<string, ProjectDocumentAsset>): string | null {
+        return reference.address?.type === "material" && reference.address.id && assets[reference.asset]
+            ? JSON.stringify([assets[reference.asset].src, reference.address.id]) : null;
+    }
+}

package/src/document/collectionSelector.ts

@@ -0,0 +1,37 @@
+export interface DocumentCollectionSelectorOptions {
+    matchesComponentType?(component: object, name: string): boolean;
+    matchesComponentGuid?(component: object, guid: string): boolean;
+    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
+    referenceId?: string;
+    report?(message: string): void;
+}
+
+/** Resolve an index or field qualifier; ambiguous identities never select an arbitrary member. */
+export function resolveDocumentCollectionElement(
+    collection: readonly unknown[], selector: string, options: DocumentCollectionSelectorOptions = {},
+): unknown {
+    if (/^\d+$/.test(selector)) return collection[Number(selector)];
+    const qualifier = /^([A-Za-z_][A-Za-z0-9_-]*):([\s\S]*)$/.exec(selector);
+    if (!qualifier) {
+        options.report?.(`"${selector}" is neither an index nor a <field>:<value> qualifier`);
+        return undefined;
+    }
+    const [, field, value] = qualifier;
+    const elements = collection.filter((element): element is Record<string, unknown> =>
+        element !== null && typeof element === "object");
+    let matches = elements.filter(element => {
+        if (field === "type") return options.matchesComponentType?.(element, value) ?? element.constructor?.name === value;
+        if (field === "guid") return options.matchesComponentGuid?.(element, value)
+            ?? (element.guid === value || element.needle_editor_guid === value);
+        return element[field] === value;
+    });
+    if (!matches.length && field === "guid" && options.referenceId && options.deriveComponentGuid) {
+        const derived = options.deriveComponentGuid(options.referenceId, value);
+        matches = elements.filter(element => element.guid === derived);
+    }
+    if (matches.length > 1) {
+        options.report?.(`"${selector}" matched ${matches.length} elements ? the document must name one unambiguously`);
+        return undefined;
+    }
+    return matches[0];
+}