@openbim/ifcx 0.1.0 → 0.2.1

package/openbim_ifcx_wasm.d.ts

@@ -92,7 +92,8 @@ export type IfcxErrorCode =
 | "layer"
 | "compose"
 | "invalid-argument"
-| "glb";
+| "glb"
+| "fetch";
 
 
 
@@ -135,3 +136,4 @@ export class IfcxFile {
      */
     readonly nodeCount: number;
 }
+export * from "./fetch-imports.js";

package/openbim_ifcx_wasm.js

@@ -487,3 +487,4 @@ const wasmBytes = require('fs').readFileSync(wasmPath);
 const wasmModule = new WebAssembly.Module(wasmBytes);
 let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
 let wasm = wasmInstance.exports;
+exports.fetchImports = require("./fetch-imports.js").fetchImports;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openbim/ifcx",
-  "description": "Read, write, validate and compose IFC5 / IFCX files, and export GLB, from JavaScript (WebAssembly build of openbim-ifcx).",
-  "version": "0.1.0",
+  "description": "Read, write, validate and compose IFC5 / IFCX files, and export GLB, from JavaScript in Node and the browser (WebAssembly build of openbim-ifcx).",
+  "version": "0.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,16 +11,42 @@
   "type": "commonjs",
   "main": "openbim_ifcx_wasm.js",
   "types": "openbim_ifcx_wasm.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./openbim_ifcx_wasm.d.ts",
+        "default": "./openbim_ifcx_wasm.js"
+      },
+      "default": {
+        "types": "./bundler/openbim_ifcx_wasm.d.ts",
+        "default": "./bundler/openbim_ifcx_wasm.js"
+      }
+    },
+    "./bundler": {
+      "types": "./bundler/openbim_ifcx_wasm.d.ts",
+      "default": "./bundler/openbim_ifcx_wasm.js"
+    },
+    "./web": {
+      "types": "./web/openbim_ifcx_wasm.d.ts",
+      "default": "./web/openbim_ifcx_wasm.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "files": [
     "openbim_ifcx_wasm.js",
     "openbim_ifcx_wasm.d.ts",
     "openbim_ifcx_wasm_bg.wasm",
     "openbim_ifcx_wasm_bg.wasm.d.ts",
+    "fetch-imports.js",
+    "fetch-imports.d.ts",
+    "bundler/",
+    "web/",
     "README.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=18"
   },
-  "keywords": ["ifcx", "ifc5", "ifc", "bim", "openbim", "gltf", "wasm"]
+  "keywords": ["ifcx", "ifc5", "ifc", "bim", "openbim", "gltf", "wasm", "browser"]
 }

package/web/fetch-imports.d.ts

@@ -0,0 +1,53 @@
+import type { IfcxInput } from "./openbim_ifcx_wasm.js";
+
+/** The part of a `fetch` `Response` that `fetchImports` reads. */
+export interface FetchedResponse {
+  ok?: boolean;
+  status?: number;
+  statusText?: string;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+/**
+ * Loads one imported file. `fetch` itself fits; a custom function may also
+ * return the file directly. `url` is the import `uri` resolved against the
+ * importing file's URL (or `baseUrl`); when a relative `uri` has no base to
+ * resolve against, a custom function receives the `uri` unchanged.
+ */
+export type ImportFetcher = (
+  url: string,
+  init?: { signal?: AbortSignal },
+) => Promise<FetchedResponse | IfcxInput | ArrayBuffer>;
+
+/** Options for `fetchImports`. */
+export interface FetchImportsOptions {
+  /**
+   * URL that relative import URIs of the given layers resolve against.
+   * Defaults to `location.href` in a browser. Imports of a fetched file
+   * resolve against that file's URL.
+   */
+  baseUrl?: string | URL;
+  /** Loads each file. Defaults to the global `fetch`. */
+  fetch?: ImportFetcher;
+  /** Files already at hand, keyed by import `uri`; never fetched again. */
+  imports?: Record<string, IfcxInput> | Map<string, IfcxInput>;
+  /** Passed to every fetch call. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Fetch every file the layers import, recursively and each `uri` once, and
+ * return them keyed by the exact import `uri`: the `imports` option of
+ * `compose`, `validate` and `exportGlb`. Network access happens here, in
+ * JavaScript; the WebAssembly module never fetches anything. A file that
+ * cannot be fetched rejects with an `IfcxError` whose `code` is `"fetch"`.
+ *
+ * ```js
+ * const imports = await fetchImports(layers, { baseUrl: "https://example.org/model/" });
+ * const tree = compose(layers, { imports });
+ * ```
+ */
+export function fetchImports(
+  layers: IfcxInput | IfcxInput[],
+  options?: FetchImportsOptions,
+): Promise<Map<string, IfcxInput>>;

package/web/fetch-imports.js

@@ -0,0 +1,137 @@
+// Import resolution over `fetch`, for the `imports` option of `compose`,
+// `validate` and `exportGlb`.
+//
+// Plain JavaScript on purpose: the Rust crates perform no network access
+// (ADR 0002), so the binding resolves imports in memory only and this
+// module does the fetching on the JavaScript side. It reads each layer's
+// `imports` list, fetches every named file (recursively, each URI once) and
+// returns the files keyed by their exact import `uri`, which is what the
+// in-memory `imports` option expects. Integrity values are checked later,
+// by the binding, against the fetched bytes.
+//
+// This file is the ES module source. scripts/build-npm-pkg.sh copies it into
+// the `web` and `bundler` builds and derives the CommonJS copy for the Node
+// build from it, so it must stay self-contained: no imports, and every
+// export a top-level `export async function` or `export function`.
+
+/** The imports of an IFCX file, or none when it is not readable JSON. */
+function importUris(input) {
+  let text = input;
+  if (typeof input !== "string") {
+    text = new TextDecoder().decode(input);
+  }
+  let file;
+  try {
+    file = JSON.parse(text);
+  } catch {
+    // Not JSON: the binding call that receives it reports where.
+    return [];
+  }
+  const imports = file !== null && typeof file === "object" ? file.imports : undefined;
+  if (!Array.isArray(imports)) return [];
+  return imports
+    .map((entry) => (entry !== null && typeof entry === "object" ? entry.uri : undefined))
+    .filter((uri) => typeof uri === "string");
+}
+
+function fetchError(message, cause) {
+  const error = new Error(message, cause === undefined ? undefined : { cause });
+  error.name = "IfcxError";
+  error.code = "fetch";
+  return error;
+}
+
+function isInput(value) {
+  return typeof value === "string" || value instanceof Uint8Array;
+}
+
+/** The URL `uri` names, relative to `base`; `undefined` if it cannot be resolved. */
+function resolveUrl(uri, base) {
+  try {
+    return base === undefined ? new URL(uri).href : new URL(uri, base).href;
+  } catch {
+    return undefined;
+  }
+}
+
+/** What a fetch function returned, as an IFCX input. */
+async function readResponse(response, uri, url) {
+  if (isInput(response)) return response;
+  if (response instanceof ArrayBuffer) return new Uint8Array(response);
+  if (response !== null && typeof response === "object" && typeof response.arrayBuffer === "function") {
+    if (response.ok === false) {
+      const status = [response.status, response.statusText].filter(Boolean).join(" ");
+      throw fetchError(`could not fetch import ${JSON.stringify(uri)} from ${url}: HTTP ${status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  throw fetchError(
+    `the fetch function returned neither a Response, a Uint8Array, an ArrayBuffer nor a string for ${JSON.stringify(uri)}`,
+  );
+}
+
+/**
+ * Fetch every file the layers import, recursively, keyed by the exact
+ * import `uri`, for the `imports` option of `compose`, `validate` and
+ * `exportGlb`.
+ */
+export async function fetchImports(layers, options = {}) {
+  const list = Array.isArray(layers) ? layers : [layers];
+  for (const layer of list) {
+    if (!isInput(layer)) {
+      throw fetchError("every layer must be a string or a Uint8Array");
+    }
+  }
+  const fetcher = options.fetch ?? globalThis.fetch;
+  if (typeof fetcher !== "function") {
+    throw fetchError("no fetch function: pass options.fetch");
+  }
+  const custom = options.fetch !== undefined;
+  const base =
+    options.baseUrl !== undefined ? String(options.baseUrl) : globalThis.location?.href;
+  const init = options.signal === undefined ? undefined : { signal: options.signal };
+
+  const found = new Map();
+  if (options.imports !== undefined) {
+    const known = options.imports instanceof Map ? options.imports : Object.entries(options.imports);
+    for (const [uri, file] of known) found.set(uri, file);
+  }
+
+  // Breadth first; each level's fetches run concurrently. `url` is where a
+  // layer came from, so its relative imports resolve against it.
+  let level = list.map((file) => ({ file, url: base }));
+  for (const [, file] of found) level.push({ file, url: base });
+  while (level.length > 0) {
+    const pending = [];
+    for (const { file, url: importer } of level) {
+      for (const uri of importUris(file)) {
+        if (found.has(uri)) continue;
+        found.set(uri, undefined); // claimed: fetch each URI once
+        const url = resolveUrl(uri, importer);
+        if (url === undefined && !custom) {
+          throw fetchError(
+            `cannot resolve import ${JSON.stringify(uri)} to a URL: pass options.baseUrl`,
+          );
+        }
+        pending.push(
+          (async () => {
+            let response;
+            try {
+              response = await fetcher(url ?? uri, init);
+            } catch (error) {
+              throw fetchError(
+                `could not fetch import ${JSON.stringify(uri)} from ${url ?? uri}: ${error?.message ?? error}`,
+                error,
+              );
+            }
+            const fetched = await readResponse(response, uri, url ?? uri);
+            found.set(uri, fetched);
+            return { file: fetched, url: url ?? importer };
+          })(),
+        );
+      }
+    }
+    level = await Promise.all(pending);
+  }
+  return found;
+}

package/web/openbim_ifcx_wasm.d.ts

@@ -0,0 +1,182 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** An IFCX file as JSON text or as its UTF-8 bytes. */
+export type IfcxInput = string | Uint8Array;
+
+/** Options for `compose` and `validate`. */
+export interface LayerOptions {
+    /**
+     * Files that imports name, keyed by the exact import `uri`. When given
+     * (even empty), imports are resolved as upstream does and every import
+     * must be here; without it, imports are not resolved.
+     */
+    imports?: Record<string, IfcxInput> | Map<string, IfcxInput>;
+}
+
+/** One node of a composed tree. The root has path `""`. */
+export interface ComposedNode {
+    path: string;
+    attributes: Record<string, unknown>;
+    children: Record<string, ComposedNode>;
+}
+
+/** The `kind` of a validation failure. */
+export type ValidationFailureKind =
+| "missing-schema"
+| "unknown-inherited-schema"
+| "inheritance-cycle"
+| "type-mismatch"
+| "not-an-integer"
+| "not-an-option"
+| "missing-key"
+| "too-few-elements"
+| "too-many-elements"
+| "missing-restrictions"
+| "unknown-data-type"
+| "other";
+
+/** One attribute value that does not match its schema. */
+export interface ValidationFailure {
+    /** Path of the node carrying the attribute. */
+    node: string;
+    /** Attribute id, which is also the schema id. */
+    attribute: string;
+    /** RFC 6901 JSON pointer into the value; `""` for the value itself. */
+    pointer: string;
+    kind: ValidationFailureKind;
+    message: string;
+}
+
+export interface ValidationReport {
+    valid: boolean;
+    failures: ValidationFailure[];
+}
+
+/**
+ * Compose layers, weakest first, into a tree of plain objects: the
+ * artificial root (path `""`) over every root node.
+ */
+export function compose(layers: IfcxInput | IfcxInput[], options?: LayerOptions): ComposedNode;
+
+/**
+ * Check the attributes of the layers, weakest first, against the schemas of
+ * every layer (and of resolved imports), after merging nodes that share a
+ * path.
+ */
+export function validate(layers: IfcxInput | IfcxInput[], options?: LayerOptions): ValidationReport;
+
+/** Options for `exportGlb`. */
+export interface GlbOptions extends LayerOptions {
+    /** Rotate IFCX's Z-up axes to glTF's Y-up. Default `true`. */
+    yUp?: boolean;
+    /**
+     * Keep the model's coordinates by putting the scene origin on the root
+     * node. With `false` the model sits around the glTF origin, which is then
+     * only recorded in the root's `extras.ifcxOrigin`. Default `true`.
+     */
+    originOnRoot?: boolean;
+}
+
+/**
+ * Compose layers, weakest first, and write their render scene as a binary
+ * glTF 2.0 (`.glb`) file: transformed, instanced meshes, lines and points
+ * with their materials, one glTF node per instance named by its IFCX path.
+ */
+export function exportGlb(layers: IfcxInput | IfcxInput[], options?: GlbOptions): Uint8Array;
+
+/** The `code` of an `IfcxError`. */
+export type IfcxErrorCode =
+| "read"
+| "write"
+| "layer"
+| "compose"
+| "invalid-argument"
+| "glb"
+| "fetch";
+
+
+
+/**
+ * One IFCX file. Writing it back is lossless: key order, unknown fields,
+ * `null` deletions and every number stay as read.
+ *
+ * A newtype because `wasm_bindgen` can only export a type defined in this
+ * crate; all state and behaviour are the core's.
+ */
+export class IfcxFile {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Read an IFCX file from its JSON text or UTF-8 bytes.
+     */
+    static parse(input: IfcxInput): IfcxFile;
+    /**
+     * The file as a plain object, so `JSON.stringify(file)` works. Unlike
+     * `write`, a plain object may reorder integer-like keys and round
+     * integers beyond 2^53.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Check every attribute against this file's own `schemas`. Imports are
+     * not resolved; use the `validate` function to include them.
+     */
+    validate(): ValidationReport;
+    /**
+     * The file as JSON text; `pretty` indents it by two spaces.
+     */
+    write(pretty?: boolean | null): string;
+    /**
+     * The `header` object.
+     */
+    readonly header: Record<string, unknown>;
+    /**
+     * Number of entries in `data`; several may share a path.
+     */
+    readonly nodeCount: number;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_ifcxfile_free: (a: number, b: number) => void;
+    readonly compose: (a: number, b: number, c: number) => void;
+    readonly exportGlb: (a: number, b: number, c: number) => void;
+    readonly ifcxfile_header: (a: number, b: number) => void;
+    readonly ifcxfile_nodeCount: (a: number) => number;
+    readonly ifcxfile_parse: (a: number, b: number) => void;
+    readonly ifcxfile_toJSON: (a: number, b: number) => void;
+    readonly ifcxfile_validate: (a: number, b: number) => void;
+    readonly ifcxfile_write: (a: number, b: number, c: number) => void;
+    readonly validate: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
+export * from "./fetch-imports.js";