@openbim/ifcx 0.1.0 → 0.2.1

package/README.md

@@ -5,9 +5,16 @@ 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`, a CommonJS build for Node 18 and later.
-Browser bundling works in principle (the crate builds for
-`wasm32-unknown-unknown`) but has no tested recipe yet.
+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.
+
+Try it in the browser: the [viewer](https://openbimrs.github.io/ifcx/viewer/)
+composes a file with this package and shows the GLB with three.js, on
+desktop and on phones. The [documentation](https://openbimrs.github.io/ifcx/)
+has a [JavaScript guide](https://openbimrs.github.io/ifcx/guide/javascript)
+and the [API reference](https://openbimrs.github.io/ifcx/reference/crates/openbim-ifcx-wasm).
 
 Targets the `ifcx_alpha` draft of buildingSMART's IFC5. IFCX is still a
 moving draft; see the
@@ -19,12 +26,26 @@ moving draft; see the
 npm install @openbim/ifcx
 ```
 
-## Example
+## 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 } = require("node:fs");
-const { writeFileSync } = require("node:fs");
-const { IfcxFile, compose, exportGlb } = require("@openbim/ifcx");
+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
@@ -44,6 +65,39 @@ console.log(Object.keys(tree.children)); // the root nodes
 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 |
@@ -57,6 +111,8 @@ writeFileSync("model.glb", exportGlb([model, readFileSync("overlay.ifcx")]));
 | `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.
@@ -79,8 +135,31 @@ 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. Nothing is fetched from the network or the
-filesystem.
+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
@@ -111,6 +190,7 @@ Every failure throws an `Error` with `name === "IfcxError"` and a stable
 | `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.
 
@@ -118,9 +198,17 @@ A code is never renamed or reused.
 
 ```sh
 cargo install wasm-bindgen-cli --version 0.2.128 --locked
-crates/openbim-ifcx-wasm/scripts/build-node-pkg.sh   # builds pkg/ and runs the Node suite
+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";