@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/package-loader/isolated-table-gateway.test.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const SQLiteDB = require("better-sqlite3");
+const event_registry_1 = require("../data/orm/event-registry");
 const sql_data_source_1 = require("../data/orm/sql.data-source");
+const table_1 = require("../data/orm/table");
 const table_container_1 = require("../data/orm/table-container");
 const package_table_identity_1 = require("../data/package-table-identity");
 const table_definitions_table_1 = require("../data/table-definitions-table");
@@ -45,6 +47,9 @@ describe("isolated package table gateway", () => {
             stateId: recordId,
             count: 1,
         });
+        await expect(gateway.call(declaration, "count", [{ count: { $in: [1, 3] } }])).resolves.toBe(1);
+        await expect(gateway.call(declaration, "count", [{ count: { $in: [2] } }])).resolves.toBe(0);
+        await expect(gateway.call(declaration, "list", [{ count: { $gt: 0 } }])).rejects.toThrow("equality and $in filters only");
         await gateway.register(declaration);
         await expect(gateway.get(declaration, recordId)).resolves.toEqual({
             stateId: recordId,
@@ -73,6 +78,28 @@ describe("isolated package table gateway", () => {
         });
         await expect(gateway.get({ ...owner, packageId: (0, utils_1.newid)() }, (0, utils_1.newid)())).rejects.toThrow(/Undeclared isolated table/);
     });
+    test("unsupported filters fail even on empty tables or after a nonmatching condition", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const declaration = makeDeclaration();
+        await gateway.register(declaration);
+        for (const operation of ["list", "count", "findOne"]) {
+            await expect(gateway.call(declaration, operation, [{ count: { $gt: 0 } }])).rejects.toThrow("equality and $in filters only");
+        }
+        await gateway.save(declaration, { stateId: (0, utils_1.newid)(), count: 1 });
+        await expect(gateway.call(declaration, "list", [{ count: 2, stateId: { $ne: "missing" } }])).rejects.toThrow("equality and $in filters only");
+    });
+    test("memory table pages use the ORM's one-based page numbers", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const declaration = makeDeclaration();
+        await gateway.register(declaration);
+        const rows = [1, 2, 3].map((count) => ({ stateId: (0, utils_1.newid)(), count }));
+        for (const row of rows)
+            await gateway.save(declaration, row);
+        for (const page of [undefined, 0, 1]) {
+            await expect(gateway.call(declaration, "list", [{}, { page, pageSize: 2 }])).resolves.toEqual(rows.slice(0, 2));
+        }
+        await expect(gateway.call(declaration, "list", [{}, { page: 2, pageSize: 2 }])).resolves.toEqual(rows.slice(2));
+    });
     test("memory gateway preserves Date and binary fields without retaining references", async () => {
         const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
         const declaration = makeDeclaration({
@@ -118,6 +145,146 @@ describe("isolated package table gateway", () => {
         await expect(gateway.register(v1)).rejects.toThrow(/schema downgrade/);
         await expect(gateway.register(makeDeclaration({ tableName: 'Unsafe"; DROP TABLE State; --' }))).rejects.toThrow(/only letters, numbers, and underscores/);
     });
+    test("a rebuild that adds descriptive IR keys, or keys a newer SDK knows, keeps the table version", async () => {
+        const declaration = makeDeclaration({
+            versionNumber: 1,
+            fields: [
+                { name: "stateId", type: field_type_1.FieldType.id },
+                { name: "mode", type: field_type_1.FieldType.string },
+                { name: "where", type: field_type_1.FieldType.object },
+            ],
+        });
+        const tableId = (0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName);
+        const stored = {
+            tableId,
+            name: `${declaration.tableName}_${declaration.packageId}`,
+            metaData: {
+                tableId,
+                packageId: declaration.packageId,
+                name: declaration.tableName,
+                description: declaration.description,
+                primaryKeyName: declaration.primaryKeyName,
+                fields: declaration.fields,
+                versionNumber: 1,
+            },
+            versionNumber: 1,
+        };
+        const table = {
+            get: jest.fn(async (id) => (id === tableId ? stored : undefined)),
+            save: jest.fn(async (record) => record),
+        };
+        const registerTableDefinition = jest.fn();
+        const dataContext = {
+            tableContainer: { registerTableDefinition, getTable: jest.fn(() => table) },
+        };
+        const enriched = {
+            ...declaration,
+            fields: [
+                { name: "stateId", type: field_type_1.FieldType.id },
+                { name: "mode", type: field_type_1.FieldType.string, enumValues: ["on", "off"] },
+                {
+                    name: "where",
+                    type: field_type_1.FieldType.object,
+                    fields: [{ name: "city", type: field_type_1.FieldType.string }],
+                    future: true,
+                },
+            ],
+        };
+        await (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext).register(enriched);
+        // The stored definition stays until the table's version changes.
+        expect(table.save).not.toHaveBeenCalled();
+        expect(registerTableDefinition.mock.calls[0][0].metaData.fields).toEqual(declaration.fields);
+        // Every other change at the same version still needs a version bump.
+        await expect((0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext).register({
+            ...declaration,
+            fields: [
+                declaration.fields[0],
+                { name: "mode", type: field_type_1.FieldType.number },
+                declaration.fields[2],
+            ],
+        })).rejects.toThrow(/different schemas at version 1/);
+    });
+    test("switches a table between synced and local-only at a higher version, keeping its rows", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const synced = makeDeclaration({ versionNumber: 1 });
+        const rowId = (0, utils_1.newid)();
+        await gateway.register(synced);
+        await gateway.save(synced, { stateId: rowId, count: 1 });
+        // Like any schema change, the flag needs a version bump.
+        await expect(gateway.register({ ...synced, localOnly: true })).rejects.toThrow(/different schemas at version 1/);
+        const local = { ...synced, versionNumber: 2, localOnly: true };
+        await gateway.register(local);
+        await expect(gateway.get(local, rowId)).resolves.toEqual({ stateId: rowId, count: 1 });
+        const syncedAgain = { ...synced, versionNumber: 3 };
+        await gateway.register(syncedAgain);
+        await expect(gateway.get(syncedAgain, rowId)).resolves.toEqual({ stateId: rowId, count: 1 });
+    });
+    test.each([
+        { localOnly: false },
+        { localOnly: true },
+    ])("switches a stored localOnly=$localOnly table only at a higher version, preflighting the batch", async ({ localOnly, }) => {
+        const declaration = makeDeclaration({ versionNumber: 1, localOnly });
+        const tableId = (0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName);
+        const stored = {
+            tableId,
+            name: `${declaration.tableName}_${declaration.packageId}`,
+            metaData: {
+                tableId,
+                packageId: declaration.packageId,
+                name: declaration.tableName,
+                description: declaration.description,
+                primaryKeyName: declaration.primaryKeyName,
+                fields: declaration.fields,
+                versionNumber: 1,
+                ...(localOnly ? { localOnly: true } : {}),
+            },
+            versionNumber: 1,
+        };
+        const table = {
+            get: jest.fn(async (id) => (id === tableId ? stored : undefined)),
+            save: jest.fn(async (record) => record),
+        };
+        const registerTableDefinition = jest.fn();
+        const dataContext = {
+            tableContainer: { registerTableDefinition, getTable: jest.fn(() => table) },
+        };
+        const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext);
+        // Synced stored definitions omit the flag, even when the incoming declaration says false.
+        await gateway.register(declaration);
+        const registered = registerTableDefinition.mock.calls[0][0].metaData;
+        if (localOnly)
+            expect(registered.localOnly).toBe(true);
+        else
+            expect(registered).not.toHaveProperty("localOnly");
+        // The first gateway rejects from the declaration it holds; a new one, as after a restart,
+        // has only the stored definition to go on.
+        for (const candidate of [gateway, (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext)]) {
+            registerTableDefinition.mockClear();
+            table.save.mockClear();
+            const activate = jest.fn();
+            await expect(candidate.registerBatch([
+                makeDeclaration({ packageId: declaration.packageId, tableName: "NewState" }),
+                { ...declaration, localOnly: !localOnly },
+            ], activate)).rejects.toThrow(/different schemas at version 1/);
+            expect(table.save).not.toHaveBeenCalled();
+            expect(registerTableDefinition).not.toHaveBeenCalled();
+            expect(activate).not.toHaveBeenCalled();
+            await expect(candidate.get({ packageId: declaration.packageId, tableName: "NewState" }, (0, utils_1.newid)())).rejects.toThrow(/Undeclared isolated table/);
+        }
+        registerTableDefinition.mockClear();
+        await (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext).registerBatch([
+            { ...declaration, versionNumber: 2, localOnly: !localOnly },
+        ]);
+        const savedMetaData = table.save.mock.calls[0][0].metaData;
+        const switched = registerTableDefinition.mock.calls[0][0].metaData;
+        for (const metaData of [savedMetaData, switched]) {
+            expect(metaData.versionNumber).toBe(2);
+            if (localOnly)
+                expect(metaData).not.toHaveProperty("localOnly");
+            else
+                expect(metaData.localOnly).toBe(true);
+        }
+    });
     test("rejects a table batch without publishing declarations that came before the conflict", async () => {
         const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
         const first = makeDeclaration({ versionNumber: 1 });
@@ -269,6 +436,82 @@ describe("isolated package table gateway", () => {
         expect(handlers.size).toBe(0);
     });
 });
+describe("local-only isolated tables", () => {
+    test("reach the data source factory as local-only, here and on a device with only the synced schema", async () => {
+        const db = new SQLiteDB(":memory:");
+        const sql = {
+            async close() {
+                db.close();
+            },
+            async get(query, params = []) {
+                return db.prepare(query).get(params);
+            },
+            async all(query, params = []) {
+                return db.prepare(query).all(params);
+            },
+            async exec(query, params = []) {
+                return { changes: db.prepare(query).run(params).changes };
+            },
+        };
+        // Real tables also try to persist their definition through the user-context singleton,
+        // which this test doesn't set up; the gateway already saved it.
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        const declaration = makeDeclaration({ localOnly: true });
+        const fullName = `${declaration.tableName}_${declaration.packageId}`;
+        const factoryCalls = [];
+        // Two containers over one database: the second stands in for another device that has the
+        // synced TableDefinitions row but hasn't loaded the package.
+        // Builds tables the way DataContext does: the data source factory sees the metadata, which is
+        // where peers-device leaves local-only tables untracked.
+        const context = () => {
+            const dataContext = { dataContextId: (0, utils_1.newid)() };
+            const eventRegistry = new event_registry_1.EventRegistry(dataContext.dataContextId);
+            dataContext.tableContainer = new table_container_1.TableContainer((metaData, schema, TableClass) => {
+                factoryCalls.push({ name: (0, utils_1.getFullTableName)(metaData), localOnly: metaData.localOnly });
+                const dataSource = new sql_data_source_1.SQLDataSource(sql, metaData, schema);
+                return new (TableClass ?? table_1.Table)(metaData, { dataSource, eventRegistry, schema });
+            });
+            return dataContext;
+        };
+        try {
+            const writer = context();
+            const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(writer);
+            await gateway.register(declaration);
+            const received = [];
+            const unsubscribe = await gateway.subscribe(declaration, "dataChanged", (event) => {
+                received.push(event);
+            });
+            const stateId = (0, utils_1.newid)();
+            await gateway.save(declaration, { stateId, count: 1 });
+            await gateway.call(declaration, "update", [{ stateId, count: 2 }]);
+            await gateway.call(declaration, "delete", [stateId]);
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(received).toEqual([
+                { dataObject: { stateId, count: 1 }, op: "insert", source: "local" },
+                { dataObject: { stateId, count: 2 }, op: "update", source: "local" },
+                { dataObject: { stateId, count: 2 }, op: "delete", source: "local" },
+            ]);
+            unsubscribe();
+            await gateway.save(declaration, { stateId, count: 3 });
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(received).toHaveLength(3);
+            expect(factoryCalls).toContainEqual({ name: fullName, localOnly: true });
+            expect(writer.tableContainer.getLocalOnlyTableNames()).toContain(fullName);
+            const stored = await (0, table_definitions_table_1.TableDefinitions)(writer).get((0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName));
+            expect(stored?.metaData).toMatchObject({ localOnly: true });
+            const peer = context();
+            (0, table_definitions_table_1.TableDefinitions)(peer);
+            factoryCalls.length = 0;
+            expect(await peer.tableContainer.getFallbackTable(fullName)).toBeTruthy();
+            expect(factoryCalls).toContainEqual({ name: fullName, localOnly: true });
+            expect(peer.tableContainer.getLocalOnlyTableNames()).toContain(fullName);
+        }
+        finally {
+            warn.mockRestore();
+            db.close();
+        }
+    });
+});
 describe("guarded isolated schema activation", () => {
     test("memory bindings remain unchanged when activation rejects", async () => {
         const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();

package/dist/package-loader/package-loader.d.ts

@@ -7,7 +7,7 @@ import type { IConsumedContract, IRemoteContract, IRemoteContractConsumer } from
 import { type IPackage } from "../data/packages";
 import { type Observable } from "../observable";
 import type { IPeersPackage } from "../types/peers-package";
-import { type IIsolatedPackageRuntime } from "./isolated-runtime";
+import { type IIsolatedCallPrincipal, type IIsolatedPackageRuntime } from "./isolated-runtime";
 import { type IPackageRuntimeState, type PackageRuntimeStates, type PackageRuntimeStatus } from "./package-runtime-state";
 import "../contracts/system";
 /** Options for {@link PackageLoader.unloadPackage}. */
@@ -112,6 +112,13 @@ export declare class PackageLoader {
      */
     private recordLoadFailure;
     private dispatchToolFromProvider;
+    /** Project a legacy caller's declared tool reach and authority for advisory catalog listings. */
+    hostToolPrincipal(principal: IIsolatedCallPrincipal, packageId: string, target: {
+        contractId: string;
+        version: number;
+        providerPackageId: string;
+    }): IIsolatedCallPrincipal | undefined;
+    private selectHostToolProvider;
     /**
      * Return the active provider selected by this data context's trusted registry.
      *

package/dist/package-loader/package-loader.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageLoader = void 0;
 exports.setDefaultRequire = setDefaultRequire;
+const action_dispatch_1 = require("../contracts/action-dispatch");
 const contract_provider_router_1 = require("../contracts/contract-provider-router");
 const contract_proxy_1 = require("../contracts/contract-proxy");
 const contract_resolvers_1 = require("../contracts/contract-resolvers");
@@ -227,26 +228,7 @@ class PackageLoader {
             throw new Error("Strict delegated calls cannot target another device until authority transport is supported");
         if (target.dataContextId && target.dataContextId !== this.dataContext.dataContextId)
             throw new Error("Cross-context action dispatch is denied");
-        const own = this.contractRegistry
-            .getRegisteredProviderIds(target.contractId, target.version)
-            .includes(packageId);
-        const consume = this.hostConsumes
-            .get(packageId)
-            ?.find((c) => c.contractId === target.contractId && c.version === target.version);
-        if (!own && !consume)
-            throw new Error("Undeclared contract consumption");
-        if (own && target.providerPackageId && target.providerPackageId !== packageId && !consume)
-            throw new Error("Provider substitution is denied for package-owned targets");
-        const selected = own && (!target.providerPackageId || target.providerPackageId === packageId)
-            ? packageId
-            : consume
-                ? this.contractRegistry.selectProvider(consume)?.providerPackageId
-                : undefined;
-        if (!selected)
-            throw new Error("No declared contract provider is available");
-        if (target.providerPackageId && target.providerPackageId !== selected)
-            throw new Error("Provider substitution is denied");
-        const providerPackageId = selected;
+        const providerPackageId = this.selectHostToolProvider(packageId, target);
         const authority = this.isolatedRuntime?.actionDispatchPrincipal?.(context.authority, packageId, target) ??
             context.authority;
         const callContext = { ...context, authority, callerPackageId: packageId };
@@ -274,6 +256,43 @@ class PackageLoader {
             endpoint.dispose();
         }
     }
+    /** Project a legacy caller's declared tool reach and authority for advisory catalog listings. */
+    hostToolPrincipal(principal, packageId, target) {
+        if (!principal.userId || this.isolatedRuntime?.isInstalled(packageId))
+            return undefined;
+        try {
+            this.selectHostToolProvider(packageId, target);
+        }
+        catch {
+            return undefined;
+        }
+        return (this.isolatedRuntime?.actionDispatchPrincipal?.(principal, packageId, {
+            ...target,
+            toolName: "",
+        }) ?? (0, action_dispatch_1.narrowActionPrincipal)(principal, true));
+    }
+    selectHostToolProvider(packageId, target) {
+        const own = this.contractRegistry
+            .getRegisteredProviderIds(target.contractId, target.version)
+            .includes(packageId);
+        const consume = this.hostConsumes
+            .get(packageId)
+            ?.find((c) => c.contractId === target.contractId && c.version === target.version);
+        if (!own && !consume)
+            throw new Error("Undeclared contract consumption");
+        if (own && target.providerPackageId && target.providerPackageId !== packageId && !consume)
+            throw new Error("Provider substitution is denied for package-owned targets");
+        const selected = own && (!target.providerPackageId || target.providerPackageId === packageId)
+            ? packageId
+            : consume
+                ? this.contractRegistry.selectProvider(consume)?.providerPackageId
+                : undefined;
+        if (!selected)
+            throw new Error("No declared contract provider is available");
+        if (target.providerPackageId && target.providerPackageId !== selected)
+            throw new Error("Provider substitution is denied");
+        return selected;
+    }
     /**
      * Return the active provider selected by this data context's trusted registry.
      *

package/dist/package-loader/package-loader.test.js

@@ -60,6 +60,53 @@ const isolated_artifact_1 = require("./isolated-artifact");
 const isolated_runtime_1 = require("./isolated-runtime");
 const package_loader_1 = require("./package-loader");
 const consumedContracts = require("./resolve-consumed-contracts");
+test("legacy catalog projection follows the dispatcher's declarations and selected provider", async () => {
+    const context = { dataContextId: (0, utils_1.newid)() };
+    const loader = new package_loader_1.PackageLoader(context);
+    const caller = (0, utils_1.newid)();
+    const provider = (0, utils_1.newid)();
+    const other = (0, utils_1.newid)();
+    const contractId = (0, utils_1.newid)();
+    const definition = {
+        contractId,
+        version: 1,
+        name: "Target",
+        description: "",
+        tools: [],
+        tables: [],
+        observables: [],
+        events: [],
+    };
+    const principal = {
+        userId: (0, utils_1.newid)(),
+        userAccessLevel: 40,
+        callingToolAccessLevel: 20,
+    };
+    const target = { contractId, version: 1, providerPackageId: provider };
+    try {
+        await loader.catalogReady;
+        loader.contractRegistry.register(provider, definition);
+        loader.contractRegistry.register(other, definition);
+        expect(loader.hostToolPrincipal(principal, caller, target)).toBeUndefined();
+        loader.hostConsumes.set(caller, [
+            { contractId, version: 1, providerPackageIds: [provider] },
+        ]);
+        expect(loader.hostToolPrincipal(principal, caller, target)).toMatchObject({
+            assistantAccessLevel: 20,
+            strictActionScope: true,
+        });
+        expect(loader.hostToolPrincipal(principal, caller, { ...target, providerPackageId: other })).toBeUndefined();
+        expect(loader.hostToolPrincipal({ ...principal, userId: undefined }, caller, target)).toBeUndefined();
+        // A provider can reach its own contract without declaring a consume.
+        expect(loader.hostToolPrincipal(principal, provider, target)).toMatchObject({
+            assistantAccessLevel: 20,
+        });
+        expect(loader.hostToolPrincipal(principal, provider, { ...target, providerPackageId: other })).toBeUndefined();
+    }
+    finally {
+        await loader.dispose();
+    }
+});
 describe("host load invalidation", () => {
     it("retains legacy package identity and refuses system calls before forwarding", async () => {
         const packageId = (0, utils_1.newid)();

package/dist/peer-id.d.ts

@@ -0,0 +1,25 @@
+/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
+export declare function cryptoRandomString(length: number): string;
+/**
+ * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
+ * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
+ */
+export declare function newid(): string;
+/** Lexicographic lower bound for valid peer ids (epoch). */
+export declare const MIN_ID: string;
+/** Lexicographic upper bound for valid peer ids (far future). */
+export declare const MAX_ID: string;
+/**
+ * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
+ * @param id Candidate id (coerced to string)
+ */
+export declare function isid(id: any): boolean;
+/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
+export declare function idTime(id: string): number;
+/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
+export declare function idDate(id: string): Date;
+/**
+ * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
+ * @param id A 25-character peer id from {@link newid}
+ */
+export declare function idRandNums(id: string): [number, number];

package/dist/peer-id.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ID = exports.MIN_ID = void 0;
+exports.cryptoRandomString = cryptoRandomString;
+exports.newid = newid;
+exports.isid = isid;
+exports.idTime = idTime;
+exports.idDate = idDate;
+exports.idRandNums = idRandNums;
+/**
+ * Peer ids: 25 base-36 characters, a 10-character time prefix plus a 15-character random suffix.
+ *
+ * Kept apart from `utils.ts` so code that only needs ids (such as zod schemas inside an isolated
+ * package) doesn't load lodash.
+ */
+const nacl = require("tweetnacl");
+/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
+function cryptoRandomString(length) {
+    let s = "";
+    let r = nacl.randomBytes(length + 6);
+    let i = 0;
+    while (s.length < length) {
+        if (i >= r.length) {
+            r = nacl.randomBytes(length - s.length);
+            i = 0;
+        }
+        const n = r[i];
+        i++;
+        if (n >= 252) {
+            // we don't want to bias the characters generated so only consider the range of numbers that spread evenly between factors of 36
+            // we exclude 252, 253, 254, and 255 because it would bias towards '0', '1', '2', and '3' respectively
+            continue;
+        }
+        s += (n % 36).toString(36);
+    }
+    return s.substring(0, length);
+}
+/**
+ * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
+ * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
+ */
+function newid() {
+    // modeled after mongo ids, timestamp + counter + random but we're going to skip counter and have bigger random
+    // people can switch to using a counter + random later if they want (or do something else with the random part).
+    // This id is going to be a 128 bit number so it fits naturally into memory.
+    // 2 ** 128 ~= 3.4e38 is the maximum it can be
+    // For efficient transmission, storage, presentation, and usage we're going to represent this number with base 36 [0-9a-z]
+    // (3.4e38).toString(36) == "f55n5nmuuaw00000000000000", this is our max in base 36, 25 characters
+    // Date.now() =~ 1625282091498
+    // but we're dealing in base 36 not base 10
+    // (1625282091498).toString(36) == "kqn6zrvu" (length 8)
+    // Number.parseInt("zzzzzzzz", 36) == 2821109907455 == year 2059.  Way too soon so going up to 9 characters
+    // Number.parseInt("zzzzzzzzz", 36) == 101559956668415 == year 5188.
+    // but the max size of 9 left most can only be "f55n5nmuu" == 42720753566838 == year 3323.  That could still work but only ~ 1300 years
+    // that leaves 16 characters to represent a random number to prevent collisions each millisecond, 36 ** 16 ~= 8e24
+    // Allocating one more character to the time and one less to the random number to avoid hitting max time in any conceivable future
+    // now our max time is new Date(Number.parseInt('f55n5nmuua',36)) == +050705-08-09T23:40:06.178Z. 50k years from now.
+    // We still have 15 chars for our random number. 36 ** 15 ~= 2e23
+    // That is still a very large number and the chance of a collision should be so small as to be effectively globally unique
+    // and certainly unique in any group's database.
+    const time = Date.now().toString(36).padStart(10, "0"); // e.g: "00kq6xh45f", length == 10
+    return time + cryptoRandomString(15);
+}
+/** Lexicographic lower bound for valid peer ids (epoch). */
+exports.MIN_ID = "0".repeat(25); // 1970
+/** Lexicographic upper bound for valid peer ids (far future). */
+exports.MAX_ID = `f55n5nmuua${"z".repeat(15)}`; // 50k years from now
+/**
+ * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
+ * @param id Candidate id (coerced to string)
+ */
+function isid(id) {
+    id = String(id);
+    const idMatch = Boolean(/^[0-9a-z]{25}$/i.exec(id));
+    if (idMatch) {
+        // only consider ids valid if they are less than current time (with 5 min buffer)
+        // This is to prevent people from making ids with times in the future to get them to always show up as the "newest" item and/or prematurely claim ids
+        return idTime(id) < Date.now() + 300000;
+    }
+    return false;
+}
+/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
+function idTime(id) {
+    const time36 = id.substr(0, 10);
+    return Number.parseInt(time36, 36);
+}
+/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
+function idDate(id) {
+    return new Date(idTime(id));
+}
+/**
+ * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
+ * @param id A 25-character peer id from {@link newid}
+ */
+function idRandNums(id) {
+    const numPart1 = id.substr(10, 8);
+    const numPart2 = id.substr(18, 7);
+    return [Number.parseInt(numPart1, 36), Number.parseInt(numPart2, 36)];
+}

package/dist/serial-json.compat.test.d.ts

@@ -0,0 +1 @@
+export {};