oxianjs 0.0.0-stage → 0.21.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oxian
+
+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/package.json

@@ -1,6 +1,28 @@
 {
   "name": "oxianjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.21.3",
+  "description": "Oxian owners and the in-process host",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AxionCompany/oxian-js.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    "./host": {
+      "types": "./src/host/index.d.ts",
+      "default": "./src/host/index.js"
+    },
+    "./owner": {
+      "types": "./src/owner/index.d.ts",
+      "default": "./src/owner/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ]
+}

package/src/host/host.d.ts

@@ -0,0 +1,5 @@
+import { type HostOptions, type OwnerHost, type ShardMap } from "./types.ts";
+/** Copies `owners` (owner id to shard id) into a map for this process's shard. */
+export declare function createShardMap(shard: string, owners: Readonly<Record<string, string>>): ShardMap;
+/** One process. It starts only the owners its shard map assigns here. */
+export declare function createOwnerHost(options: HostOptions): OwnerHost;

package/src/host/host.js

@@ -0,0 +1,84 @@
+import { createOwnerError } from "../owner/primitives.js";
+import { CONNECTION_BUDGET, } from "./types.js";
+/** Copies `owners` (owner id to shard id) into a map for this process's shard. */
+export function createShardMap(shard, owners) {
+    if (shard === "")
+        throw new TypeError("shard must be non-empty");
+    const assigned = new Map();
+    for (const [ownerId, shardId] of Object.entries(owners)) {
+        if (ownerId === "" || shardId === "") {
+            throw new TypeError("owner and shard ids must be non-empty");
+        }
+        assigned.set(ownerId, shardId);
+    }
+    return Object.freeze({
+        shard,
+        locate: (ownerId) => assigned.get(ownerId),
+    });
+}
+/** One process. It starts only the owners its shard map assigns here. */
+export function createOwnerHost(options) {
+    const { map } = options;
+    const budget = options.maxConnections ?? CONNECTION_BUDGET;
+    if (!Number.isSafeInteger(budget) ||
+        budget < 1 ||
+        budget > CONNECTION_BUDGET) {
+        throw new RangeError(`maxConnections must be from 1 to ${CONNECTION_BUDGET}`);
+    }
+    const running = new Map();
+    let connections = 0;
+    let closed = false;
+    function owns(ownerId) {
+        return map.locate(ownerId) === map.shard;
+    }
+    function open(ownerId, start) {
+        if (closed)
+            throw new Error("host is closed");
+        if (ownerId === "")
+            throw new TypeError("owner id must be non-empty");
+        if (!owns(ownerId)) {
+            throw createOwnerError("ownership_lost", "owner is not assigned to this host");
+        }
+        const existing = running.get(ownerId);
+        if (existing !== undefined)
+            return existing;
+        const started = start();
+        running.set(ownerId, started);
+        return started;
+    }
+    function connect() {
+        if (closed)
+            throw new Error("host is closed");
+        if (connections >= budget)
+            throw new Error("connection budget exceeded");
+        connections += 1;
+        let released = false;
+        return Object.freeze({
+            release() {
+                if (released)
+                    return;
+                released = true;
+                connections -= 1;
+            },
+        });
+    }
+    function snapshot() {
+        return Object.freeze({
+            shard: map.shard,
+            owners: Object.freeze([...running.keys()]),
+            connections,
+            budget,
+        });
+    }
+    return Object.freeze({
+        map,
+        budget,
+        open,
+        connect,
+        owns,
+        snapshot,
+        close() {
+            closed = true;
+        },
+    });
+}

package/src/host/index.d.ts

@@ -0,0 +1,3 @@
+export { createOwnerHost, createShardMap } from "./host.ts";
+export { CONNECTION_BUDGET } from "./types.ts";
+export type { HostOptions, HostSnapshot, OwnerConnection, OwnerHost, ShardMap, } from "./types.ts";

package/src/host/index.js

@@ -0,0 +1,2 @@
+export { createOwnerHost, createShardMap } from "./host.js";
+export { CONNECTION_BUDGET } from "./types.js";

package/src/host/types.d.ts

@@ -0,0 +1,46 @@
+/** How many connections one Cloud Run host may hold. */
+export declare const CONNECTION_BUDGET = 1000;
+/**
+ * A fixed assignment of owner ids to shards. One process is one shard.
+ * An id maps to one shard, so two processes cannot take the same owner.
+ */
+export type ShardMap = Readonly<{
+    shard: string;
+    /** The shard that owns `ownerId`, or undefined when this map does not know it. */
+    locate(ownerId: string): string | undefined;
+}>;
+export type HostOptions = Readonly<{
+    map: ShardMap;
+    /**
+     * Open connections this process accepts. Defaults to `CONNECTION_BUDGET`
+     * and cannot be higher.
+     */
+    maxConnections?: number;
+}>;
+/** One accepted connection. `release` is safe to call twice. */
+export type OwnerConnection = Readonly<{
+    release(): void;
+}>;
+export type HostSnapshot = Readonly<{
+    shard: string;
+    owners: readonly string[];
+    connections: number;
+    budget: number;
+}>;
+/** The owners assigned to this process, and the connections it still has room for. */
+export type OwnerHost = Readonly<{
+    readonly map: ShardMap;
+    readonly budget: number;
+    /**
+     * Starts `ownerId` when this shard owns it. `start` is not called otherwise,
+     * so the epoch does not move. Opening an id twice returns the first instance.
+     */
+    open<T>(ownerId: string, start: () => T): T;
+    /** Takes one connection. Throws when the budget is full. */
+    connect(): OwnerConnection;
+    /** True when this shard owns `ownerId`. */
+    owns(ownerId: string): boolean;
+    snapshot(): HostSnapshot;
+    /** Rejects later opens and connections. Does not stop owners already started. */
+    close(): void;
+}>;

package/src/host/types.js

@@ -0,0 +1,2 @@
+/** How many connections one Cloud Run host may hold. */
+export const CONNECTION_BUDGET = 1_000;

package/src/owner/index.d.ts

@@ -0,0 +1,6 @@
+export { createMemoryOwnerStore } from "./memory.ts";
+export type { MemoryOwnerStore, MemoryTables } from "./memory.ts";
+export { createOwner } from "./owner.ts";
+export { createCommandSession, createSnapshotSession, SNAPSHOT_IDLE_MS, SNAPSHOT_LIFETIME_MS, } from "./remote.ts";
+export { createOwnerError, isOwnerError } from "./primitives.ts";
+export type * from "./types.ts";

package/src/owner/index.js

@@ -0,0 +1,4 @@
+export { createMemoryOwnerStore } from "./memory.js";
+export { createOwner } from "./owner.js";
+export { createCommandSession, createSnapshotSession, SNAPSHOT_IDLE_MS, SNAPSHOT_LIFETIME_MS, } from "./remote.js";
+export { createOwnerError, isOwnerError } from "./primitives.js";

package/src/owner/memory.d.ts

@@ -0,0 +1,15 @@
+import type { JsonValue } from "../protocol/types.ts";
+import type { OwnerStore } from "./types.ts";
+/** Tables of JSON records, as seen by command handlers. */
+export type MemoryTables = Readonly<{
+    get(table: string, id: string): JsonValue | undefined;
+    put(table: string, id: string, value: JsonValue): void;
+    delete(table: string, id: string): void;
+    list(table: string): readonly (readonly [string, JsonValue])[];
+}>;
+export type MemoryOwnerStore = OwnerStore<MemoryTables> & Readonly<{
+    /** Reads committed state, outside any command. */
+    read(table: string, id: string): Promise<JsonValue | undefined>;
+}>;
+/** One owner's state in process memory: for tests, the browser and the in-process host. */
+export declare function createMemoryOwnerStore(): MemoryOwnerStore;

package/src/owner/memory.js

@@ -0,0 +1,216 @@
+import { createOwnerError, identityKey } from "./primitives.js";
+/** One owner's state in process memory: for tests, the browser and the in-process host. */
+export function createMemoryOwnerStore() {
+    const tables = new Map();
+    const receipts = new Map();
+    const changes = [];
+    let head = 0;
+    let alarm;
+    let alarmRevision = 0;
+    let epoch = 0;
+    let tail = Promise.resolve();
+    /** One transaction at a time; acquiring an epoch waits for the open one. */
+    function lock() {
+        let release;
+        const released = new Promise((resolve) => {
+            release = resolve;
+        });
+        const acquired = tail.then(() => release);
+        tail = tail.then(() => released);
+        return acquired;
+    }
+    function tableOf(name) {
+        let table = tables.get(name);
+        if (table === undefined) {
+            table = new Map();
+            tables.set(name, table);
+        }
+        return table;
+    }
+    async function begin(fenced) {
+        const release = await lock();
+        if (fenced !== epoch) {
+            release();
+            throw createOwnerError("ownership_lost", `epoch ${fenced} is no longer current (current ${epoch})`);
+        }
+        const undo = [];
+        let mark;
+        let finished = false;
+        const open = () => {
+            if (finished)
+                throw new TypeError("transaction has finished");
+        };
+        const write = (name, id, value) => {
+            open();
+            const table = tableOf(name);
+            const existed = table.has(id);
+            const previous = table.get(id);
+            undo.push(() => {
+                if (existed)
+                    table.set(id, previous);
+                else
+                    table.delete(id);
+            });
+            if (value === undefined)
+                table.delete(id);
+            else
+                table.set(id, structuredClone(value));
+        };
+        const unwind = (to) => {
+            while (undo.length > to)
+                undo.pop()();
+        };
+        const tx = Object.freeze({
+            get(name, id) {
+                open();
+                const value = tables.get(name)?.get(id);
+                return value === undefined ? undefined : structuredClone(value);
+            },
+            put: (name, id, value) => write(name, id, value),
+            delete: (name, id) => write(name, id),
+            list(name) {
+                open();
+                return [...(tables.get(name) ?? [])].map(([id, value]) => [id, structuredClone(value)]);
+            },
+        });
+        return Object.freeze({
+            tx,
+            savepoint() {
+                open();
+                mark = undo.length;
+                return Promise.resolve();
+            },
+            release() {
+                open();
+                mark = undefined;
+                return Promise.resolve();
+            },
+            rollbackToSavepoint() {
+                open();
+                if (mark === undefined)
+                    throw new TypeError("no open savepoint");
+                unwind(mark);
+                mark = undefined;
+                return Promise.resolve();
+            },
+            readReceipt(identity) {
+                open();
+                return Promise.resolve(copyReceipt(receipts.get(identityKey(identity))));
+            },
+            writeReceipt(receipt) {
+                open();
+                const key = identityKey(receipt.identity);
+                const previous = receipts.get(key);
+                undo.push(() => {
+                    if (previous === undefined)
+                        receipts.delete(key);
+                    else
+                        receipts.set(key, previous);
+                });
+                receipts.set(key, structuredClone(receipt));
+                return Promise.resolve();
+            },
+            append(body) {
+                open();
+                const seq = head + 1;
+                const previousHead = head;
+                undo.push(() => {
+                    head = previousHead;
+                    changes.pop();
+                });
+                head = seq;
+                changes.push(structuredClone(body));
+                return Promise.resolve(seq);
+            },
+            head() {
+                open();
+                return Promise.resolve(head);
+            },
+            setAlarm(at) {
+                open();
+                const previous = alarm;
+                const previousRevision = alarmRevision;
+                undo.push(() => {
+                    alarm = previous;
+                    alarmRevision = previousRevision;
+                });
+                if (at === undefined)
+                    alarm = undefined;
+                else {
+                    alarmRevision += 1;
+                    alarm = { at, revision: alarmRevision };
+                }
+                return Promise.resolve();
+            },
+            commit() {
+                open();
+                finished = true;
+                release();
+                return Promise.resolve();
+            },
+            rollback() {
+                open();
+                unwind(0);
+                finished = true;
+                release();
+                return Promise.resolve();
+            },
+        });
+    }
+    async function committed(read) {
+        const release = await lock();
+        try {
+            return read();
+        }
+        finally {
+            release();
+        }
+    }
+    return Object.freeze({
+        async acquire() {
+            return await committed(() => ++epoch);
+        },
+        begin,
+        readReceipt: (identity) => committed(() => copyReceipt(receipts.get(identityKey(identity)))),
+        readHead: () => committed(() => head),
+        readAlarm: () => committed(() => (alarm === undefined ? undefined : { ...alarm })),
+        readEpoch: () => committed(() => epoch),
+        beginSnapshot: () => committed(() => {
+            const copy = new Map();
+            for (const [name, table] of tables) {
+                const cloned = new Map();
+                for (const [id, value] of table) {
+                    cloned.set(id, structuredClone(value));
+                }
+                copy.set(name, cloned);
+            }
+            const tx = Object.freeze({
+                get(name, id) {
+                    const value = copy.get(name)?.get(id);
+                    return value === undefined ? undefined : structuredClone(value);
+                },
+                put() {
+                    throw new Error("snapshot is read-only");
+                },
+                delete() {
+                    throw new Error("snapshot is read-only");
+                },
+                list(name) {
+                    return [...(copy.get(name) ?? [])].map(([id, value]) => [id, structuredClone(value)]);
+                },
+            });
+            const snapshot = Object.freeze({
+                tx,
+                close: () => Promise.resolve(),
+            });
+            return snapshot;
+        }),
+        read: (table, id) => committed(() => {
+            const value = tables.get(table)?.get(id);
+            return value === undefined ? undefined : structuredClone(value);
+        }),
+    });
+}
+function copyReceipt(receipt) {
+    return receipt === undefined ? undefined : structuredClone(receipt);
+}

package/src/owner/owner.d.ts

@@ -0,0 +1,3 @@
+import type { Owner, OwnerOptions } from "./types.ts";
+/** Creates the single live owner of one store. */
+export declare function createOwner<Tx>(options: OwnerOptions<Tx>): Owner;