@adobe/ecs-persistence 0.0.1 → 0.1.1

package/dist/index.js

@@ -1,28 +1,18 @@
-import { Component, Resource, System } from "@adobe/ecs";
-//#region src/persist.ts
+import { Component, Index, Resource, System } from "@adobe/ecs";
+//#region src/program/program.ts
 /**
-* The trait marking a component or resource to persist, its value the stable name saved data names it by: unlike its
-* key's id, the name stays the same across versions and moves of its module. Not on a derived component, which its
-* rule derives again once its entity is loaded.
+* The keys of `declarations` with the trait `by`, by the name it gives each, or why one can't be saved: the trait's
+* value isn't a string, or the key isn't data, is derived, or has a name another has.
 */
-var persist = Symbol();
-declare$(persist, "trait");
-function declare$(key, kind, declaration) {
-	(globalThis[Symbol.for("@adobe/ecs/declarations@1")] ??= /* @__PURE__ */ new Map()).set(key, {
-		kind,
-		declaration
-	});
-}
-//#endregion
-//#region src/program/program.ts
-/** 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. */
-var namedIn = (declarations, kind) => {
+const namedIn = (declarations, kind, by) => {
 	const named = /* @__PURE__ */ new Map();
 	for (const [key, declaration] of declarations) {
-		const name = declaration[persist];
-		if (typeof name !== "string") continue;
-		if (declaration.type === void 0) 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}".`;
+		const name = Reflect.get(declaration, by);
+		if (name === void 0) continue;
+		if (typeof name !== "string") return `A ${kind}'s value of the trait isn't a name: ${String(name)}.`;
+		if (declaration.type === void 0) return `The ${kind} the trait names "${name}" isn't data: it has no schema.`;
+		if (declaration.derived === true) return `The ${kind} the trait names "${name}" is derived, which its rule derives again once its entity is loaded.`;
+		if (named.has(name)) return `The trait names two ${kind}s "${name}".`;
 		named.set(name, {
 			name,
 			key,
@@ -31,13 +21,15 @@ var namedIn = (declarations, kind) => {
 	}
 	return named;
 };
-/** What the program persists, as its modules registered so far declare it, or why it can't. */
-var programOf = () => {
-	const components = namedIn(Component.declarations(), "component");
+/** What the trait `by` covers, as the modules registered so far declare it, or why it can't be saved. */
+const programOf = (by) => {
+	if (typeof by !== "symbol") return "`by` is the key of the trait to save by, a symbol.";
+	const components = namedIn(Component.declarations(), "component", by);
 	if (typeof components === "string") return components;
-	const resources = namedIn(Resource.declarations(), "resource");
+	const resources = namedIn(Resource.declarations(), "resource", by);
 	if (typeof resources === "string") return resources;
 	return {
+		by,
 		components,
 		resources
 	};
@@ -45,8 +37,8 @@ var programOf = () => {
 //#endregion
 //#region src/values/values.ts
 /** A number JSON can't hold, as text: `NaN`, `Infinity`, `-Infinity` or `-0`. */
-var numberToJson = (value) => Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value;
-var numberFromJson = (json) => {
+const numberToJson = (value) => Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value;
+const numberFromJson = (json) => {
 	if (typeof json !== "string") return json;
 	switch (json) {
 		case "NaN": return NaN;
@@ -57,7 +49,7 @@ var numberFromJson = (json) => {
 	}
 };
 /** Whether a value is of the JSON kind a schema's values are, to pick a union's member. */
-var fits = (schema, value) => {
+const fits = (schema, value) => {
 	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));
@@ -76,7 +68,7 @@ var fits = (schema, value) => {
 	}
 };
 /** A value of `schema` as JSON. */
-var toJson = (schema, value) => {
+const toJson = (schema, value) => {
 	if ("anyOf" in schema) {
 		const index = schema.anyOf.findIndex((candidate) => fits(candidate, value));
 		const member = schema.anyOf[index];
@@ -102,7 +94,7 @@ var toJson = (schema, value) => {
 	}
 };
 /** A value of `schema` read back from its JSON. */
-var fromJson = (schema, json) => {
+const fromJson = (schema, json) => {
 	if ("anyOf" in schema) {
 		if (!Array.isArray(json) || typeof json[0] !== "number") return json;
 		const member = schema.anyOf[json[0]];
@@ -140,19 +132,19 @@ var fromJson = (schema, json) => {
 *   layout holds them, and a column of values as JSON text.
 * A loader views the blocks of bytes where they are, in the buffer it's given.
 */
-var magic = [
+const magic = [
 	69,
 	67,
 	83,
 	80
 ];
-var version = 1;
-var prefix = 16;
-var aligned = (offset) => Math.ceil(offset / 8) * 8;
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
+const version = 1;
+const prefix = 16;
+const aligned = (offset) => Math.ceil(offset / 8) * 8;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
 /** A snapshot's contents as bytes. */
-var encodeContents = (snapshot) => {
+const encodeContents = (snapshot) => {
 	const blocks = [];
 	let offset = 0;
 	/** Places a block, returning its offset from the first block. */
@@ -224,9 +216,9 @@ var encodeContents = (snapshot) => {
 	}
 	return bytes;
 };
-var isObject = (value) => typeof value === "object" && value !== null;
+const isObject = (value) => typeof value === "object" && value !== null;
 /** The header's JSON, checked enough to read it without casts, or null. */
-var headerOf = (json) => {
+const headerOf = (json) => {
 	if (!isObject(json)) return null;
 	const components = Reflect.get(json, "components");
 	const resources = Reflect.get(json, "resources");
@@ -254,13 +246,13 @@ var headerOf = (json) => {
 	return json;
 };
 /** Whether two schemas are the same, by their JSON in their properties' order, which places a struct's fields. */
-var sameSchema = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const sameSchema = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /**
-* The snapshot contents `bytes` holds, its components and resources by name as this program persists them, its blocks of
-* bytes viewed where they are; or why it can't be read: it isn't one, or names what this program doesn't persist, or
-* persists with another schema.
+* The snapshot contents `bytes` holds, its components and resources by the names the trait `by` gives them, its blocks
+* of bytes viewed where they are; or why it can't be read: it isn't one, or names what the trait doesn't cover, or
+* covers with another schema.
 */
-var decodeContents = (bytes) => {
+const decodeContents = (bytes, by) => {
 	if (bytes.byteLength < prefix || magic.some((byte, at) => bytes[at] !== byte)) return { failure: "These bytes aren't a snapshot." };
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 	const found = view.getUint32(4, true);
@@ -274,19 +266,19 @@ var decodeContents = (bytes) => {
 	}
 	const header = headerOf(json);
 	if (header === null) return { failure: "This snapshot's header isn't one this package writes." };
-	const program = programOf();
+	const program = programOf(by);
 	if (typeof program === "string") return { failure: program };
 	const components = [];
 	for (const { name, schema } of header.components) {
 		const persisted = program.components.get(name);
-		if (persisted === void 0) return { failure: `This snapshot holds component "${name}", which this program doesn't persist.` };
+		if (persisted === void 0) return { failure: `This snapshot holds component "${name}", which the trait doesn't cover.` };
 		if (!sameSchema(persisted.schema, schema)) return { failure: `Component "${name}" has another schema here than in this snapshot.` };
 		components.push(persisted);
 	}
 	const resources = [];
 	for (const { name, schema, value } of header.resources) {
 		const persisted = program.resources.get(name);
-		if (persisted === void 0) return { failure: `This snapshot holds resource "${name}", which this program doesn't persist.` };
+		if (persisted === void 0) return { failure: `This snapshot holds resource "${name}", which the trait doesn't cover.` };
 		if (!sameSchema(persisted.schema, schema)) return { failure: `Resource "${name}" has another schema here than in this snapshot.` };
 		resources.push({
 			persisted,
@@ -335,6 +327,7 @@ var decodeContents = (bytes) => {
 		});
 	}
 	return {
+		by: program.by,
 		components,
 		tables,
 		resources
@@ -343,34 +336,34 @@ var decodeContents = (bytes) => {
 //#endregion
 //#region src/program/contents.ts
 /** Where a snapshot holds what it holds, a key only this package uses. */
-var contents = Symbol("snapshot contents");
+const contents = Symbol("snapshot contents");
 //#endregion
 //#region src/decode.ts
 /**
-* The snapshot `bytes` holds, its columns of bytes viewed where they are in `bytes`, copied once only when `bytes`
-* doesn't start at a multiple of 8; or why it can't be read: it isn't one, or names a component or resource this
-* program doesn't persist, or persists with another schema.
+* The snapshot `bytes` holds, read by the trait `by`, its columns of bytes viewed where they are in `bytes`, copied once
+* only when `bytes` doesn't start at a multiple of 8; or why it can't be read: it isn't one, `by` isn't a symbol, or it
+* names a component or resource the trait doesn't cover, or covers with another schema.
 */
-var decode = (bytes) => {
-	const decoded = decodeContents(bytes);
+const decode = (bytes, options) => {
+	const decoded = decodeContents(bytes, options.by);
 	return "failure" in decoded ? decoded : { [contents]: decoded };
 };
 //#endregion
 //#region src/encode.ts
 /**
-* A snapshot as bytes, little-endian: a header naming each persisted component and resource with its schema, then
-* 8-byte-aligned blocks of each table's entities and columns, its bytes columns copied whole.
+* A snapshot as bytes, little-endian: a header naming each component and resource it holds by its trait's name for it,
+* with its schema, then 8-byte-aligned blocks of each table's entities and columns, its bytes columns copied whole.
 */
-var encode = (snapshot) => encodeContents(snapshot[contents]);
+const encode = (snapshot) => encodeContents(snapshot[contents]);
 //#endregion
 //#region src/selection/selection.ts
 /** A readonly system reading the tables `declaration` names. */
-var tablesSystemOf = (declaration) => System.create({
+const tablesSystemOf = (declaration) => System.create({
 	readonly: true,
 	tables: declaration
 }, ({ tables }) => tables);
 /** The rows of `table` whose entities `keep` takes, as a table of their own. */
-var rowsOf = (table, keep) => {
+const rowsOf = (table, keep) => {
 	const rows = [];
 	for (let row = 0; row < table.count; row++) if (keep(table.entities[row])) rows.push(row);
 	if (rows.length === table.count) return table;
@@ -402,7 +395,7 @@ var rowsOf = (table, keep) => {
 	};
 };
 /** The entities `root` owns, itself included, through the owner references among `owners` in the tables. */
-var subtreeOf = (tables, owners, root) => {
+const subtreeOf = (tables, owners, root) => {
 	const children = /* @__PURE__ */ new Map();
 	for (const table of tables) for (const reference of owners) {
 		const key = reference;
@@ -425,8 +418,8 @@ var subtreeOf = (tables, owners, root) => {
 	}
 	return taken;
 };
-/** The persisted part of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
-var select = async (world, program, selection) => {
+/** What `program`'s trait covers of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
+const select = async (world, program, selection) => {
 	const components = [...program.components.values()];
 	const keys = components.map((persisted) => persisted.key);
 	const subtree = "root" in selection;
@@ -435,9 +428,17 @@ var select = async (world, program, selection) => {
 		components: keys,
 		with: selection.with ?? [],
 		not: selection.not ?? [],
+		where: selection.where ?? {},
 		resources: resources.map((persisted) => persisted.key)
 	};
-	const read = await world.run(tablesSystemOf(declaration)).catch((error) => ({ failure: error instanceof Error ? error.message : String(error) }));
+	const failed = (error) => ({ failure: error instanceof Error ? error.message : String(error) });
+	let system;
+	try {
+		system = tablesSystemOf(declaration);
+	} catch (error) {
+		return failed(error);
+	}
+	const read = await world.run(system).catch(failed);
 	if ("failure" in read) return read;
 	let tables = read.archetypes;
 	if (subtree) {
@@ -446,6 +447,7 @@ var select = async (world, program, selection) => {
 		tables = tables.flatMap((table) => rowsOf(table, (entity) => taken.has(entity)) ?? []);
 	}
 	return {
+		by: program.by,
 		components,
 		tables,
 		resources: resources.map((persisted) => ({
@@ -457,39 +459,281 @@ var select = async (world, program, selection) => {
 //#endregion
 //#region src/snapshot.ts
 /**
-* 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.
+* A snapshot of some of `world`'s entities, read on its thread, by the trait `by`: a trait of the application's own,
+* whose value on a component's or resource's declaration is the name it's saved under. Of each entity it takes, it
+* takes the components the trait covers. By default it takes every entity holding one of them, and the resources the
+* trait covers; with `with` and `not`, those a query matches, and the resources unless `resources` is false; with
+* `where`, those of the archetypes holding its values of shared components, as a system's `where` of values keeps it to
+* them, read whole, so a snapshot of one value's entities costs what they hold, not the world; with `root`, it and every
+* entity it owns, through owner references the trait covers, without resources. Fails, as data, when `by` isn't a
+* symbol, what the trait covers can't be saved, `where` names what isn't a shared component or gives one a value not
+* of its type, or the world can't be read.
 */
-var snapshot = async (input) => {
-	const program = programOf();
+const snapshot = async (input) => {
+	const program = programOf(input.by);
 	if (typeof program === "string") return { failure: program };
 	const taken = await select(input.world, program, input);
 	return "failure" in taken ? taken : { [contents]: taken };
 };
 //#endregion
+//#region src/match/keys.ts
+/** A table for up to `capacity` keys. */
+const createKeyTable = (capacity) => {
+	let size = 16;
+	while (size < 2 * capacity) size *= 2;
+	return {
+		mask: size - 1,
+		slots: new Int32Array(2 * size),
+		tables: new Int32Array(capacity),
+		rows: new Int32Array(capacity),
+		values: new Float64Array(capacity),
+		columns: [],
+		count: 0
+	};
+};
+/** FNV-1a over a row's bytes in each column, then mixed so its low bits, which pick a slot, depend on all of them. */
+const hashOf = (columns, row) => {
+	let hash = 2166136261;
+	for (let c = 0; c < columns.length; c++) {
+		const { bytes, stride } = columns[c];
+		for (let at = row * stride, end = at + stride; at < end; at++) hash = Math.imul(hash ^ bytes[at], 16777619);
+	}
+	hash ^= hash >>> 16;
+	hash = Math.imul(hash, 2246822507);
+	hash ^= hash >>> 13;
+	hash = Math.imul(hash, 3266489909);
+	return hash ^ hash >>> 16;
+};
+const equalAt = (a, rowA, b, rowB) => {
+	if (a.length !== b.length) return false;
+	for (let c = 0; c < a.length; c++) {
+		const { bytes: left, stride } = a[c];
+		const { bytes: right, stride: other } = b[c];
+		if (stride !== other) return false;
+		for (let k = 0, i = rowA * stride, j = rowB * stride; k < stride; k++) if (left[i + k] !== right[j + k]) return false;
+	}
+	return true;
+};
+/** The slot holding `row`'s key, or the empty one where it would go. */
+const slotOf = (table, columns, row, hash) => {
+	const { mask, slots, tables, rows } = table;
+	for (let slot = hash & mask;; slot = slot + 1 & mask) {
+		const entry = slots[2 * slot + 1] - 1;
+		if (entry < 0) return slot;
+		if (slots[2 * slot] === hash && equalAt(table.columns[tables[entry]], rows[entry], columns, row)) return slot;
+	}
+};
+/**
+* Begins adding the rows of a table of `columns`; `addKey` then takes rows of it. Each table's columns are kept, since
+* its entries' keys are their rows' bytes.
+*/
+const addKeyColumns = (table, columns) => {
+	table.columns.push(columns);
+};
+/**
+* Adds row `row` of the table `addKeyColumns` began last, with `value`, unless a key equal to its is there: whether
+* it was added. Takes at most the capacity the table was created with.
+*/
+const addKey = (table, row, value) => {
+	const at = table.columns.length - 1;
+	const columns = table.columns[at];
+	const hash = hashOf(columns, row);
+	const slot = slotOf(table, columns, row, hash);
+	if (table.slots[2 * slot + 1] !== 0) return false;
+	const entry = table.count++;
+	table.slots[2 * slot] = hash;
+	table.slots[2 * slot + 1] = entry + 1;
+	table.tables[entry] = at;
+	table.rows[entry] = row;
+	table.values[entry] = value;
+	return true;
+};
+/**
+* The entry whose key is equal to row `row`'s of `columns`, or -1 for none. `guess` is an entry to compare first, such
+* as the one after the entry found for the row before: rows in the order they were added are found without hashing.
+*/
+const findKey = (table, columns, row, guess) => {
+	if (guess >= 0 && guess < table.count && equalAt(table.columns[table.tables[guess]], table.rows[guess], columns, row)) return guess;
+	return table.slots[2 * slotOf(table, columns, row, hashOf(columns, row)) + 1] - 1;
+};
+//#endregion
+//#region src/match/match.ts
+/** What a match reads of a world: the tables of the entities an index holds, with its key's columns. */
+const keysSystemOf = (declaration) => System.create({
+	readonly: true,
+	tables: {
+		components: declaration.key,
+		with: [...declaration.key, ...declaration.components.with ?? []],
+		not: declaration.components.not ?? []
+	}
+}, ({ tables }) => tables.archetypes);
+/** Bytes as text, a character each, so equal bytes give equal text and a row's are a slice of its column's. */
+const bytesDecoder = new TextDecoder("latin1");
+/**
+* Each row's key in a table, as text, or null for a table without a column of each part: each part's column, its bytes
+* in the world's layout, which two worlds of one program share, or its value as JSON by its schema. Equal keys give
+* equal text.
+*/
+const keysOf = (table, parts) => {
+	const columns = [];
+	for (const { key, schema } of parts) {
+		const column = table.columns[key];
+		if (column === void 0) return null;
+		if (column.kind === "bytes") {
+			const text = bytesDecoder.decode(column.bytes);
+			const { stride } = column;
+			columns.push((row) => text.slice(row * stride, (row + 1) * stride));
+		} else if (column.kind === "values") columns.push((row) => JSON.stringify(toJson(schema, column.values[row])));
+		else {
+			const text = JSON.stringify(toJson(schema, column.value));
+			columns.push(() => text);
+		}
+	}
+	const [only] = columns;
+	return columns.length === 1 && only !== void 0 ? only : (row) => columns.map((part) => part(row)).join("\0");
+};
+/** Whether a table holds the entities an index holds: every key part and `with` component, and none in `not`. */
+const covers = (table, declaration) => [...declaration.key, ...declaration.components.with ?? []].every((key) => table.columns[key] !== void 0) && (declaration.components.not ?? []).every((key) => table.columns[key] === void 0);
+const twoWithOneKey = (name) => ({ failure: `Index "${name}" can't match: two of the snapshot's entities have one key.` });
+const readWorld = (world, declaration) => world.run(keysSystemOf(declaration)).catch((error) => ({ failure: error instanceof Error ? error.message : String(error) }));
+/** Two of the world's entities with one key: the one with the lower entity index, as its unique index keeps. */
+const keep = (existing, entity, candidate) => {
+	const kept = existing.get(entity);
+	if (kept === void 0 || candidate >>> 0 < kept >>> 0) existing.set(entity, candidate);
+};
+/** A table's columns of each part, or null for one without a column of bytes for each. */
+const bytesOf = (table, parts) => {
+	const columns = [];
+	for (const { key } of parts) {
+		const column = table.columns[key];
+		if (column === void 0 || column.kind !== "bytes") return null;
+		columns.push(column);
+	}
+	return columns;
+};
+/**
+* Matches by the bytes of keys' columns, without making text of them, when every table of the snapshot holding the
+* index's entities has columns of bytes for its key; null otherwise. The world's tables, of the same program, then do too.
+*/
+const matchBytes = (world, from, declaration, parts) => {
+	const tables = from.tables.filter((table) => covers(table, declaration));
+	const columns = tables.map((table) => bytesOf(table, parts));
+	if (columns.some((item) => item === null)) return null;
+	return async (name, existing) => {
+		const saved = createKeyTable(tables.reduce((sum, table) => sum + table.count, 0));
+		for (let t = 0; t < tables.length; t++) {
+			const keys = columns[t];
+			if (keys === null) continue;
+			addKeyColumns(saved, keys);
+			const { entities, count } = tables[t];
+			for (let row = 0; row < count; row++) if (!addKey(saved, row, entities[row])) return twoWithOneKey(name);
+		}
+		if (saved.count === 0) return void 0;
+		const read = await readWorld(world, declaration);
+		if ("failure" in read) return read;
+		for (const table of read) {
+			const keys = bytesOf(table, parts);
+			if (keys === null) continue;
+			for (let row = 0, entry = -1; row < table.count; row++) {
+				entry = findKey(saved, keys, row, entry + 1);
+				if (entry >= 0) keep(existing, saved.values[entry], table.entities[row]);
+			}
+		}
+	};
+};
+/** Matches by keys as text, which any column gives. */
+const matchText = (world, from, declaration, parts) => async (name, existing) => {
+	const saved = /* @__PURE__ */ new Map();
+	for (const table of from.tables) {
+		if (!covers(table, declaration)) continue;
+		const keyAt = keysOf(table, parts);
+		if (keyAt === null) continue;
+		for (let row = 0; row < table.count; row++) {
+			const key = keyAt(row);
+			if (saved.has(key)) return twoWithOneKey(name);
+			saved.set(key, table.entities[row]);
+		}
+	}
+	if (saved.size === 0) return void 0;
+	const read = await readWorld(world, declaration);
+	if ("failure" in read) return read;
+	for (const table of read) {
+		const keyAt = keysOf(table, parts);
+		if (keyAt === null) continue;
+		for (let row = 0; row < table.count; row++) {
+			const entity = saved.get(keyAt(row));
+			if (entity !== void 0) keep(existing, entity, table.entities[row]);
+		}
+	}
+};
+/**
+* Each of the snapshot's entities that `indexes` say is the same as one of `world`'s, to that one: an index holds both,
+* with equal keys. Fails, as data, for an index whose key, `with` or `not` names a component the snapshot's trait doesn't
+* cover, or two of the snapshot's entities one index holds with one key.
+*/
+const existingFor = async (world, from, indexes) => {
+	const existing = /* @__PURE__ */ new Map();
+	const persisted = new Map(from.components.map((item) => [item.key, item]));
+	for (const index of indexes) {
+		const declaration = Index.declarationOf(index);
+		if (declaration === void 0) return { failure: `${index.name} isn't an index.` };
+		const parts = [];
+		for (const key of declaration.key) {
+			const found = persisted.get(key);
+			if (found === void 0) return { failure: `Index "${index.name}" can't match: a part of its key isn't one the snapshot's trait covers, so the snapshot holds no key for it.` };
+			parts.push({
+				key,
+				schema: found.schema
+			});
+		}
+		if ([...declaration.components.with ?? [], ...declaration.components.not ?? []].some((key) => !persisted.has(key))) return { failure: `Index "${index.name}" can't match: its with or not names a component the snapshot's trait doesn't cover, so the snapshot can't tell which of its entities the index holds.` };
+		const found = await (matchBytes(world, from, declaration, parts) ?? matchText(world, from, declaration, parts))(index.name, existing);
+		if (found !== void 0) return found;
+	}
+	return existing;
+};
+//#endregion
 //#region src/spawn.ts
-var isTables = (value) => 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");
-var isKeyed = (value) => typeof value === "object" && value !== null;
-/** Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities. */
-var spawnTables = System.create({}, ({ commands }, input) => {
-	if (!isTables(input.tables) || !isKeyed(input.resources)) throw new Error("A snapshot holds tables and resources.");
-	return commands.spawnTables(input.tables, input.resources);
+const isTables = (value) => 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) => typeof value === "object" && value !== null;
+/** `spawnTables` takes entities by their numbers: a map of the snapshot's to the world's holds only numbers. */
+const isEntities = (value) => {
+	if (!(value instanceof Map)) return false;
+	for (const [saved, found] of value) if (typeof saved !== "number" || typeof found !== "number") return false;
+	return true;
+};
+/**
+* Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities, those `existing` maps
+* standing for theirs, onto which `update` writes their rows.
+*/
+const spawnTables = System.create({}, ({ commands }, input) => {
+	if (!isTables(input.tables) || !isKeyed(input.resources) || !isEntities(input.existing)) throw new Error("A snapshot holds tables and resources.");
+	return commands.spawnTables(input.tables, {
+		resources: input.resources,
+		existing: input.existing,
+		update: input.update
+	});
 }, {
 	"type": "object",
 	"properties": {
 		"tables": { "allOf": [] },
-		"resources": { "allOf": [] }
+		"resources": { "allOf": [] },
+		"existing": { "allOf": [] },
+		"update": { "type": "boolean" }
 	}
 });
 async function spawn(input) {
-	const { tables, resources } = input.snapshot[contents];
+	const from = input.snapshot[contents];
+	const { tables, resources } = from;
 	const values = {};
 	for (const { persisted, value } of resources) values[persisted.key] = value;
+	const existing = input.match === void 0 || input.match.length === 0 ? /* @__PURE__ */ new Map() : await existingFor(input.world, from, input.match);
+	if ("failure" in existing) return existing;
 	const spawned = await input.world.run(spawnTables, {
 		tables,
-		resources: values
+		resources: values,
+		existing,
+		update: input.update === true
 	}).catch((error) => ({ failure: error instanceof Error ? error.message : String(error) }));
 	if ("failure" in spawned) return spawned;
 	if (input.entities === false) return { dropped: spawned.dropped };
@@ -498,8 +742,8 @@ async function spawn(input) {
 		entities: entitiesOf(tables, spawned.entities)
 	};
 }
-/** Each of the tables' entities to the one spawned for it, or null for one that wasn't. */
-var entitiesOf = (tables, spawned) => {
+/** Each of the tables' entities to the one spawned for it, the one existing for it, or null for one that wasn't. */
+const entitiesOf = (tables, spawned) => {
 	const entities = /* @__PURE__ */ new Map();
 	tables.forEach((table, t) => {
 		const made = spawned[t];
@@ -511,6 +755,6 @@ var entitiesOf = (tables, spawned) => {
 	return entities;
 };
 //#endregion
-export { decode, encode, persist, snapshot, spawn };
+export { decode, encode, snapshot, spawn };
 
 //# sourceMappingURL=index.js.map