@matter/nodejs 0.16.6-alpha.0-20260121-bc6d62766 → 0.16.6

package/src/storage/sqlite/SqliteUtil.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SqliteStorageError } from "./SqliteStorageError.js";
+
+/**
+ * Build string context path from contexts[]
+ * @param contexts Contexts
+ * @returns `.` joined context path
+ */
+export function buildContextPath(contexts: string[]) {
+    for (const ctx of contexts) {
+        if (ctx.trim().length <= 0 || ctx.includes(".")) {
+            throw new SqliteStorageError(
+                "build",
+                `{${contexts.join(",")}}`,
+                "Context must not be an empty and not contain dots.",
+            );
+        }
+    }
+    return contexts.join(".");
+}
+
+/**
+ * Build Context & Key pair
+ * @param contexts Contexts
+ * @param key Key
+ */
+export function buildContextKeyPair(contexts: string[], key: string) {
+    return {
+        context: buildContextPath(contexts),
+        key: buildKey(key),
+    };
+}
+
+/**
+ * Build Context & Key *log* path
+ */
+export function buildContextKeyLog(contexts: string[], key: string) {
+    return `${buildContextPath(contexts)}$${key}`; // use in log only
+}
+
+/**
+ * Build key (just verification)
+ */
+export function buildKey(key: string) {
+    if (key.trim().length <= 0) {
+        throw new SqliteStorageError("build", key, "Key must not be an empty string.");
+    }
+    return key;
+}
+
+/**
+ * Escape string for Glob
+ */
+export function escapeGlob(value: string) {
+    return value.replace(/[*[?]/g, "[$&]");
+}

package/src/storage/sqlite/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { PlatformSqlite } from "./platform/PlatformSqlite.js";
+export { SqliteStorage } from "./SqliteStorage.js";
+export { SqliteStorageError } from "./SqliteStorageError.js";
+export type { DatabaseCreator, DatabaseLike } from "./SqliteTypes.js";

package/src/storage/sqlite/platform/BunSqlite.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SqliteStorage } from "../SqliteStorage.js";
+// @ts-expect-error - bun:sqlite is only available in Bun runtime
+import { Database } from "bun:sqlite";
+// @ts-expect-error - Bun is only available in Bun runtime
+import Bun from "bun";
+
+/**
+ * `StorageSqliteDisk` for Bun
+ *
+ * DO NOT IMPORT DIRECTLY
+ * (should import `PlatformSqlite.js`)
+ */
+export class BunSqlite extends SqliteStorage {
+    constructor(path: string | null, clear = false) {
+        super({
+            databaseCreator: path =>
+                new Database(path, {
+                    strict: true,
+                    create: true,
+                }),
+            path,
+            clear,
+        });
+    }
+
+    override async clear(completely?: boolean) {
+        await super.clear();
+        if (completely ?? false) {
+            this.close();
+            await Bun.file(this.dbPath).delete();
+            this.isInitialized = false;
+        }
+    }
+}

package/src/storage/sqlite/platform/NodeJsSqlite.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { rm } from "node:fs/promises";
+import { DatabaseSync } from "node:sqlite";
+
+import { SqliteStorage } from "../SqliteStorage.js";
+import { DatabaseLike } from "../SqliteTypes.js";
+
+/**
+ * `StorageSqliteDisk` for Node.js
+ *
+ * DO NOT IMPORT DIRECTLY
+ * (should import `PlatformSqlite.js`)
+ */
+export class NodeJsSqlite extends SqliteStorage {
+    constructor(path: string | null, clear = false) {
+        super({
+            databaseCreator: path => new DatabaseSync(path) as DatabaseLike,
+            path,
+            clear,
+        });
+    }
+
+    override async clear(completely?: boolean) {
+        await super.clear();
+        if (completely ?? false) {
+            this.close();
+            await rm(this.dbPath, { force: true });
+            this.isInitialized = false;
+        }
+    }
+}

package/src/storage/sqlite/platform/PlatformSqlite.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isBunjs } from "#util/runtimeChecks.js";
+import type { SqliteStorage } from "../SqliteStorage.js";
+
+/**
+ * Create platform-specific SQLite storage
+ *
+ * Automatically detects runtime (Bun or Node.js) and returns appropriate implementation.
+ */
+export async function PlatformSqlite(path: string | null, clear = false): Promise<SqliteStorage> {
+    const isBun = isBunjs();
+
+    // Node.js is the primary target
+    if (!isBun) {
+        const module = await import("./NodeJsSqlite.js");
+        const NodeJsSqlite = findDefaultExport(module, "NodeJsSqlite");
+        return new NodeJsSqlite(path, clear);
+    }
+
+    // Bun runtime fallback
+    const module = await import("./BunSqlite.js");
+    const BunSqlite = findDefaultExport(module, "BunSqlite");
+    return new BunSqlite(path, clear);
+}
+
+/**
+ * Find default export from dynamically imported module.
+ *
+ * Handles both ESM and CJS module formats when using `await import()`:
+ *
+ * - **ESM**: `{ ExportName: [value] }`
+ * - **CJS (wrapped)**: `{ default: { ExportName: [value] } }`
+ * - **CJS (direct)**: `{ default: [value] }`
+ *
+ * @param moduleLike The imported module object
+ * @param name The export name to find
+ * @returns The exported value
+ *
+ * @example
+ * ```typescript
+ * const module = await import("./NodeJsSqlite.js")
+ * const NodeJsSqlite = findDefaultExport(module, "NodeJsSqlite")
+ * new NodeJsSqlite(path)
+ * ```
+ */
+function findDefaultExport<T, N extends keyof T>(moduleLike: T, name: N): T[N] {
+    return moduleLike[name] || (moduleLike as any).default?.[name] || (moduleLike as any).default;
+}

package/src/util/runtimeChecks.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Some utilities for checking runtime feature.
+
+/**
+ * Check runtime is bun.js
+ */
+export function isBunjs() {
+    return process.versions.bun != null;
+}
+
+/**
+ * Check Node.js's runtime supports sqlite.
+ */
+export function supportsSqlite() {
+    const nodeVersion = process.versions.node;
+    if (!nodeVersion.includes(".")) {
+        return false;
+    }
+    const prefixPart = nodeVersion.substring(0, nodeVersion.indexOf("."));
+
+    const majorNum = Number(prefixPart);
+    if (Number.isNaN(majorNum)) {
+        return false;
+    }
+    // Don't need to check minor version because of minimum requirement version.
+    return majorNum >= 22;
+}

package/dist/cjs/storage/StorageBackendDisk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StorageBackendDisk.d.ts","sourceRoot":"","sources":["../../../src/storage/StorageBackendDisk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,KAAK,EAKL,OAAO,EAEP,qBAAqB,EAExB,MAAM,UAAU,CAAC;AAmBlB,qBAAa,kBAAmB,SAAQ,OAAO;;IAG3C,SAAS,CAAC,aAAa,UAAS;gBAIpB,IAAI,EAAE,MAAM,EAAE,KAAK,UAAQ;IAMvC,IAAI,WAAW,YAEd;IAEK,UAAU;IA0DV,KAAK;IAKX,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAInB,KAAK;IAOX,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAiB,UAAQ;IAY/D,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM;IAWhC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/D,GAAG,CAAC,CAAC,SAAS,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAkB7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC;IAIlF,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IACjF,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoG/E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM;IAW5C,yEAAyE;IACnE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE;IAKvB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE;IAmB/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAKhC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE;CA0BpC"}

package/dist/cjs/storage/StorageBackendJsonFile.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StorageBackendJsonFile.d.ts","sourceRoot":"","sources":["../../../src/storage/StorageBackendJsonFile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAqB,oBAAoB,EAAgB,qBAAqB,EAAgB,MAAM,UAAU,CAAC;AAItH,qBAAa,sBAAuB,SAAQ,oBAAoB;IAWhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAVjC,2GAA2G;IAC3G,MAAM,CAAC,WAAW,8BAAe;IACjC,SAAS,gBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;IACF,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAC,CAAa;gBAET,IAAI,EAAE,MAAM;WAInB,MAAM,CAAC,IAAI,EAAE,MAAM;IAMhC,UAAU;IAcnB,OAAO,CAAC,aAAa;IASZ,GAAG,CACR,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAC3D,KAAK,CAAC,EAAE,qBAAqB,GAC9B,IAAI;IAKE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK7C,KAAK,IAAI,IAAI;YAKR,MAAM;IAcL,KAAK;IAQpB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,QAAQ;CAGnB"}

package/dist/esm/storage/StorageBackendDisk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StorageBackendDisk.d.ts","sourceRoot":"","sources":["../../../src/storage/StorageBackendDisk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,KAAK,EAKL,OAAO,EAEP,qBAAqB,EAExB,MAAM,UAAU,CAAC;AAmBlB,qBAAa,kBAAmB,SAAQ,OAAO;;IAG3C,SAAS,CAAC,aAAa,UAAS;gBAIpB,IAAI,EAAE,MAAM,EAAE,KAAK,UAAQ;IAMvC,IAAI,WAAW,YAEd;IAEK,UAAU;IA0DV,KAAK;IAKX,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAInB,KAAK;IAOX,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAiB,UAAQ;IAY/D,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM;IAWhC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/D,GAAG,CAAC,CAAC,SAAS,qBAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAkB7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC;IAIlF,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IACjF,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoG/E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM;IAW5C,yEAAyE;IACnE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE;IAKvB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE;IAmB/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAKhC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE;CA0BpC"}

package/dist/esm/storage/StorageBackendJsonFile.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StorageBackendJsonFile.d.ts","sourceRoot":"","sources":["../../../src/storage/StorageBackendJsonFile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAqB,oBAAoB,EAAgB,qBAAqB,EAAgB,MAAM,UAAU,CAAC;AAItH,qBAAa,sBAAuB,SAAQ,oBAAoB;IAWhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAVjC,2GAA2G;IAC3G,MAAM,CAAC,WAAW,8BAAe;IACjC,SAAS,gBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;IACF,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAC,CAAa;gBAET,IAAI,EAAE,MAAM;WAInB,MAAM,CAAC,IAAI,EAAE,MAAM;IAMhC,UAAU;IAcnB,OAAO,CAAC,aAAa;IASZ,GAAG,CACR,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAC3D,KAAK,CAAC,EAAE,qBAAqB,GAC9B,IAAI;IAKE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK7C,KAAK,IAAI,IAAI;YAKR,MAAM;IAcL,KAAK;IAQpB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,QAAQ;CAGnB"}