@openbim/ifcx 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 point-grey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# @openbim/ifcx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read, write, validate and compose **IFC5 / IFCX** files, and export them as
+GLB, from JavaScript and TypeScript. A WebAssembly build of the
+[`openbim-ifcx`](https://crates.io/crates/openbim-ifcx) Rust crate, from the
+`openbim-ifcx-wasm` crate in [openbimrs/ifcx](https://github.com/openbimrs/ifcx).
+
+Published to npm as `@openbim/ifcx`: one package for Node 18 and later,
+bundlers (webpack, Rollup) and plain browser pages, with TypeScript
+declarations for each. Every build is tested from the packed tarball,
+the browser builds in headless Chrome.
+
+Targets the `ifcx_alpha` draft of buildingSMART's IFC5. IFCX is still a
+moving draft; see the
+[capabilities](https://github.com/openbimrs/ifcx/blob/main/docs/capabilities.md).
+
+## Install
+
+```sh
+npm install @openbim/ifcx
+```
+
+## Entry points
+
+| Import | Build | Loads the wasm module |
+| --- | --- | --- |
+| `@openbim/ifcx` in Node (`require` or `import`) | CommonJS (`wasm-bindgen --target nodejs`) | synchronously, on load |
+| `@openbim/ifcx` in a bundler | ES module (`--target bundler`) | through the bundler's WebAssembly support, e.g. webpack 5 `experiments.asyncWebAssembly` |
+| `@openbim/ifcx/web` | ES module (`--target web`) | when you `await init()` |
+
+`package.json` `exports` picks the build: the `node` condition gets the
+CommonJS build, everything else the bundler build. Use `@openbim/ifcx/web`
+for a page without a bundler, and for bundlers without WebAssembly ES
+module integration, such as Vite (or add `vite-plugin-wasm`). All three
+export the same API; the `web` build adds the default `init` export (and
+`initSync`).
+
+## Node
+
+```js
+const { readFileSync, writeFileSync } = require("node:fs");
+const { IfcxFile, compose, exportGlb } = require("@openbim/ifcx"); // or import
+
+const model = readFileSync("model.ifcx"); // a Buffer is a Uint8Array
+const file = IfcxFile.parse(model); // or a string
+console.log(file.header.id, file.nodeCount);
+
+const report = file.validate();
+for (const f of report.failures) {
+  console.log(f.node, f.attribute, f.pointer, f.kind, f.message);
+}
+const text = file.write(); // JSON text, unchanged from the input
+
+// Layers weakest first: the last layer's opinions win.
+const tree = compose([model, readFileSync("overlay.ifcx")]);
+console.log(Object.keys(tree.children)); // the root nodes
+
+// Any glTF viewer opens the result.
+writeFileSync("model.glb", exportGlb([model, readFileSync("overlay.ifcx")]));
+```
+
+## Browser
+
+With a bundler, import the package as usual; the bundler loads the wasm
+module:
+
+```js
+import { compose, exportGlb, fetchImports } from "@openbim/ifcx";
+```
+
+Without one, serve the package's `web/` directory, map the name in an
+import map (or import the file by URL), and call `init()` once before
+anything else. `init()` fetches `openbim_ifcx_wasm_bg.wasm` from next to
+the module; pass `init({ module_or_path: url })` to load it from elsewhere.
+
+```html
+<script type="importmap">
+  { "imports": { "@openbim/ifcx/web": "/node_modules/@openbim/ifcx/web/openbim_ifcx_wasm.js" } }
+</script>
+<script type="module">
+  import init, { IfcxFile, exportGlb, fetchImports, validate } from "@openbim/ifcx/web";
+
+  await init();
+  const url = new URL("models/house.ifcx", location.href);
+  const model = new Uint8Array(await (await fetch(url)).arrayBuffer());
+
+  // Fetch what the model imports, relative to its own URL, then use it.
+  const imports = await fetchImports(model, { baseUrl: url });
+  const report = validate(model, { imports });
+  const glb = exportGlb(model, { imports }); // e.g. for three.js's GLTFLoader.parse
+  console.log(IfcxFile.parse(model).header.id, report.valid, glb.length);
+</script>
+```
+
+## API
+
+| Call | Returns |
+| --- | --- |
+| `IfcxFile.parse(input)` | an `IfcxFile`; `input` is JSON text or UTF-8 bytes |
+| `file.write(pretty?)` | the file as JSON text, lossless |
+| `file.toJSON()` | the file as a plain object (`JSON.stringify(file)` works) |
+| `file.header` | the `header` object |
+| `file.nodeCount` | number of entries in `data` |
+| `file.validate()` | a `ValidationReport` against the file's own `schemas` |
+| `compose(layers, options?)` | the composed tree as a `ComposedNode` |
+| `validate(layers, options?)` | a `ValidationReport` over all layers and resolved imports |
+| `exportGlb(layers, options?)` | the composed model as binary glTF 2.0, a `Uint8Array` |
+| `fetchImports(layers, options?)` | a promise of a `Map` from import `uri` to file, for `options.imports` |
+| `init(input?)` | `@openbim/ifcx/web` only: loads the wasm module; await it once first |
+
+`layers` is one input or an array of them, weakest first. TypeScript
+declarations ship with the package.
+
+**Lossless round trip.** `write()` keeps key order, fields the draft does
+not define, `null` deletions and every number exactly as read. A plain
+object from `toJSON()` cannot promise that: JavaScript lists integer-like
+keys first and rounds integers beyond 2^53. Keep the `IfcxFile` and call
+`write()` to save a file.
+
+**Composed tree.** `compose` returns the artificial root (path `""`) over
+every root node. Each node is `{ path, attributes, children }`, the shape of
+upstream's `PostCompositionNode`, with `children` keyed by child name. Nodes
+shared through inheritance appear once per place they are used.
+
+**Imports.** Without `options.imports`, imports are not resolved: the layers'
+schemas and data are concatenated in order, as upstream's `Federate` does.
+With `options.imports` (an object or a `Map` from the exact import `uri` to
+a file), the layers become the imports of a synthetic main layer, as
+upstream's `ifcx compose` command builds it, and every import must be
+supplied. `integrity` values are checked against the supplied bytes. In
+upstream order an import overrides the layer that imports it, and a later
+layer overrides both. The WebAssembly module never touches the network or
+the filesystem.
+
+**Fetching imports.** `fetchImports(layers, options?)` collects them for
+you, in JavaScript: it reads each layer's `imports`, fetches every `uri`
+(recursively, each once, concurrently) and resolves to a `Map` keyed by
+the exact import `uri`, ready for `options.imports`.
+
+- `baseUrl`: what relative URIs of the given layers resolve against;
+  `location.href` by default in a browser. A fetched file's own imports
+  resolve against its URL.
+- `fetch`: the function that loads a URL, the global `fetch` by default.
+  Pass your own for credentials, a cache, a mirror, or Node files:
+  `{ fetch: async (url) => readFile(new URL(url)) }`. It may return a
+  `Response`, a `Uint8Array`, an `ArrayBuffer` or a string. Without a
+  `baseUrl` it receives a relative `uri` unchanged.
+- `imports`: files already at hand, never fetched again.
+- `signal`: an `AbortSignal` passed to every fetch.
+
+The in-memory map keys a file by its exact `uri`, as upstream's
+`InMemoryLayerProvider` does, so two different files imported under the
+same relative `uri` from different directories cannot both be supplied;
+the first one fetched is used. Anything that cannot be fetched rejects with
+an `IfcxError` with code `fetch`; `integrity` and import cycles are checked
+by `compose`, `validate` and `exportGlb`.
+
+**GLB export.** `exportGlb` writes the render scene of the composed tree:
+transformed, instanced meshes, lines and points with their materials, one
+glTF node per instance named by its IFCX path. The root node turns IFCX's
+Z-up into glTF's Y-up (`yUp: false` keeps Z-up) and carries the scene
+origin, so georeferenced models keep their coordinates
+(`originOnRoot: false` centres the model on the glTF origin instead).
+Geometry values that do not decode are left out. `options.imports` works
+as for `compose`.
+
+**Validation report.** `{ valid, failures }`, each failure
+`{ node, attribute, pointer, kind, message }`: the node path, the attribute
+id, an RFC 6901 pointer into the value (`""` for the value itself), a stable
+`kind` such as `missing-schema`, `type-mismatch`, `not-an-integer`,
+`not-an-option`, `missing-key`, `too-few-elements` or `too-many-elements`,
+and a human message.
+
+## Errors
+
+Every failure throws an `Error` with `name === "IfcxError"` and a stable
+`code`:
+
+| `code` | Meaning |
+| --- | --- |
+| `read` | not an IFCX file: invalid JSON or the wrong shape; the message gives line and column |
+| `write` | the file could not be written |
+| `layer` | imports could not be resolved: a missing file, an import cycle, an `integrity` mismatch |
+| `compose` | a reference cycle, or a reference to a node no layer defines |
+| `invalid-argument` | an argument of the wrong type, or no layers |
+| `glb` | the scene could not be written as GLB (over 4 GiB) |
+| `fetch` | `fetchImports` could not fetch an import, or got no file back |
+
+A code is never renamed or reused.
+
+## Building
+
+```sh
+cargo install wasm-bindgen-cli --version 0.2.128 --locked
+crates/openbim-ifcx-wasm/scripts/build-npm-pkg.sh    # builds pkg/, runs every check
+```
+
+The script binds one release build three times (`pkg/`, `pkg/bundler/`,
+`pkg/web/`), runs the Node suite, then `npm pack`s the package and checks
+each entry point from the tarball: Node `require` and `import`, a webpack
+bundle, and the `web` and bundler builds in headless Chrome, which parse,
+validate, compose, fetch imports and export GLB from the repository's
+fixtures. It finds Chrome through `CHROME_BIN`, `PATH` or a Playwright
+download; `IFCX_SKIP_BROWSER=1` skips the browser part with a warning.
+
+## License
+
+MIT, like the rest of `openbimrs/ifcx`.

package/bundler/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/bundler/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/bundler/openbim_ifcx_wasm.d.ts

@@ -0,0 +1,139 @@
+/* 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 * from "./fetch-imports.js";

package/bundler/openbim_ifcx_wasm.js

@@ -0,0 +1,10 @@
+/* @ts-self-types="./openbim_ifcx_wasm.d.ts" */
+import * as wasm from "./openbim_ifcx_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./openbim_ifcx_wasm_bg.js";
+
+__wbg_set_wasm(wasm);
+
+export {
+    IfcxFile, compose, exportGlb, validate
+} from "./openbim_ifcx_wasm_bg.js";
+export { fetchImports } from "./fetch-imports.js";