@adobe/ecs-persistence 0.0.0-stage → 0.0.1

package/src/program/program.ts

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component, Resource, type Schema } from "@adobe/ecs";
+import { persist } from "../persist.js";
+
+/** A key persisted, with its name and schema. */
+export type Persisted<K extends symbol = symbol> = { readonly name: string; readonly key: K; readonly schema: Schema };
+
+/** What the program persists: its components and resources by name. */
+export type Program = {
+    readonly components: ReadonlyMap<string, Persisted<Component.Key>>;
+    readonly resources: ReadonlyMap<string, Persisted<Resource.Key>>;
+};
+
+/** The keys of `declarations` with a `persist` trait by name, or why one can't persist: it isn't data, or a name is taken. */
+const namedIn = <K extends symbol>(declarations: ReadonlyMap<K, Component.Declared>, kind: string): ReadonlyMap<string, Persisted<K>> | string => {
+    const named = new Map<string, Persisted<K>>();
+    for (const [key, declaration] of declarations) {
+        const name: unknown = declaration[persist];
+        if (typeof name !== "string") continue;
+        if (declaration.type === undefined) return `The ${kind} persisted as "${name}" isn't data: it has no schema.`;
+        if (named.has(name)) return `Two ${kind}s are persisted as "${name}".`;
+        named.set(name, { name, key, schema: declaration.type });
+    }
+    return named;
+};
+
+/** What the program persists, as its modules registered so far declare it, or why it can't. */
+export const programOf = (): Program | string => {
+    const components = namedIn(Component.declarations(), "component");
+    if (typeof components === "string") return components;
+    const resources = namedIn(Resource.declarations(), "resource");
+    if (typeof resources === "string") return resources;
+    return { components, resources };
+};

package/src/selection/selection.ts

@@ -0,0 +1,96 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component, System, type Entity, type Resource, type World } from "@adobe/ecs";
+import type { Failure } from "../failure.js";
+import type { Contents } from "../program/contents.js";
+import type { Program } from "../program/program.js";
+
+/**
+ * Which entities a snapshot takes: those matching `with` and `not`, every one holding a persisted component by
+ * default; or `root` and every entity it owns, directly or through others, by persisted owner references.
+ */
+export type Selection =
+    | { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly resources?: boolean }
+    | { readonly root: Entity };
+
+/** Which tables a snapshot reads: those of its persisted components, matching `with` and `not`, and its resources. */
+type Reading = {
+    readonly components: readonly Component.Key[];
+    readonly with?: readonly Component.Key[];
+    readonly not?: readonly Component.Key[];
+    readonly resources?: readonly Resource.Key[];
+};
+
+/** A readonly system reading the tables `declaration` names. */
+const tablesSystemOf = (declaration: Reading) =>
+    System.create({ readonly: true, tables: declaration }, ({ tables }) => tables);
+
+/** The rows of `table` whose entities `keep` takes, as a table of their own. */
+const rowsOf = (table: World.Table, keep: (entity: number) => boolean): World.Table | null => {
+    const rows: number[] = [];
+    for (let row = 0; row < table.count; row++) if (keep(table.entities[row])) rows.push(row);
+    if (rows.length === table.count) return table;
+    if (rows.length === 0) return null;
+    const columns: { [key: symbol]: World.Table.Column } = {};
+    for (const key of Object.getOwnPropertySymbols(table.columns)) {
+        const column: World.Table.Column | undefined = Reflect.get(table.columns, key);
+        if (column === undefined) continue;
+        if (column.kind === "value") columns[key] = column;
+        else if (column.kind === "values") columns[key] = { kind: "values", values: rows.map(row => column.values[row]) };
+        else {
+            const { stride } = column;
+            const bytes = new Uint8Array(rows.length * stride);
+            rows.forEach((row, at) => bytes.set(column.bytes.subarray(row * stride, (row + 1) * stride), at * stride));
+            columns[key] = { kind: "bytes", bytes, stride };
+        }
+    }
+    return { count: rows.length, entities: Float64Array.from(rows, row => table.entities[row]), columns };
+};
+
+/** The entities `root` owns, itself included, through the owner references among `owners` in the tables. */
+const subtreeOf = (tables: readonly World.Table[], owners: readonly Component.Key[], root: Entity): ReadonlySet<number> => {
+    const children = new Map<number, number[]>();
+    for (const table of tables) {
+        for (const reference of owners) {
+            const key: symbol = reference;
+            const column: World.Table.Column | undefined = Reflect.get(table.columns, key);
+            if (column?.kind !== "bytes") continue;
+            const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+            for (let row = 0; row < table.count; row++) {
+                const owner = view.getFloat64(row * column.stride, true);
+                const list = children.get(owner);
+                if (list === undefined) children.set(owner, [table.entities[row]]);
+                else list.push(table.entities[row]);
+            }
+        }
+    }
+    const taken = new Set<number>([root]);
+    const waiting: number[] = [root];
+    for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
+        for (const child of children.get(next) ?? []) {
+            if (taken.has(child)) continue;
+            taken.add(child);
+            waiting.push(child);
+        }
+    }
+    return taken;
+};
+
+/** The persisted part of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
+export const select = async (world: World, program: Program, selection: Selection): Promise<Contents | Failure> => {
+    const components = [...program.components.values()];
+    const keys = components.map(persisted => persisted.key);
+    const subtree = "root" in selection;
+    const resources = subtree || selection.resources === false ? [] : [...program.resources.values()];
+    const declaration: Reading = subtree
+        ? { components: keys }
+        : { components: keys, with: selection.with ?? [], not: selection.not ?? [], resources: resources.map(persisted => persisted.key) };
+    const read = await world.run(tablesSystemOf(declaration)).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
+    if ("failure" in read) return read;
+    let tables = read.archetypes;
+    if (subtree) {
+        const owners = keys.filter(key => Component.declarations().get(key)?.reference === "owner");
+        const taken = subtreeOf(tables, owners, selection.root);
+        tables = tables.flatMap(table => rowsOf(table, entity => taken.has(entity)) ?? []);
+    }
+    return { components, tables, resources: resources.map(persisted => ({ persisted, value: read.resources[persisted.key] })) };
+};

package/src/snapshot.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { World } from "@adobe/ecs";
+import type { Failure } from "./failure.js";
+import { contents, type Contents } from "./program/contents.js";
+import { programOf } from "./program/program.js";
+import { select, type Selection } from "./selection/selection.js";
+
+/** The persisted part of some of a world's entities and its persisted resources, which `encode` and `spawn` take. */
+export type Snapshot = { readonly failure?: undefined; readonly [contents]: Contents };
+
+/**
+ * A snapshot of some of `world`'s entities, read on its thread: by default every entity holding a persisted
+ * component, and the persisted resources; with `with` and `not`, those a query matches, and the resources unless
+ * `resources` is false; with `root`, it and every entity it owns, through persisted owner references, without
+ * resources. Fails, as data, when the program's persisted keys can't be saved or the world can't be read.
+ */
+export const snapshot = async (input: { readonly world: World } & Selection): Promise<Snapshot | Failure> => {
+    const program = programOf();
+    if (typeof program === "string") return { failure: program };
+    const taken = await select(input.world, program, input);
+    return "failure" in taken ? taken : { [contents]: taken };
+};

package/src/spawn.ts

@@ -0,0 +1,60 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, type Entity, type World } from "@adobe/ecs";
+import type { Failure } from "./failure.js";
+import { contents } from "./program/contents.js";
+import type { Snapshot } from "./snapshot.js";
+
+/**
+ * What `spawn` made: how many of the snapshot's entities it didn't spawn, those owned by an entity outside it; and,
+ * unless asked not to, `entities`, each of the snapshot's entities to the one spawned for it, or null for one it
+ * didn't spawn.
+ */
+export type Spawned<Entities extends boolean = true> = { readonly failure?: undefined; readonly dropped: number }
+    & (Entities extends false ? {} : { readonly entities: ReadonlyMap<Entity, Entity | null> });
+
+const isTables = (value: unknown): value is readonly World.Table[] => Array.isArray(value) && value.every(table =>
+    typeof table === "object" && table !== null && typeof Reflect.get(table, "count") === "number" && Reflect.get(table, "entities") instanceof Float64Array
+    && typeof Reflect.get(table, "columns") === "object");
+
+const isKeyed = (value: unknown): value is { readonly [key: symbol]: unknown } => typeof value === "object" && value !== null;
+
+/** Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities. */
+const spawnTables = System.create({}, ({ commands }, input: { readonly tables: unknown; readonly resources: unknown }) => {
+    if (!isTables(input.tables) || !isKeyed(input.resources)) throw new Error("A snapshot holds tables and resources.");
+    return commands.spawnTables(input.tables, input.resources);
+});
+
+/**
+ * Spawns an entity in `world` for each of the snapshot's, with its persisted components, and sets the persisted
+ * resources, on the world's thread, as the world's references would leave them had the entities outside the snapshot
+ * despawned: each entity value naming one of the snapshot's names the one spawned for it; an entity owned, directly
+ * or through others, by an entity outside the snapshot isn't spawned, which the result counts; a weak reference to
+ * one is left out; and any other entity value naming one is `Entity.none`. With `entities: false`, the result leaves
+ * out its map of entities, which costs about 85 ms and 50 MB at a million. Fails, as data, for a column or
+ * resource that doesn't fit, spawning nothing.
+ */
+export function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities: false }): Promise<Spawned<false> | Failure>;
+export function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities?: true }): Promise<Spawned | Failure>;
+export async function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities?: boolean }): Promise<Spawned<boolean> | Failure> {
+    const { tables, resources } = input.snapshot[contents];
+    const values: { [key: symbol]: unknown } = {};
+    for (const { persisted, value } of resources) values[persisted.key] = value;
+    const spawned = await input.world.run(spawnTables, { tables, resources: values }).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
+    if ("failure" in spawned) return spawned;
+    if (input.entities === false) return { dropped: spawned.dropped };
+    return { dropped: spawned.dropped, entities: entitiesOf(tables, spawned.entities) };
+}
+
+/** Each of the tables' entities to the one spawned for it, or null for one that wasn't. */
+const entitiesOf = (tables: readonly World.Table[], spawned: readonly Float64Array[]): ReadonlyMap<Entity, Entity | null> => {
+    const entities = new Map<Entity, Entity | null>();
+    tables.forEach((table, t) => {
+        const made = spawned[t];
+        for (let row = 0; row < table.count; row++) {
+            // A table's entities and `spawnTables`' are entities, `Entity.none`, 0, for a row it didn't spawn.
+            const entity = made[row] as Entity;
+            entities.set(table.entities[row] as Entity, entity === 0 ? null : entity);
+        }
+    });
+    return entities;
+};

package/src/values/values.ts

@@ -0,0 +1,97 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "@adobe/ecs";
+
+// Values of components stored as values, strings and other data that isn't a fixed layout, as JSON their schema reads
+// back: a map as its entries, a set as its items, numbers JSON lacks as text, and a union's value as its member's
+// index and its JSON.
+
+/** A number JSON can't hold, as text: `NaN`, `Infinity`, `-Infinity` or `-0`. */
+const numberToJson = (value: number): number | string =>
+    Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value;
+
+const numberFromJson = (json: unknown): unknown => {
+    if (typeof json !== "string") return json;
+    switch (json) {
+        case "NaN": return NaN;
+        case "Infinity": return Infinity;
+        case "-Infinity": return -Infinity;
+        case "-0": return -0;
+        default: return json;
+    }
+};
+
+/** Whether a value is of the JSON kind a schema's values are, to pick a union's member. */
+const fits = (schema: Schema, value: unknown): boolean => {
+    if ("const" in schema) return Object.is(schema.const, value) || JSON.stringify(schema.const) === JSON.stringify(value);
+    if ("anyOf" in schema) return schema.anyOf.some(member => fits(member, value));
+    if ("allOf" in schema) return schema.allOf.every(member => fits(member, value));
+    if (!("type" in schema)) return true;
+    switch (schema.type) {
+        case "number": case "integer": return typeof value === "number";
+        case "string": return typeof value === "string";
+        case "boolean": return typeof value === "boolean";
+        case "null": return value === null;
+        case "array": return Array.isArray(value);
+        case "set": return value instanceof Set;
+        case "map": return value instanceof Map;
+        case "object": return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map);
+        default: return true;
+    }
+};
+
+/** A value of `schema` as JSON. */
+export const toJson = (schema: Schema, value: unknown): unknown => {
+    if ("anyOf" in schema) {
+        const index = schema.anyOf.findIndex(candidate => fits(candidate, value));
+        const member = schema.anyOf[index];
+        return member === undefined ? [-1, value] : [index, toJson(member, value)];
+    }
+    if (typeof value === "number") return numberToJson(value);
+    if (!("type" in schema)) return value;
+    switch (schema.type) {
+        case "array": return Array.isArray(value) ? value.map(item => toJson(schema.items, item)) : value;
+        case "set": return value instanceof Set ? Array.from(value, item => toJson(schema.items, item)) : value;
+        case "map": return value instanceof Map ? Array.from(value, ([key, item]) => [toJson(schema.keys, key), toJson(schema.values, item)]) : value;
+        case "object": {
+            if (typeof value !== "object" || value === null) return value;
+            const json: { [name: string]: unknown } = {};
+            for (const name of Object.keys(value)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(value, name);
+                if (item !== undefined) json[name] = field === undefined ? item : toJson(field, item);
+            }
+            return json;
+        }
+        default: return value;
+    }
+};
+
+/** A value of `schema` read back from its JSON. */
+export const fromJson = (schema: Schema, json: unknown): unknown => {
+    if ("anyOf" in schema) {
+        if (!Array.isArray(json) || typeof json[0] !== "number") return json;
+        const member = schema.anyOf[json[0]];
+        return member === undefined ? json[1] : fromJson(member, json[1]);
+    }
+    if ("const" in schema) return schema.const;
+    if (!("type" in schema)) return json;
+    switch (schema.type) {
+        case "number": case "integer": return numberFromJson(json);
+        case "array": return Array.isArray(json) ? json.map(item => fromJson(schema.items, item)) : json;
+        case "set": return Array.isArray(json) ? new Set(json.map(item => fromJson(schema.items, item))) : json;
+        case "map": return Array.isArray(json)
+            ? new Map(json.map(entry => Array.isArray(entry) ? [fromJson(schema.keys, entry[0]), fromJson(schema.values, entry[1])] : [entry, undefined]))
+            : json;
+        case "object": {
+            if (typeof json !== "object" || json === null || Array.isArray(json)) return json;
+            const value: { [name: string]: unknown } = {};
+            for (const name of Object.keys(json)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(json, name);
+                value[name] = field === undefined ? item : fromJson(field, item);
+            }
+            return value;
+        }
+        default: return json;
+    }
+};