slopkit 0.1.2 → 0.2.0

package/dist/conformance/paging-budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conformance/paging-budget.test.js

@@ -0,0 +1,101 @@
+import { expect, test } from "vitest";
+import { createSync, table } from "../sync.js";
+import { row, rowSchema } from "./fixtures.js";
+/** Real Map with read instrumentation: no timer noise and no substitute for the production table implementation. */
+class MeasuredMap extends Map {
+    visits = 0;
+    *measure(items) {
+        for (const item of items) {
+            this.visits++;
+            yield item;
+        }
+    }
+    entries() {
+        return this.measure(super.entries());
+    }
+    keys() {
+        return this.measure(super.keys());
+    }
+    values() {
+        return this.measure(super.values());
+    }
+    [Symbol.iterator]() {
+        return this.measure(super[Symbol.iterator]());
+    }
+    get(key) {
+        this.visits++;
+        return super.get(key);
+    }
+    forEach(callback, 
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Map's receiver is arbitrary, forwarded unchanged
+    thisArg) {
+        for (const [key, value] of super.entries()) {
+            this.visits++;
+            callback.call(thisArg, value, key, this);
+        }
+    }
+}
+test("budget: merging a two-row chunk does not grow with the existing 1k or 100k rows", () => {
+    const costs = [1000, 100_000].map((size) => {
+        const rows = new MeasuredMap(Array.from({ length: size }, (_, index) => [String(index), row(String(index), index, 1)]));
+        const before = { rows };
+        const lens = table({
+            name: "rows",
+            schema: rowSchema,
+            rows: (patch) => patch.rows,
+            key: (item) => item.id,
+            get: (tables) => tables.rows,
+            set: (_tables, next) => ({ rows: next }),
+        });
+        const engine = createSync({
+            tables: [lens],
+            empty: { rows: new Map() },
+            onlineOnly: () => false,
+            refused: (_command, reason) => ({ kind: "failed", reason }),
+        });
+        const replica = {
+            dataset: "dataset-a",
+            revision: 1,
+            tables: before,
+            server: { build: "fixture-v1" },
+            history: {
+                kind: "partial",
+                next: "older",
+                through: "0",
+                held: size,
+                total: size + 2,
+            },
+        };
+        const [model] = engine.update(engine.initial("page-a", 0), {
+            type: "loaded",
+            replica,
+            commands: [],
+            unreadable: 0,
+            now: 0,
+        });
+        const reply = {
+            dataset: "dataset-a",
+            revision: 2,
+            reset: false,
+            rows: { rows: [row("new-a", -1, 2), row("new-b", -2, 2)] },
+            server: { build: "fixture-v1" },
+            page: { from: "older", next: null, through: null, held: size + 2, total: size + 2 },
+        };
+        rows.visits = 0;
+        const [after] = engine.update(model, {
+            type: "pulled",
+            since: 1,
+            patch: reply,
+            receipts: [],
+            now: 1,
+        });
+        const cost = rows.visits;
+        expect(after.replica.tables.rows.size).toBe(size + 2);
+        expect(after.replica.tables.rows.get("new-a")).toStrictEqual(row("new-a", -1, 2));
+        expect(after.replica.tables.rows.get("new-b")).toStrictEqual(row("new-b", -2, 2));
+        expect(before.rows.has("new-a")).toBe(false);
+        expect(before.rows.get("0")).toStrictEqual(row("0", 0, 1));
+        return cost;
+    });
+    expect(costs[1]).toBe(costs[0]);
+});

package/dist/conformance/paging-fixtures.d.ts

@@ -0,0 +1,80 @@
+import type { Effect, Model, Patch, Replica } from "../sync.ts";
+import type { Command, Outcome, PatchRows, Row, Server, Tables } from "./fixtures.ts";
+/** Wire and checkpoint vocabulary shared by the conformance inputs. */
+export type Page = {
+    from: string | null;
+    next: string | null;
+    through: string | null;
+    held: number;
+    total: number;
+};
+export type History = {
+    kind: "complete";
+} | {
+    kind: "partial";
+    next: string;
+    through: string | null;
+    held: number;
+    total: number;
+};
+export type PagedCopy = Replica<Tables, Server> & {
+    history: History;
+};
+export type PagedPatch = Patch<PatchRows, Server> & {
+    page: Page;
+};
+export type M = Model<Tables, Server, Command, Outcome>;
+export type E = Effect<Tables, Server, Command, Outcome>;
+export declare const complete: {
+    readonly kind: "complete";
+};
+export declare const newest: {
+    deleted: boolean;
+    id: string;
+    revision: number;
+    value: number;
+}[];
+export declare const middle: {
+    deleted: boolean;
+    id: string;
+    revision: number;
+    value: number;
+}[];
+export declare const oldest: {
+    deleted: boolean;
+    id: string;
+    revision: number;
+    value: number;
+}[];
+export declare const all: {
+    deleted: boolean;
+    id: string;
+    revision: number;
+    value: number;
+}[];
+export declare const firstPage: Page;
+export declare const secondPage: Page;
+export declare const lastPage: Page;
+export declare function paged(revision: number, rows: Row[], page: Page, reset?: boolean, dataset?: string): PagedPatch;
+export declare function partialCopy(revision?: number, rows?: {
+    deleted: boolean;
+    id: string;
+    revision: number;
+    value: number;
+}[], page?: Page): PagedCopy;
+export declare function history(replica: Replica<Tables, Server>): History | undefined;
+export declare function requestedPage(request: {
+    client: string;
+    since: number;
+}): string | null | undefined;
+export declare function loaded(replica?: Replica<Tables, Server>): M;
+export declare function deliver(model: M, reply: PagedPatch | Patch<PatchRows, Server>, since?: number): readonly [M, readonly E[]];
+/** A tiny independent history: only the authoritative rows, indexed by revision. No client merge or digest. */
+export declare class Reference {
+    private readonly revisions;
+    constructor(revision: number, rows: readonly Row[]);
+    write(revision: number, changes: readonly Row[]): void;
+    at(revision: number): ReadonlyMap<string, Row>;
+}
+/** Every held row must be current; the declared covered range must be fully present. */
+export declare function assertCopy(model: M, reference: Reference): void;

package/dist/conformance/paging-fixtures.js

@@ -0,0 +1,135 @@
+import { expect } from "vitest";
+import { check, literal, nullable, number, object, optional, string, variant } from "../schema.js";
+import { copy, patch, row, sync } from "./fixtures.js";
+export const complete = { kind: "complete" };
+export const newest = [row("f", 60, 10), row("e", 50, 10)];
+export const middle = [row("d", 40, 10), row("c", 30, 10)];
+export const oldest = [row("b", 20, 10), row("a", 10, 10)];
+export const all = [...newest, ...middle, ...oldest];
+export const firstPage = { from: null, next: "older:e:50", through: "50", held: 2, total: 6 };
+export const secondPage = {
+    from: "older:e:50",
+    next: "older:c:30",
+    through: "30",
+    held: 4,
+    total: 6,
+};
+export const lastPage = { from: "older:c:30", next: null, through: null, held: 6, total: 6 };
+export function paged(revision, rows, page, reset = false, dataset = "dataset-a") {
+    return { ...patch(revision, rows, reset, dataset), page };
+}
+export function partialCopy(revision = 10, rows = newest, page = firstPage) {
+    if (page.next === null) {
+        return { ...copy(revision, rows), history: complete };
+    }
+    return {
+        ...copy(revision, rows),
+        history: {
+            kind: "partial",
+            next: page.next,
+            through: page.through,
+            held: page.held,
+            total: page.total,
+        },
+    };
+}
+const historySchema = variant("kind", {
+    complete: object({ kind: literal("complete") }),
+    partial: object({
+        kind: literal("partial"),
+        next: string(),
+        through: nullable(string()),
+        held: number({ integer: true, min: 0 }),
+        total: number({ integer: true, min: 0 }),
+    }),
+});
+export function history(replica) {
+    if (!("history" in replica)) {
+        return undefined;
+    }
+    const parsed = check(historySchema, replica.history);
+    if (!parsed.ok) {
+        throw new Error("invalid history shape");
+    }
+    return parsed.value;
+}
+export function requestedPage(request) {
+    const parsed = check(optional(nullable(string())), "page" in request ? request.page : undefined);
+    if (!parsed.ok) {
+        throw new Error("invalid request page");
+    }
+    return parsed.value;
+}
+const emptyCopy = { ...copy(0, []), history: complete };
+export function loaded(replica = emptyCopy) {
+    return sync.update(sync.initial("page-a", 0), {
+        type: "loaded",
+        replica,
+        commands: [],
+        unreadable: 0,
+        now: 0,
+    })[0];
+}
+export function deliver(model, reply, since = model.replica.revision) {
+    return sync.update(model, {
+        type: "pulled",
+        since,
+        patch: reply,
+        receipts: [],
+        now: model.now + 1,
+    });
+}
+/** A tiny independent history: only the authoritative rows, indexed by revision. No client merge or digest. */
+export class Reference {
+    revisions = new Map();
+    constructor(revision, rows) {
+        this.revisions.set(revision, new Map(rows.flatMap((item) => (item.deleted ? [] : [[item.id, item]]))));
+    }
+    write(revision, changes) {
+        const previous = [...this.revisions.values()].at(-1);
+        const next = new Map(previous);
+        for (const item of changes) {
+            if (item.deleted) {
+                next.delete(item.id);
+            }
+            else {
+                next.set(item.id, item);
+            }
+        }
+        this.revisions.set(revision, next);
+    }
+    at(revision) {
+        const rows = this.revisions.get(revision);
+        if (rows === undefined) {
+            throw new Error(`no reference revision ${revision}`);
+        }
+        return rows;
+    }
+}
+/** Every held row must be current; the declared covered range must be fully present. */
+export function assertCopy(model, reference) {
+    const expected = reference.at(model.replica.revision);
+    for (const [id, item] of model.replica.tables.rows) {
+        expect(item, `held row ${id} at ${model.replica.revision}`).toStrictEqual(expected.get(String(id)));
+    }
+    const claim = history(model.replica);
+    expect(claim).toBeDefined();
+    if (claim === undefined) {
+        throw new Error("missing history");
+    }
+    const kind = claim.kind;
+    const through = claim.kind === "partial" ? claim.through : null;
+    const covered = [...expected.values()].filter((item) => kind === "complete" || (through !== null && item.value >= Number(through)));
+    for (const item of covered) {
+        expect(model.replica.tables.rows.get(item.id)).toStrictEqual(item);
+    }
+    if (kind === "complete") {
+        expect(model.replica.tables.rows.size).toBe(expected.size);
+    }
+    else {
+        expect(kind).toBe("partial");
+        expect(claim.held).toBeGreaterThanOrEqual(covered.length);
+        expect(claim.held).toBeLessThanOrEqual(expected.size);
+        expect(claim.total).toBe(expected.size);
+    }
+}

package/dist/conformance/paging-network.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conformance/paging-network.test.js

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "vitest";
+import { createClient } from "../client.js";
+import { Network as SeededNetwork } from "../test/network.js";
+import { copy, database, deferred, patch, row, sync, values } from "./fixtures.js";
+import { all, assertCopy, complete, firstPage, history, lastPage, middle, newest, paged, Reference, requestedPage, secondPage, } from "./paging-fixtures.js";
+// Named histories replay fixed server answers through the actual executor and seeded overlapping transport.
+const histories = [
+    { name: "lost-first-copy", seed: 73, drop: 0.2, duplicate: 0.3 },
+    { name: "overlapping-retries", seed: 991, drop: 0.1, duplicate: 0.7 },
+];
+describe("paged first copy over the seeded network", () => {
+    test.each(histories)("1, 2, 5, 12: $name converges across dropped and duplicate requests and a reload", async (scenario) => {
+        const transport = new SeededNetwork(scenario.seed);
+        transport.faults = { drop: scenario.drop, duplicate: scenario.duplicate, maxDelay: 200 };
+        const stored = database();
+        const reloadStep = 50 + Math.floor(transport.random() * 650);
+        const reference = new Reference(10, all);
+        const changes = [
+            row("f", 65, 11),
+            row("a", 5, 11),
+            row("new", 70, 11),
+            row("b", 20, 11, true),
+        ];
+        reference.write(11, changes);
+        const snapshots = [];
+        const writes = new Set();
+        const requests = [];
+        const network = {
+            pull: async (request) => {
+                requests.push(request);
+                const response = await transport.request(async () => {
+                    const cursor = requestedPage(request);
+                    const reply = request.since === 0
+                        ? paged(10, newest, firstPage, true)
+                        : cursor === firstPage.next
+                            ? paged(11, [...changes, ...middle], { ...secondPage, held: 5, total: 6 })
+                            : cursor === secondPage.next
+                                ? paged(11, [row("a", 5, 11)], { ...lastPage, held: 6, total: 6 })
+                                : patch(11, request.since === 10 ? changes : []);
+                    return { patch: reply, receipts: [] };
+                }, 1000);
+                return response.ok
+                    ? { ok: true, value: response.value }
+                    : { ok: false, failure: { kind: "offline", message: "seeded delivery lost" } };
+            },
+            push: async () => ({ ok: false, failure: { kind: "offline", message: "no commands" } }),
+        };
+        function page(name) {
+            const booted = deferred();
+            const original = stored.port.commit;
+            const app = createClient({
+                sync,
+                client: name,
+                render: (model) => {
+                    snapshots.push(model);
+                    if (model.boot.kind === "ready") {
+                        booted.resolve();
+                    }
+                },
+                ports: {
+                    storage: {
+                        ...stored.port,
+                        commit: (value) => {
+                            const work = original(value);
+                            writes.add(work);
+                            void work
+                                .finally(() => {
+                                writes.delete(work);
+                            })
+                                .catch(() => undefined);
+                            return work;
+                        },
+                    },
+                    network,
+                    now: () => transport.now,
+                    fingerprint: async () => "fixture-fingerprint",
+                },
+            });
+            return { app, booted };
+        }
+        let { app, booted } = page("page-a");
+        app.start();
+        await booted.promise;
+        const abandoned = [];
+        for (let step = 0; step < 3500; step++) {
+            if (step === 750) {
+                transport.faults = { drop: 0, duplicate: 0, maxDelay: 10 };
+            }
+            if (step === reloadStep) {
+                abandoned.push(app);
+                // The old page is no longer visible; already-sent answers may still land.
+                app.dispatch({ type: "visible", visible: false, now: transport.now });
+                ({ app, booted } = page("page-b"));
+                app.start();
+                await booted.promise;
+            }
+            app.dispatch({ type: "tick", now: transport.now });
+            await transport.advance(20);
+            await Promise.allSettled(writes);
+        }
+        // No more ticks: finish any already-started request and commit, not a wall-clock delay.
+        await transport.advance(2000);
+        await Promise.allSettled(writes);
+        await Promise.all([app, ...abandoned].map((client) => client.settle()));
+        expect(transport.errors).toStrictEqual([]);
+        for (const model of snapshots) {
+            if (model.replica.dataset !== null && model.replica.revision > 0) {
+                assertCopy(model, reference);
+            }
+        }
+        expect(values(app.model().replica)).toStrictEqual(values(copy(11, [
+            ...newest.filter((item) => item.id !== "f"),
+            row("f", 65, 11),
+            ...middle,
+            row("a", 5, 11),
+            row("new", 70, 11),
+        ])));
+        expect(history(app.model().replica)).toStrictEqual(complete);
+        expect(history((await stored.port.load()).replica)).toStrictEqual(complete);
+        expect(requests.some((request) => requestedPage(request) === firstPage.next)).toBe(true);
+        expect(app.faults).toStrictEqual([]);
+    });
+});

package/dist/conformance/paging-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conformance/paging-state.test.js

@@ -0,0 +1,180 @@
+import { expect, test } from "vitest";
+import { MEANINGS, states } from "../states.js";
+import * as syncExports from "../sync.js";
+import { STORAGE_DEADLINE_MS } from "../sync.js";
+import { copy } from "./fixtures.js";
+import { all, complete, loaded, newest, partialCopy } from "./paging-fixtures.js";
+const working = {
+    meaning: "working",
+    where: "main",
+    claim: false,
+    why: "the copy is loading",
+    text: () => "loading copy",
+    action: null,
+};
+const warning = {
+    meaning: "ours",
+    where: "main",
+    claim: true,
+    why: "the durable copy needs attention",
+    text: () => "copy needs attention",
+    action: null,
+};
+const historyTable = {
+    loading: working,
+    none: {
+        meaning: "none",
+        where: "main",
+        claim: false,
+        why: "no server copy is held",
+        text: () => "no copy yet",
+        action: null,
+    },
+    complete: {
+        meaning: "ok",
+        where: "panel",
+        claim: false,
+        why: "every server row is held",
+        text: () => "complete history",
+        action: null,
+    },
+    partial: {
+        meaning: "partial",
+        where: "main",
+        claim: true,
+        why: "the numbers cover only a fully loaded range",
+        text: (state) => state.through === null
+            ? `loading history · ${state.held} of ${state.total}`
+            : `history from ${state.through}, loading older · ${state.held} of ${state.total}`,
+        action: null,
+    },
+};
+const durabilityTable = {
+    loading: working,
+    unsaved: { ...warning, text: () => "not saved yet" },
+    lost: { ...warning, text: (state) => `not saved: ${state.reason}` },
+    failing: { ...warning, text: (state) => `storage failing: ${state.reason}` },
+    replaced: { ...warning, text: () => "reload this copy" },
+    unreadable: { ...warning, text: (state) => `${state.count} unreadable commands kept` },
+    ok: {
+        meaning: "ok",
+        where: "panel",
+        claim: false,
+        why: "the observed copy is kept",
+        text: () => "saved",
+        action: null,
+    },
+};
+function typeContract() {
+    const { partial, ...withoutPartial } = historyTable;
+    // @ts-expect-error the public history union requires partial to be placed
+    const incomplete = withoutPartial;
+    const { lost, ...withoutLost } = durabilityTable;
+    // @ts-expect-error the independent durability union requires lost to be placed
+    const missingStorage = withoutLost;
+    void partial;
+    void lost;
+    void incomplete;
+    void missingStorage;
+}
+void typeContract;
+function api() {
+    const exported = syncExports;
+    return exported;
+}
+function deriveHistory(model) {
+    const derive = api().deriveHistoryState;
+    expect(derive, "sync exports deriveHistoryState(model)").toBeTypeOf("function");
+    if (derive === undefined) {
+        throw new Error("missing deriveHistoryState");
+    }
+    return derive(model);
+}
+function deriveDurability(model) {
+    const derive = api().deriveDurabilityState;
+    expect(derive, "sync exports deriveDurabilityState(model)").toBeTypeOf("function");
+    if (derive === undefined) {
+        throw new Error("missing deriveDurabilityState");
+    }
+    return derive(model);
+}
+test("6, 10: history is its own closed subject, including no fully covered order group yet", () => {
+    const model = loaded(partialCopy());
+    const state = deriveHistory(model);
+    expect(state).toStrictEqual({ kind: "partial", through: "50", held: 2, total: 6 });
+    const display = states({ order: MEANINGS });
+    const subject = display.subject("history", historyTable);
+    const line = subject.line(state);
+    expect(line).toMatchObject({
+        where: "main",
+        claim: true,
+        glyph: "◑",
+        text: "history from 50, loading older · 2 of 6",
+    });
+    const unbounded = deriveHistory(loaded(partialCopy(10, newest, { from: null, next: "tie", through: null, held: 2, total: 6 })));
+    expect(subject.line(unbounded).text).toBe("loading history · 2 of 6");
+    const whole = { ...copy(10, all), history: complete };
+    expect(deriveHistory(loaded(whole))).toStrictEqual({ kind: "complete" });
+    expect(deriveHistory({ ...model, boot: { kind: "loading", since: 0 } })).toStrictEqual({
+        kind: "loading",
+    });
+    expect(deriveHistory({ ...model, replica: { ...whole, dataset: null } })).toStrictEqual({
+        kind: "none",
+    });
+});
+const trouble = (base) => [
+    { model: { ...base, storage: { kind: "replaced" } }, state: { kind: "replaced" } },
+    {
+        model: { ...base, storage: { kind: "failed", reason: "quota" } },
+        state: { kind: "failing", reason: "quota" },
+    },
+    {
+        model: {
+            ...base,
+            storage: { kind: "failed", reason: "quota" },
+            saved: { ...base.saved, behindSince: 0 },
+        },
+        state: { kind: "lost", reason: "quota" },
+    },
+    {
+        model: { ...base, now: STORAGE_DEADLINE_MS, saved: { ...base.saved, behindSince: 0 } },
+        state: { kind: "unsaved" },
+    },
+    { model: { ...base, unreadable: 2 }, state: { kind: "unreadable", count: 2 } },
+];
+test("durability retains the storage catalog independently of completeness", () => {
+    const whole = { ...copy(10, all), history: complete };
+    const base = loaded(whole);
+    for (const item of trouble(base)) {
+        expect(deriveDurability(item.model)).toStrictEqual(item.state);
+    }
+    expect(deriveDurability({ ...base, boot: { kind: "loading", since: 0 } })).toStrictEqual({
+        kind: "loading",
+    });
+    expect(deriveDurability(base)).toStrictEqual({ kind: "ok" });
+});
+test("partial history and every storage problem survive composition as independent claims", () => {
+    const display = states({ order: MEANINGS });
+    const historySubject = display.subject("history", historyTable);
+    const durabilitySubject = display.subject("durability", durabilityTable);
+    const base = loaded(partialCopy());
+    for (const item of trouble(base)) {
+        const historyState = deriveHistory(item.model);
+        const durability = deriveDurability(item.model);
+        expect(historyState).toStrictEqual({ kind: "partial", through: "50", held: 2, total: 6 });
+        expect(durability).toStrictEqual(item.state);
+        const historyLine = historySubject.line(historyState);
+        const storageLine = durabilitySubject.line(durability);
+        for (const parts of [
+            [historyLine, storageLine],
+            [storageLine, historyLine],
+        ]) {
+            const screen = display.compose(parts, "synced");
+            expect(screen.ok).toBe(false);
+            expect(screen.claims).toContain(historyLine);
+            expect(screen.claims).toContain(storageLine);
+            expect(screen.more).not.toContain(historyLine);
+            expect(screen.more).not.toContain(storageLine);
+        }
+    }
+});

package/dist/conformance/paging-storage.test.d.ts

@@ -0,0 +1 @@
+export {};