@adobe/ecs 0.0.0-stage → 0.1.0

package/src/observe/entity.ts

@@ -0,0 +1,224 @@
+import { Index, System, type Component, type Entity, type World } from '../interface/index.js';
+import type { Observe } from './observe.js';
+import { createEntry, give, giveFirst, keysId, labelOf, none, noDelivery, ownName, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
+
+/** An observed entity's value, shared by its observers, and by optional component whether it had it last. */
+type EntityEntry = Entry<object | null> & { readonly entity: Entity; readonly present: boolean[] };
+
+/**
+ * The entities observed with one list of required and optional components, read by one observer system that looks each
+ * up by entity; with no optional components, it skips them while an index of what has the required ones reports no
+ * change. `swept` is false while an entry may have no subscribers.
+ */
+type EntityShape = Shape & {
+    readonly system: System;
+    /** On a joined thread, a run of its system, once resolved giving first values its pass read. */
+    readonly read: Read;
+    /** Whether its system is added: it's removed once the shape has been idle for a pass, and added again on use. */
+    attached: boolean;
+    readonly entries: EntityEntry[];
+    readonly byEntity: Map<Entity, EntityEntry>;
+    waiting: boolean;
+    swept: boolean;
+};
+
+/** By world, its entity observers' shapes, kept for its life, so their systems register in it once. */
+const shapes = new WeakMap<WorldState, Map<string, EntityShape>>();
+
+/** Indexes of the entities with every component of a list, by its id: one per list in the program. */
+const memberIndexes = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly has: readonly Component.Key[] } }>>();
+
+const membersOf = (required: readonly Component.Key[]) => {
+    const id = keysId(required);
+    let index = memberIndexes.get(id);
+    if (index === undefined) memberIndexes.set(id, index = Index.create({ name: `Observe.entity(${labelOf(required)})`, key: [], components: { has: [...required] } }));
+    return index;
+};
+
+/** A by-entity lookup's row: whether a component it watches changed since its system last ran. */
+type PresenceRow = { readonly changed: boolean };
+
+/** A by-entity lookup's row of the components it reads, and whether one changed since its system last ran. */
+type LookupRow = { readonly changed: boolean } & { readonly [K in Component.Key]: unknown };
+
+/** What a pass finds an entity by: whether it has the required components and they changed, their values, and an optional one's. */
+type Finders = {
+    readonly presence: (entity: Entity) => PresenceRow | null;
+    readonly values: (entity: Entity) => { readonly [K in Component.Key]?: unknown } | null;
+    readonly optional: (index: number, entity: Entity) => LookupRow | null;
+};
+
+const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: string, required: readonly Component.Key[], optional: readonly Component.Key[]): EntityShape => {
+    const name = ownName(`Observe.entity(${labelOf(required)}${optional.length === 0 ? "" : `; ${labelOf(optional)}`})`);
+    const rows: (LookupRow | null)[] = optional.map(() => null);
+    /**
+     * Reads an entry's entity, giving its value if it changed and first values to subscribers waiting up to `through`:
+     * its required values only once they changed, a new object each time.
+     */
+    const evaluate = (entry: EntityEntry, finders: Finders, through: number, failed: unknown): unknown => {
+        const found = finders.presence(entry.entity);
+        let changed: boolean;
+        if (found === null) changed = !entry.valid || entry.value !== null;
+        else {
+            changed = !entry.valid || entry.value === null || found.changed;
+            for (let i = 0; i < optional.length; i++) {
+                const row = rows[i] = finders.optional(i, entry.entity);
+                const present = row !== null;
+                if (present !== entry.present[i] || (present && row.changed)) changed = true;
+            }
+        }
+        if (changed) {
+            if (found === null) entry.value = null;
+            else if (optional.length === 0) entry.value = finders.values(entry.entity);
+            else {
+                const value: { [key: symbol]: unknown } = {};
+                const values = required.length === 0 ? null : finders.values(entry.entity);
+                for (let i = 0; i < required.length; i++) value[required[i]] = values?.[required[i]];
+                for (let i = 0; i < optional.length; i++) {
+                    const row = rows[i];
+                    entry.present[i] = row !== null;
+                    if (row !== null) value[optional[i]] = row[optional[i]];
+                }
+                entry.value = value;
+            }
+            entry.valid = true;
+        }
+        if (!changed && entry.waiting === 0) return failed;
+        return give(entry, through, changed, state.pass, -1, failed);
+    };
+    /** Drops entries found without subscribers in three passes, as shapes are; returns whether any is left without them. */
+    const sweep = (): boolean => {
+        const { entries } = shape;
+        let kept = 0;
+        let idle = false;
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.stopped > 0) sweepSubscribers(entry);
+            if (entry.live === 0) {
+                if (++entry.idle > 2) {
+                    shape.byEntity.delete(entry.entity);
+                    continue;
+                }
+                idle = true;
+            }
+            entries[kept++] = entry;
+        }
+        entries.length = kept;
+        return idle;
+    };
+    /** Evaluates every entry, or with nothing changed, those whose subscribers wait for a first value. */
+    const pass = (changed: boolean, finders: Finders): void => {
+        passed(state);
+        if (!shape.swept) shape.swept = !sweep();
+        if (!changed && !shape.waiting) return;
+        const through = state.delivered;
+        const { entries } = shape;
+        let failed: unknown = none;
+        let waiting = false;
+        for (let i = 0, count = entries.length; i < count; i++) {
+            const entry = entries[i];
+            if (changed || (entry.waiting > 0 && !entry.valid)) failed = evaluate(entry, finders, through, failed);
+            else if (entry.waiting > 0) failed = give(entry, through, false, state.pass, -1, failed);
+            if (entry.waiting > 0) waiting = true;
+        }
+        shape.waiting = waiting;
+        throwFailed(failed);
+    };
+    /** The finders of the runner whose lookups they are: another, once its system is added again. */
+    let finders: Finders | null = null;
+    let source: object | null = null;
+    const system = optional.length === 0
+        ? System.create({ name, observer: true, lookup: { presence: { has: required, changed: required }, values: { read: required }, members: { index: membersOf(required), changed: required } } }, ({ lookup }) => {
+            if (source !== lookup || finders === null) {
+                source = lookup;
+                finders = { presence: lookup.presence, values: lookup.values, optional: noOptional };
+            }
+            pass(lookup.members().changed, finders);
+        })
+        : System.create({ name, observer: true, lookup: optionalLookups(required, optional) }, ({ lookup }) => {
+            if (source !== lookup || finders === null) {
+                source = lookup;
+                finders = { presence: lookup.presence, values: lookup.values, optional: (index, entity) => lookup[index](entity) };
+            }
+            pass(true, finders);
+        });
+    const shape: EntityShape = {
+        live: 0,
+        idle: 0,
+        system,
+        read: {
+            system,
+            flushed: noDelivery,
+            delivered: batch => {
+                const { entries } = shape;
+                for (let i = 0; i < entries.length; i++) giveFirst(state, entries[i], batch);
+            },
+        },
+        attached: false,
+        entries: [],
+        byEntity: new Map(),
+        waiting: false,
+        swept: true,
+        remove: () => {
+            shape.attached = false;
+            shape.entries.length = 0;
+            shape.byEntity.clear();
+            state.world.remove(system);
+        },
+    };
+    byShape.set(id, shape);
+    return shape;
+};
+
+const noOptional = (): null => null;
+
+type Watched = { readonly read: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+
+/** Lookups of an entity's required components, whether and what, and one of each optional one, by its position. */
+const optionalLookups = (required: readonly Component.Key[], optional: readonly Component.Key[]): {
+    readonly presence: { readonly has: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+    readonly values: { readonly read: readonly Component.Key[] };
+    readonly [index: number]: Watched;
+} => {
+    const lookups: { presence: { readonly has: readonly Component.Key[]; readonly changed: readonly Component.Key[] }; values: { readonly read: readonly Component.Key[] }; [index: number]: Watched } = {
+        presence: { has: required, changed: required },
+        values: { read: required },
+    };
+    for (let i = 0; i < optional.length; i++) lookups[i] = { read: [optional[i]], changed: [optional[i]] };
+    return lookups;
+};
+
+export const observeEntity = <T>(world: World, entity: Entity, components: { readonly required?: readonly Component.Key[]; readonly optional?: readonly Component.Key[] }): Observe<T | null> => {
+    const required = [...components.required ?? []];
+    const optional = [...components.optional ?? []];
+    const id = `${keysId(required)};${keysId(optional)}`;
+    return notify => {
+        const state = stateOf(world);
+        let byShape = shapes.get(state);
+        if (byShape === undefined) shapes.set(state, byShape = new Map());
+        const shape = byShape.get(id) ?? createShape(state, byShape, id, required, optional);
+        if (!shape.attached) {
+            // Throws on a joined thread for components it can't read, adding nothing.
+            world.add(shape.system);
+            shape.attached = true;
+        }
+        let entry = shape.byEntity.get(entity);
+        if (entry === undefined) {
+            entry = { ...createEntry<object | null>(null), entity, present: optional.map(() => false) };
+            shape.byEntity.set(entity, entry);
+            shape.entries.push(entry);
+        }
+        const observed = entry;
+        // An entity observer's values have the listed components' types, which `members.ts` gives `T` by the lists.
+        const typed = observed as Entry<T | null>;
+        const stop = subscribe(state, shape, typed, notify, () => {
+            shape.waiting = true;
+            if (state.joined) scheduleRead(state, shape.read);
+            else scheduleDelivery(state);
+        });
+        return () => {
+            if (observed.live > 0) shape.swept = false;
+            stop();
+        };
+    };
+};

package/src/observe/index.ts

@@ -0,0 +1 @@
+export { Observe } from './observe.js';

package/src/observe/members.ts

@@ -0,0 +1,42 @@
+import type { Component, Components, Entity, Resource, World } from '../interface/index.js';
+import { observeEntity } from './entity.js';
+import type { Observe } from './observe.js';
+import { observeCount, observeSelect } from './select.js';
+import type { Query } from './query.js';
+import { observeResource } from './resource.js';
+import type { ReadonlyResourceValue, ReadonlyValue } from './values.js';
+
+export { toPromise } from './to-promise.js';
+export type { Query } from './query.js';
+
+/**
+ * A resource's value, then a new one after each run or tick that changed it: one whose sync point stamped it, even with
+ * the same value, a reduced resource when its fold differs.
+ */
+export const resource = <R extends Resource.Key>(world: World, resource: R): Observe<ReadonlyResourceValue<R>> =>
+    observeResource(world, resource);
+
+/**
+ * An entity's required components and those optional ones it has, or `null` while it's dead or lacks a required one;
+ * then a new value after each run or tick that wrote a listed component of it, added or removed one, or despawned it.
+ * Other components' changes don't notify, nor does anything while it stays `null`. Values map over
+ * `Pick<Components, ...>`, so their symbol keys keep the declarations a consumer's emitted types name them by.
+ */
+export const entity = <const R extends readonly Component.Key[] = [], const O extends readonly Component.Key[] = []>(
+    world: World,
+    entity: Entity,
+    components: { readonly required?: R; readonly optional?: O },
+): Observe<({ readonly [K in keyof Pick<Components, R[number]>]: ReadonlyValue<K> } & { readonly [K in keyof Pick<Components, O[number]>]?: ReadonlyValue<K> }) | null> =>
+    observeEntity(world, entity, components);
+
+/**
+ * The entities a query matches, sorted by `order` if given, and with a `page`, at most `limit` of them from `offset`;
+ * then a new value after each run or tick whose result differs. Nothing when it's the same, even if matching entities
+ * were written. Throws for a page whose offset or limit isn't a non-negative integer.
+ */
+export const select = <const R extends readonly Component.Key[] = []>(world: World, query: Query<R>): Observe<readonly Entity[]> =>
+    observeSelect(world, query);
+
+/** The number of entities a query matches; then a new one after each run or tick that changed it. */
+export const count = <const R extends readonly Component.Key[] = []>(world: World, query: Omit<Query<R>, "order" | "page">): Observe<number> =>
+    observeCount(world, query);

package/src/observe/observe.ts

@@ -0,0 +1,24 @@
+/**
+ * Observes a sequence of values: `notify` is called zero or more times, possibly during the call that subscribes,
+ * possibly later; an observer mustn't depend on either. Returns the function that stops it.
+ */
+export type Observe<T> = (notify: (value: T) => void) => Unobserve;
+
+/** Stops notifications; calling it again does nothing. */
+type Unobserve = () => void;
+
+/**
+ * Observers of a world, built on observer systems: one per resource and per shape of observer, shared by every
+ * subscriber of it, notifying once per run or tick whose sync point changed what it gives, and only then. - A first
+ * value already held for that resource, entity or query, while others observe it, comes during the subscribing   call,
+ * as of the last sync point. Any other comes later, from a run after every run called before the subscribing   call, so
+ * it reflects them; first values of one task come in that order, from one batch of runs. A first value   whose notify
+ * throws is thrown out of band, as an uncaught error, and stops that observer; a later value's is a   `"system"`
+ * failure of the run or tick, named by the observer's system.
+ * - Selections without `order`, and ties under one, come in entity order. Under `order`, NaN comes after every number.
+ * - Values are kept warm for subscribers to come while their observers are used, and released once the world's
+ *   passes found them unused in three; a query is kept current through an index only once a subscriber outlives its
+ *   first value, so a first value alone is one scan.
+ * - A disposed world runs nothing, so a first value that comes later never comes.
+ */
+export * as Observe from './members.js';

package/src/observe/observe.type-test.ts

@@ -0,0 +1,88 @@
+import { Component, Resource, type Entity, type World } from '../interface/index.js';
+import { Observe } from './index.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+declare const world: World;
+declare const entity: Entity;
+
+const point = Symbol("observeTypeTest/point");
+const persistent = Symbol("observeTypeTest/persistent");
+const shared = Symbol("observeTypeTest/shared");
+const time = Symbol("observeTypeTest/time");
+declare module '@adobe/ecs' {
+    export interface Components {
+        [point]: { type: { readonly x: number } };
+        [persistent]: { type: true };
+        [shared]: { type: true };
+    }
+    export interface Resources {
+        [time]: { type: number };
+    }
+}
+Component.register(point, { type: { type: "object", properties: { x: { type: "number" } } } });
+Component.register(persistent, { type: { const: true } });
+Component.register(shared, { type: { const: true } });
+Resource.register(time, { type: { type: "number", default: 0 } });
+
+// The module's `Observe` has the shape of the package root's.
+check<Equal<Observe<number>, (notify: (value: number) => void) => () => void>>();
+
+// A resource's value, read-only.
+const observedTime: Observe<number> = Observe.resource(world, time);
+// @ts-expect-error a resource's value has its type
+Observe.resource(world, time)((value: string) => { void value; });
+// @ts-expect-error only resources are observed by key
+Observe.resource(world, point);
+
+// An entity's listed components, required present and optional possibly, or null.
+const observedBoth: Observe<({ readonly [point]: { readonly x: number } } & { readonly [shared]?: true }) | null> = Observe.entity(world, entity, { required: [point], optional: [shared] });
+Observe.entity(world, entity, { required: [point] })(value => {
+    if (value === null) return;
+    check<Equal<typeof value[typeof point]["x"], number>>();
+    // @ts-expect-error only listed components are observed
+    void value[shared];
+    // @ts-expect-error observed values are read-only
+    value[point].x = 1;
+});
+Observe.entity(world, entity, { optional: [point] })(value => {
+    // @ts-expect-error an optional component may be missing
+    void value?.[point].x;
+});
+// @ts-expect-error the whole-entity form is gone: list the components
+Observe.entity(world, entity);
+// @ts-expect-error an observed entity may be dead
+Observe.entity(world, entity, { required: [point] })((value: { readonly [point]: { readonly x: number } }) => { void value; });
+// @ts-expect-error only components are observed on an entity
+Observe.entity(world, entity, { optional: [time] });
+
+// Queries: `where` and `order` name only required components; `count` takes no `order` or `page`.
+const query: Observe.Query<[typeof persistent]> = { required: [persistent], not: [shared], where: { [persistent]: true }, order: { [persistent]: true } };
+const selected: Observe<readonly Entity[]> = Observe.select(world, query);
+const selectedAll: Observe<readonly Entity[]> = Observe.select(world, {});
+const counted: Observe<number> = Observe.count(world, { required: [persistent], where: { [persistent]: { "!=": true } } });
+const paged: Observe<readonly Entity[]> = Observe.select(world, { required: [persistent], order: { [persistent]: true }, page: { offset: 20, limit: 10 } });
+Observe.select(world, { required: [point], where: { [point]: { x: 1 } } })(entities => {
+    // @ts-expect-error selected entities are read-only
+    entities.push(entity);
+});
+// @ts-expect-error where may only filter required components
+Observe.select(world, { required: [persistent], where: { [shared]: true } });
+// @ts-expect-error order may only sort by required components
+Observe.select(world, { required: [persistent], order: { [shared]: true } });
+// @ts-expect-error a where value has its component's type
+Observe.select(world, { required: [point], where: { [point]: { x: "one" } } });
+// @ts-expect-error count has no order
+Observe.count(world, { required: [persistent], order: { [persistent]: true } });
+// @ts-expect-error count has no page
+Observe.count(world, { required: [persistent], page: { offset: 0, limit: 10 } });
+// @ts-expect-error a page has an offset and a limit
+Observe.select(world, { required: [persistent], page: { limit: 10 } });
+// @ts-expect-error queries list only components
+Observe.select(world, { required: [time] });
+
+// The first value of any observer.
+const first: Promise<number> = Observe.toPromise(Observe.count(world, {}));
+
+void [observedTime, observedBoth, selected, selectedAll, counted, paged, first];

package/src/observe/plans.ts

@@ -0,0 +1,272 @@
+import type { Component, Entity } from '../interface/index.js';
+import { compare, compareNumbers } from './compare.js';
+
+// What a query's rows are gathered into, row by row, from a scan or an index's list: a count; every entity, put in
+// entity order once gathered; or by `order`, a bounded heap of the first `offset + limit`, or every row, sorted once
+// gathered. Ties under `order` go in entity order. Scratch is typed and reused, so gathering allocates only to grow.
+
+/** A row's values by component, as systems' rows and index lookups' rows give them. */
+export type Values = { readonly [K in Component.Key]?: unknown };
+
+/** One term of an `order`: its component and direction. */
+export type Term = { readonly key: Component.Key; readonly ascending: boolean };
+
+export type Page = { readonly offset: number; readonly limit: number };
+
+/** Gathers rows, then writes the result, entities into `out` from 0, returning how many, or for a count, the count. */
+export type Gather = {
+    readonly start: () => void;
+    readonly add: (entity: number, values: Values) => void;
+    readonly finish: (out: Entity[]) => number;
+    /** How many entities `finish` would write now, so a result can be made at its length. */
+    readonly size: () => number;
+};
+
+/** An entity a world gave out, held as a number in typed scratch. */
+// The world's entities are numbers, which scratch arrays hold as they were given.
+export const asEntity = (value: number): Entity => value as Entity;
+
+/** An entity's index: its low 32 bits, which order live entities, as an index without a key keeps them. */
+export const indexOf = (entity: number): number => entity >>> 0;
+
+export const createCount = (): Gather => {
+    let count = 0;
+    return {
+        start: () => { count = 0; },
+        add: () => { count++; },
+        finish: () => count,
+        size: () => count,
+    };
+};
+
+/** By entity index, the entity there while sorting, else 0: shared, and cleared after each use. */
+let bucket = new Float64Array(0);
+
+/** Writes `count` entities of `from` into `out` in entity order. */
+const toEntityOrder = (from: Float64Array, count: number, largest: number, out: Entity[]): void => {
+    if (bucket.length <= largest) bucket = new Float64Array(Math.max(largest + 1, 2 * bucket.length));
+    for (let i = 0; i < count; i++) bucket[indexOf(from[i])] = from[i];
+    if (count * 16 >= largest) {
+        let n = 0;
+        for (let index = 0; index <= largest && n < count; index++) {
+            const entity = bucket[index];
+            if (entity === 0) continue;
+            bucket[index] = 0;
+            out[n++] = asEntity(entity);
+        }
+        return;
+    }
+    const indexes = new Uint32Array(count);
+    for (let i = 0; i < count; i++) indexes[i] = indexOf(from[i]);
+    indexes.sort();
+    for (let i = 0; i < count; i++) {
+        out[i] = asEntity(bucket[indexes[i]]);
+        bucket[indexes[i]] = 0;
+    }
+};
+
+/**
+ * A new array of `count` entities of `from` in entity order: as they are when `ordered`, else sorted, `largest` the
+ * largest index among them.
+ */
+export const inEntityOrder = (from: Float64Array, count: number, largest: number, ordered: boolean): Entity[] => {
+    const out = new Array<Entity>(count);
+    if (ordered) for (let i = 0; i < count; i++) out[i] = asEntity(from[i]);
+    else toEntityOrder(from, count, largest, out);
+    return out;
+};
+
+/** Every entity, in entity order once gathered. */
+export const createAll = (): Gather => {
+    let entities = new Float64Array(64);
+    let count = 0;
+    let largest = 0;
+    let ordered = true;
+    return {
+        start: () => {
+            count = 0;
+            largest = 0;
+            ordered = true;
+        },
+        add: entity => {
+            if (count === entities.length) {
+                const grown = new Float64Array(2 * entities.length);
+                grown.set(entities);
+                entities = grown;
+            }
+            const index = indexOf(entity);
+            if (index < largest) ordered = false;
+            else largest = index;
+            entities[count++] = entity;
+        },
+        finish: out => {
+            if (ordered) {
+                for (let i = 0; i < count; i++) out[i] = asEntity(entities[i]);
+                return count;
+            }
+            toEntityOrder(entities, count, largest, out);
+            return count;
+        },
+        size: () => count,
+    };
+};
+
+/**
+ * Rows held by slot: each one's entity, and per term its value, a number in `numbers` where `isNumber` says so, so
+ * numeric keys aren't boxed.
+ */
+type Slots = {
+    entities: Float64Array;
+    numbers: Float64Array[];
+    isNumber: Uint8Array[];
+    values: unknown[][];
+};
+
+const createSlots = (terms: number, length: number): Slots => ({
+    entities: new Float64Array(length),
+    numbers: Array.from({ length: terms }, () => new Float64Array(length)),
+    isNumber: Array.from({ length: terms }, () => new Uint8Array(length)),
+    values: Array.from({ length: terms }, () => new Array<unknown>(length)),
+});
+
+const growSlots = (slots: Slots, length: number): void => {
+    const entities = new Float64Array(length);
+    entities.set(slots.entities);
+    slots.entities = entities;
+    for (let t = 0; t < slots.numbers.length; t++) {
+        const numbers = new Float64Array(length);
+        numbers.set(slots.numbers[t]);
+        slots.numbers[t] = numbers;
+        const isNumber = new Uint8Array(length);
+        isNumber.set(slots.isNumber[t]);
+        slots.isNumber[t] = isNumber;
+        slots.values[t].length = length;
+    }
+};
+
+const store = (slots: Slots, terms: readonly Term[], at: number, entity: number, values: Values): void => {
+    slots.entities[at] = entity;
+    for (let t = 0; t < terms.length; t++) {
+        const value = values[terms[t].key];
+        if (typeof value === "number") {
+            slots.numbers[t][at] = value;
+            slots.isNumber[t][at] = 1;
+            slots.values[t][at] = undefined;
+        }
+        else {
+            slots.isNumber[t][at] = 0;
+            slots.values[t][at] = value;
+        }
+    }
+};
+
+const move = (slots: Slots, from: number, to: number): void => {
+    slots.entities[to] = slots.entities[from];
+    for (let t = 0; t < slots.numbers.length; t++) {
+        slots.numbers[t][to] = slots.numbers[t][from];
+        slots.isNumber[t][to] = slots.isNumber[t][from];
+        slots.values[t][to] = slots.values[t][from];
+    }
+};
+
+/** Slots `a` and `b` compared in `order`, then by entity index. */
+const compareSlots = (slots: Slots, terms: readonly Term[], a: number, b: number): number => {
+    for (let t = 0; t < terms.length; t++) {
+        const isNumber = slots.isNumber[t];
+        const order = isNumber[a] === 1 && isNumber[b] === 1
+            ? compareNumbers(slots.numbers[t][a], slots.numbers[t][b])
+            : compare(isNumber[a] === 1 ? slots.numbers[t][a] : slots.values[t][a], isNumber[b] === 1 ? slots.numbers[t][b] : slots.values[t][b]);
+        if (order !== 0) return terms[t].ascending ? order : -order;
+    }
+    return indexOf(slots.entities[a]) - indexOf(slots.entities[b]);
+};
+
+/**
+ * The first `offset + limit` rows by `order`, or by entity index without terms: a heap of them with the last at its
+ * root, O(n log(offset + limit)), sorted once gathered. The last two slots hold a candidate and a swap.
+ */
+export const createHeap = (terms: readonly Term[], page: Page): Gather => {
+    const bound = page.offset + page.limit;
+    const slots = createSlots(terms.length, Math.min(bound, 62) + 2);
+    let size = 0;
+    const swap = (a: number, b: number): void => {
+        const spare = slots.entities.length - 1;
+        move(slots, a, spare);
+        move(slots, b, a);
+        move(slots, spare, b);
+    };
+    const siftUp = (from: number): void => {
+        let at = from;
+        while (at > 0) {
+            const parent = (at - 1) >> 1;
+            if (compareSlots(slots, terms, parent, at) >= 0) return;
+            swap(parent, at);
+            at = parent;
+        }
+    };
+    const siftDown = (from: number, count: number): void => {
+        let at = from;
+        for (;;) {
+            const left = 2 * at + 1;
+            if (left >= count) return;
+            const right = left + 1;
+            const later = right < count && compareSlots(slots, terms, left, right) < 0 ? right : left;
+            if (compareSlots(slots, terms, at, later) >= 0) return;
+            swap(at, later);
+            at = later;
+        }
+    };
+    return {
+        start: () => { size = 0; },
+        add: (entity, values) => {
+            if (bound === 0) return;
+            if (size < bound) {
+                if (size + 2 >= slots.entities.length) growSlots(slots, Math.min(bound, 2 * slots.entities.length) + 2);
+                store(slots, terms, size, entity, values);
+                siftUp(size++);
+                return;
+            }
+            // Before the last kept, it replaces it.
+            const candidate = slots.entities.length - 2;
+            store(slots, terms, candidate, entity, values);
+            if (compareSlots(slots, terms, candidate, 0) >= 0) return;
+            move(slots, candidate, 0);
+            siftDown(0, size);
+        },
+        finish: out => {
+            for (let end = size - 1; end > 0; end--) {
+                swap(0, end);
+                siftDown(0, end);
+            }
+            let n = 0;
+            for (let i = page.offset; i < size; i++) out[n++] = asEntity(slots.entities[i]);
+            for (let t = 0; t < terms.length; t++) slots.values[t].fill(undefined);
+            return n;
+        },
+        size: () => Math.max(0, size - page.offset),
+    };
+};
+
+/** Every row by `order`, sorted once gathered. */
+export const createSorted = (terms: readonly Term[]): Gather => {
+    const slots = createSlots(terms.length, 64);
+    let size = 0;
+    let positions = new Int32Array(64);
+    const byOrder = (a: number, b: number): number => compareSlots(slots, terms, a, b);
+    return {
+        start: () => { size = 0; },
+        add: (entity, values) => {
+            if (size === slots.entities.length) growSlots(slots, 2 * size);
+            store(slots, terms, size++, entity, values);
+        },
+        finish: out => {
+            if (positions.length < size) positions = new Int32Array(slots.entities.length);
+            for (let i = 0; i < size; i++) positions[i] = i;
+            const sorted = positions.subarray(0, size).sort(byOrder);
+            for (let i = 0; i < size; i++) out[i] = asEntity(slots.entities[sorted[i]]);
+            for (let t = 0; t < terms.length; t++) slots.values[t].fill(undefined, 0, size);
+            return size;
+        },
+        size: () => size,
+    };
+};