@adobe/ecs-persistence 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,754 @@
+import { Component, Index, Resource, System } from "@adobe/ecs";
+//#region src/program/program.ts
+/**
+* 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.
+*/
+const namedIn = (declarations, kind, by) => {
+	const named = /* @__PURE__ */ new Map();
+	for (const [key, declaration] of declarations) {
+		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,
+			schema: declaration.type
+		});
+	}
+	return named;
+};
+/** 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", by);
+	if (typeof resources === "string") return resources;
+	return {
+		by,
+		components,
+		resources
+	};
+};
+//#endregion
+//#region src/values/values.ts
+/** A number JSON can't hold, as text: `NaN`, `Infinity`, `-Infinity` or `-0`. */
+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;
+		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, 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));
+	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. */
+const toJson = (schema, value) => {
+	if ("anyOf" in schema) {
+		const index = schema.anyOf.findIndex((candidate) => fits(candidate, value));
+		const member = schema.anyOf[index];
+		return member === void 0 ? [-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 = {};
+			for (const name of Object.keys(value)) {
+				const field = schema.properties[name];
+				const item = Reflect.get(value, name);
+				if (item !== void 0) json[name] = field === void 0 ? item : toJson(field, item);
+			}
+			return json;
+		}
+		default: return value;
+	}
+};
+/** A value of `schema` read back from its 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]];
+		return member === void 0 ? 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, void 0])) : json;
+		case "object": {
+			if (typeof json !== "object" || json === null || Array.isArray(json)) return json;
+			const value = {};
+			for (const name of Object.keys(json)) {
+				const field = schema.properties[name];
+				const item = Reflect.get(json, name);
+				value[name] = field === void 0 ? item : fromJson(field, item);
+			}
+			return value;
+		}
+		default: return json;
+	}
+};
+//#endregion
+//#region src/format/format.ts
+/**
+* The binary form of a snapshot, little-endian:
+* - 16 bytes: `ECSP`, the format's version as a u32, the header's length in bytes as a u32, and 4 bytes of zeros;
+* - the header, JSON text padded with spaces to a multiple of 8 bytes: each component and resource by name with its
+*   schema, and each table's count and where its entities and columns are;
+* - blocks, each starting at a multiple of 8 bytes: a table's entities as f64s, a column's bytes as its components'
+*   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.
+*/
+const magic = [
+	69,
+	67,
+	83,
+	80
+];
+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. */
+const encodeContents = (snapshot) => {
+	const blocks = [];
+	let offset = 0;
+	/** Places a block, returning its offset from the first block. */
+	const place = (bytes) => {
+		const at = offset;
+		blocks.push(bytes);
+		offset = aligned(offset + bytes.byteLength);
+		return at;
+	};
+	const indexOf = new Map(snapshot.components.map((persisted, index) => [persisted.key, index]));
+	const tables = snapshot.tables.map((table) => {
+		const entities = place(new Uint8Array(table.entities.buffer, table.entities.byteOffset, table.entities.byteLength));
+		const columns = snapshot.components.flatMap((persisted) => {
+			const key = persisted.key;
+			const column = Reflect.get(table.columns, key);
+			const component = indexOf.get(persisted.key) ?? -1;
+			if (column === void 0) return [];
+			if (column.kind === "bytes") return [{
+				component,
+				kind: "bytes",
+				offset: place(column.bytes),
+				length: column.bytes.byteLength,
+				stride: column.stride
+			}];
+			if (column.kind === "value") return [{
+				component,
+				kind: "value",
+				value: toJson(persisted.schema, column.value)
+			}];
+			const text = encoder.encode(JSON.stringify(column.values.map((value) => toJson(persisted.schema, value))));
+			return [{
+				component,
+				kind: "values",
+				offset: place(text),
+				length: text.byteLength
+			}];
+		});
+		return {
+			count: table.count,
+			entities,
+			columns
+		};
+	});
+	const header = {
+		components: snapshot.components.map(({ name, schema }) => ({
+			name,
+			schema
+		})),
+		resources: snapshot.resources.map(({ persisted, value }) => ({
+			name: persisted.name,
+			schema: persisted.schema,
+			value: toJson(persisted.schema, value)
+		})),
+		tables
+	};
+	const text = encoder.encode(JSON.stringify(header));
+	const headerLength = aligned(text.byteLength);
+	const bytes = new Uint8Array(prefix + headerLength + offset);
+	bytes.set(magic, 0);
+	const view = new DataView(bytes.buffer);
+	view.setUint32(4, version, true);
+	view.setUint32(8, headerLength, true);
+	bytes.set(text, prefix);
+	bytes.fill(32, prefix + text.byteLength, prefix + headerLength);
+	let at = prefix + headerLength;
+	for (const block of blocks) {
+		bytes.set(block, at);
+		at = aligned(at + block.byteLength);
+	}
+	return bytes;
+};
+const isObject = (value) => typeof value === "object" && value !== null;
+/** The header's JSON, checked enough to read it without casts, or null. */
+const headerOf = (json) => {
+	if (!isObject(json)) return null;
+	const components = Reflect.get(json, "components");
+	const resources = Reflect.get(json, "resources");
+	const tables = Reflect.get(json, "tables");
+	if (!Array.isArray(components) || !Array.isArray(resources) || !Array.isArray(tables)) return null;
+	const named = (item) => isObject(item) && typeof Reflect.get(item, "name") === "string" && isObject(Reflect.get(item, "schema"));
+	if (!components.every(named) || !resources.every(named)) return null;
+	const isColumn = (item) => {
+		if (!isObject(item) || typeof Reflect.get(item, "component") !== "number") return false;
+		const kind = Reflect.get(item, "kind");
+		if (kind === "value") return true;
+		const numbers = kind === "bytes" ? [
+			"offset",
+			"length",
+			"stride"
+		] : kind === "values" ? ["offset", "length"] : null;
+		return numbers !== null && numbers.every((name) => typeof Reflect.get(item, name) === "number");
+	};
+	const isTable = (item) => {
+		if (!isObject(item) || typeof Reflect.get(item, "count") !== "number" || typeof Reflect.get(item, "entities") !== "number") return false;
+		const columns = Reflect.get(item, "columns");
+		return Array.isArray(columns) && columns.every(isColumn);
+	};
+	if (!tables.every(isTable)) return null;
+	return json;
+};
+/** Whether two schemas are the same, by their JSON in their properties' order, which places a struct's fields. */
+const sameSchema = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* 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.
+*/
+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);
+	if (found !== version) return { failure: `This snapshot's format is version ${found}; this package reads version ${version}.` };
+	const headerLength = view.getUint32(8, true);
+	let json;
+	try {
+		json = JSON.parse(decoder.decode(bytes.subarray(prefix, prefix + headerLength)));
+	} catch {
+		return { failure: "This snapshot's header isn't JSON." };
+	}
+	const header = headerOf(json);
+	if (header === null) return { failure: "This snapshot's header isn't one this package writes." };
+	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 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 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,
+			value: fromJson(schema, value)
+		});
+	}
+	const blocks = (bytes.byteOffset + prefix + headerLength) % 8 === 0 ? bytes : bytes.slice();
+	const base = blocks.byteOffset + prefix + headerLength;
+	const end = blocks.byteOffset + blocks.byteLength;
+	const inBounds = (offset, length) => offset >= 0 && length >= 0 && base + offset + length <= end;
+	const tables = [];
+	for (const table of header.tables) {
+		if (!inBounds(table.entities, table.count * 8)) return { failure: "This snapshot's blocks are cut short." };
+		const columns = {};
+		for (const column of table.columns) {
+			const persisted = components[column.component];
+			if (persisted === void 0) return { failure: "This snapshot names a component it doesn't hold." };
+			if (column.kind === "value") columns[persisted.key] = {
+				kind: "value",
+				value: fromJson(persisted.schema, column.value)
+			};
+			else if (!inBounds(column.offset, column.length)) return { failure: "This snapshot's blocks are cut short." };
+			else if (column.kind === "bytes") columns[persisted.key] = {
+				kind: "bytes",
+				bytes: new Uint8Array(blocks.buffer, base + column.offset, column.length),
+				stride: column.stride
+			};
+			else {
+				let values;
+				try {
+					values = JSON.parse(decoder.decode(new Uint8Array(blocks.buffer, base + column.offset, column.length)));
+				} catch {
+					return { failure: `Component "${persisted.name}"'s values in this snapshot aren't JSON.` };
+				}
+				if (!Array.isArray(values)) return { failure: `Component "${persisted.name}"'s values in this snapshot aren't a list.` };
+				columns[persisted.key] = {
+					kind: "values",
+					values: values.map((value) => fromJson(persisted.schema, value))
+				};
+			}
+		}
+		tables.push({
+			count: table.count,
+			entities: new Float64Array(blocks.buffer, base + table.entities, table.count),
+			columns
+		});
+	}
+	return {
+		by: program.by,
+		components,
+		tables,
+		resources
+	};
+};
+//#endregion
+//#region src/program/contents.ts
+/** Where a snapshot holds what it holds, a key only this package uses. */
+const contents = Symbol("snapshot contents");
+//#endregion
+//#region src/decode.ts
+/**
+* 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.
+*/
+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 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.
+*/
+const encode = (snapshot) => encodeContents(snapshot[contents]);
+//#endregion
+//#region src/selection/selection.ts
+/** A readonly system reading the tables `declaration` names. */
+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. */
+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;
+	if (rows.length === 0) return null;
+	const columns = {};
+	for (const key of Object.getOwnPropertySymbols(table.columns)) {
+		const column = Reflect.get(table.columns, key);
+		if (column === void 0) 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, owners, root) => {
+	const children = /* @__PURE__ */ new Map();
+	for (const table of tables) for (const reference of owners) {
+		const key = reference;
+		const column = 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 === void 0) children.set(owner, [table.entities[row]]);
+			else list.push(table.entities[row]);
+		}
+	}
+	const taken = /* @__PURE__ */ new Set([root]);
+	const waiting = [root];
+	for (let next = waiting.pop(); next !== void 0; next = waiting.pop()) for (const child of children.get(next) ?? []) {
+		if (taken.has(child)) continue;
+		taken.add(child);
+		waiting.push(child);
+	}
+	return taken;
+};
+/** 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;
+	const resources = subtree || selection.resources === false ? [] : [...program.resources.values()];
+	const declaration = subtree ? { components: keys } : {
+		components: keys,
+		with: selection.with ?? [],
+		not: selection.not ?? [],
+		where: selection.where ?? {},
+		resources: resources.map((persisted) => persisted.key)
+	};
+	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) {
+		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 {
+		by: program.by,
+		components,
+		tables,
+		resources: resources.map((persisted) => ({
+			persisted,
+			value: read.resources[persisted.key]
+		}))
+	};
+};
+//#endregion
+//#region src/snapshot.ts
+/**
+* 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.
+*/
+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
+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. */
+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
+	});
+}, {
+	"type": "object",
+	"properties": {
+		"tables": { "allOf": [] },
+		"resources": { "allOf": [] },
+		"existing": { "allOf": [] }
+	}
+});
+async function spawn(input) {
+	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,
+		existing
+	}).catch((error) => ({ 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, 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];
+		for (let row = 0; row < table.count; row++) {
+			const entity = made[row];
+			entities.set(table.entities[row], entity === 0 ? null : entity);
+		}
+	});
+	return entities;
+};
+//#endregion
+export { decode, encode, snapshot, spawn };
+
+//# sourceMappingURL=index.js.map