mirror of
https://github.com/morluto/rea.git
synced 2026-11-22 14:35:45 +00:00
fix(environment): preserve evidence when inferring and serving state Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2699 lines
93 KiB
TypeScript
2699 lines
93 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
|
|
import { jsonObjectSchema, type JsonValue } from "../jsonValue.js";
|
|
import { webNetworkCaptureSchema } from "../webNetworkCapture.js";
|
|
import { EnvironmentStateAccumulator } from "./EnvironmentStateAccumulator.js";
|
|
import {
|
|
timedCaptureEvidence,
|
|
type TimedCaptureRow,
|
|
} from "../../../tests/fixtures/analysisView.js";
|
|
import {
|
|
ASSET_ROWS,
|
|
BOOK_INIT_ROWS,
|
|
BOOK_NOT_FOUND,
|
|
BOOK_ROWS,
|
|
BOOK_WRITE_CLOCK,
|
|
DETAILED_LIST_ROWS,
|
|
EXPANDED_LIST_ROWS,
|
|
FIRST_BOOK,
|
|
OMITTED_FIELD_ROWS,
|
|
PROJECTED_ROWS,
|
|
RENAMED_BOOK,
|
|
HANDLE_ROWS,
|
|
LIST_LINE_ROWS,
|
|
QUERY_ROWS,
|
|
OFFSET_LIST_ROWS,
|
|
SECOND_BOOK,
|
|
THIRD_BOOK,
|
|
assetBook,
|
|
VERSIONED_ROWS,
|
|
book,
|
|
numberedUuid,
|
|
versionedBook,
|
|
offsetListed,
|
|
bookClock,
|
|
detailedBook,
|
|
environmentStateViewOf,
|
|
expandedBook,
|
|
rawCaptureEvidence,
|
|
renamedBook,
|
|
type Book,
|
|
} from "../../../tests/fixtures/environmentStateWrites.js";
|
|
|
|
type StateView = ReturnType<typeof environmentStateViewOf>;
|
|
|
|
const ISO_SECONDS = {
|
|
kind: "iso",
|
|
separator: "T",
|
|
fraction: 0,
|
|
zone: "Z",
|
|
} as const;
|
|
|
|
const stateOf = (rows: readonly TimedCaptureRow[]): StateView =>
|
|
environmentStateViewOf(timedCaptureEvidence(rows));
|
|
|
|
it("retains learned clock rules but withholds their serving when the global clock is unknown", () => {
|
|
const baseline = stateOf(BOOK_ROWS);
|
|
const unknown = stateOf([
|
|
...BOOK_ROWS,
|
|
["GET", "/api/health", { ready: true }, 200, undefined, -1],
|
|
]);
|
|
expect(baseline.write_clock).not.toBeNull();
|
|
expect(unknown.write_clock).toBeNull();
|
|
const generatesClock = (plan: StateView["writes"][number]) =>
|
|
plan.rules.some((rule) =>
|
|
["clock", "held-clock", "nested-clock"].includes(rule.rule),
|
|
);
|
|
const clockPlans = baseline.writes.filter(
|
|
(plan) => plan.served && generatesClock(plan),
|
|
);
|
|
expect(clockPlans.length).toBeGreaterThan(0);
|
|
for (const plan of clockPlans)
|
|
expect(
|
|
unknown.writes.find((candidate) => candidate.tool === plan.tool),
|
|
).toEqual({
|
|
...plan,
|
|
served: false,
|
|
reason: "unknown-clock",
|
|
});
|
|
const independent = baseline.writes.filter(
|
|
(plan) => plan.served && !generatesClock(plan),
|
|
);
|
|
expect(independent.length).toBeGreaterThan(0);
|
|
for (const plan of independent)
|
|
expect(
|
|
unknown.writes.find((candidate) => candidate.tool === plan.tool),
|
|
).toEqual(plan);
|
|
});
|
|
|
|
it.each([
|
|
["000000000", 0, "2026-10-17T18:00:12.000Z"],
|
|
["000001", 0, "2026-10-17T18:00:13.000Z"],
|
|
["000000001", 0, "2026-10-17T18:00:13.000Z"],
|
|
["123000000", 0, "2026-10-17T18:00:13.000Z"],
|
|
["999999", 0.001, "2026-10-17T18:00:13.000Z"],
|
|
["999999", 0.001001, "2026-10-17T18:00:14.000Z"],
|
|
])(
|
|
"starts the served clock after a final captured fractional instant .%s plus %sms",
|
|
(fraction, duration, expected) => {
|
|
const evidence = timedCaptureEvidence([
|
|
...BOOK_ROWS,
|
|
["GET", "/api/health", { ready: true }, 200, undefined, 0],
|
|
]);
|
|
const capture = webNetworkCaptureSchema.parse(evidence.normalized_result);
|
|
const state = environmentStateViewOf({
|
|
...evidence,
|
|
normalized_result: {
|
|
...capture,
|
|
records: capture.records.map((record, index) =>
|
|
index === capture.records.length - 1
|
|
? {
|
|
...record,
|
|
reported: {
|
|
...jsonObjectSchema.parse(record.reported),
|
|
startedDateTime: `2026-10-17T18:00:12.${fraction}Z`,
|
|
time: duration,
|
|
},
|
|
}
|
|
: record,
|
|
),
|
|
},
|
|
});
|
|
expect(state.write_clock).toBe(expected);
|
|
},
|
|
);
|
|
|
|
it.each(["delete", "mismatched-query"])(
|
|
"does not parse unused request content for %s under a bounded state allowance",
|
|
(kind) => {
|
|
const payload = { unused: "x".repeat(96 * 1024) };
|
|
const changed = renamedBook(FIRST_BOOK, "Renamed", 3);
|
|
const rows: TimedCaptureRow[] =
|
|
kind === "delete"
|
|
? [
|
|
...BOOK_INIT_ROWS,
|
|
["DELETE", "/api/books/2", "", 204, payload],
|
|
["GET", "/api/books/2", BOOK_NOT_FOUND, 404],
|
|
]
|
|
: [
|
|
...BOOK_INIT_ROWS,
|
|
[
|
|
"PATCH",
|
|
"/api/books/1?mode=one",
|
|
changed,
|
|
200,
|
|
{ name: "Renamed" },
|
|
],
|
|
["GET", "/api/books/1", changed],
|
|
["PATCH", "/api/books/2?mode=two", SECOND_BOOK, 200, payload],
|
|
];
|
|
const capture = webNetworkCaptureSchema.parse(
|
|
timedCaptureEvidence(rows).normalized_result,
|
|
);
|
|
const accumulator = new EnvironmentStateAccumulator(512 * 1024);
|
|
for (const record of capture.records) {
|
|
const added = accumulator.add(record);
|
|
if (!added.ok) throw added.error;
|
|
}
|
|
const state = accumulator.finishState();
|
|
expect(state).toMatchObject({ ok: true });
|
|
if (!state.ok) throw state.error;
|
|
expect(
|
|
state.value.writes.find(
|
|
(write) => write.effect === (kind === "delete" ? "delete" : "update"),
|
|
),
|
|
).toMatchObject({ served: true });
|
|
},
|
|
);
|
|
|
|
describe("structured values an earlier update kept", () => {
|
|
it.each([false, true])(
|
|
"refuses a later derived rule that changes an earlier kept value (array: %s)",
|
|
(array) => {
|
|
const content = (text: string): JsonValue =>
|
|
array ? [{ text }] : { children: [{ text }] };
|
|
const entry = (id: number, edited: boolean) => ({
|
|
id,
|
|
title: edited ? "Edited" : "Original",
|
|
content: content(edited ? "Edited body text." : "Original body text."),
|
|
});
|
|
const initial: TimedCaptureRow[] = [
|
|
["GET", "/api/posts", [entry(1, false), entry(2, false)]],
|
|
["GET", "/api/posts/1", entry(1, false)],
|
|
["GET", "/api/posts/2", entry(2, false)],
|
|
];
|
|
const edit = (id: number, changed: boolean): TimedCaptureRow[] => {
|
|
const after = { ...entry(id, changed), title: "Edited" };
|
|
return [
|
|
[
|
|
"PATCH",
|
|
`/api/posts/${id}`,
|
|
after,
|
|
200,
|
|
{ title: "Edited", html: "<p>Edited body text.</p>" },
|
|
],
|
|
["GET", `/api/posts/${id}`, after],
|
|
];
|
|
};
|
|
const plan = (rows: TimedCaptureRow[]) =>
|
|
stateOf([...initial, ...rows]).writes.find(
|
|
(write) => write.tool === "patch_posts_by_id",
|
|
);
|
|
expect(plan([...edit(1, true), ...edit(2, true)])).toMatchObject({
|
|
served: true,
|
|
});
|
|
expect(plan([...edit(1, false), ...edit(2, true)])).toMatchObject({
|
|
served: false,
|
|
reason: "unexplained-change",
|
|
});
|
|
expect(plan([...edit(1, true), ...edit(2, false)])).toMatchObject({
|
|
served: false,
|
|
reason: "unexplained-change",
|
|
});
|
|
},
|
|
);
|
|
});
|
|
|
|
const planOf = (state: StateView, tool: string) => {
|
|
const plan = state.writes.find((candidate) => candidate.tool === tool);
|
|
if (plan === undefined) throw new Error(`No write plan for ${tool}`);
|
|
return plan;
|
|
};
|
|
|
|
/** Each write tool's verdict: "served", else the reason it is not. */
|
|
const verdicts = (rows: readonly TimedCaptureRow[]) =>
|
|
Object.fromEntries(
|
|
stateOf(rows).writes.map((plan) => [
|
|
plan.tool,
|
|
plan.served ? "served" : plan.reason,
|
|
]),
|
|
);
|
|
|
|
/** A create of the third book whose response is `response`, then the given later exchanges. */
|
|
const created = (
|
|
response: JsonValue,
|
|
...later: TimedCaptureRow[]
|
|
): TimedCaptureRow[] => [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", response, 201, { name: "Third Book" }],
|
|
...later,
|
|
];
|
|
|
|
const RENAMED_AT_3 = renamedBook(FIRST_BOOK, "Renamed Book", 3);
|
|
/** An update renaming the first book whose response is `response`, then the given later exchanges. */
|
|
const rename = (
|
|
response: Book = RENAMED_AT_3,
|
|
...later: TimedCaptureRow[]
|
|
): TimedCaptureRow[] => [
|
|
...BOOK_INIT_ROWS,
|
|
["PATCH", "/api/books/1", response, 200, { name: "Renamed Book" }],
|
|
...later,
|
|
];
|
|
|
|
describe("served write plans", () => {
|
|
it("serves the create, update and delete that later reads confirm, citing those reads", () => {
|
|
const state = stateOf(BOOK_ROWS);
|
|
expect(state.write_clock).toBe(BOOK_WRITE_CLOCK);
|
|
expect(planOf(state, "post_books")).toEqual({
|
|
tool: "post_books",
|
|
effect: "create",
|
|
target: "/api/books",
|
|
served: true,
|
|
reason: null,
|
|
exemplar_ordinal: 3,
|
|
observation: { ordinal: 3, pointer: "" },
|
|
response: { ordinal: 3, shape: "entity", pointer: "" },
|
|
body: {
|
|
accepted: ["name"],
|
|
fixed: [],
|
|
required: ["name"],
|
|
identity: null,
|
|
kinds: [],
|
|
},
|
|
rules: [
|
|
{ field: "id", rule: "identity", generator: "sequence" },
|
|
{ field: "name", rule: "echo" },
|
|
{ field: "slug", rule: "slug", from: "name" },
|
|
{ field: "created_at", rule: "clock", format: ISO_SECONDS },
|
|
{ field: "updated_at", rule: "clock", format: ISO_SECONDS },
|
|
],
|
|
collection: null,
|
|
insert: { rule: "sorted", field: "id", direction: "ascending" },
|
|
merge: null,
|
|
// The final list follows the delete of book 3, so it shows nothing of the create.
|
|
checked_record_ordinals: [4],
|
|
contradicted_by: null,
|
|
});
|
|
// PATCH requires no member; the slug follows the sent name and the update stamps its clock.
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
effect: "update",
|
|
served: true,
|
|
exemplar_ordinal: 5,
|
|
body: { accepted: ["name"], required: [] },
|
|
rules: [
|
|
{ field: "name", rule: "echo" },
|
|
{ field: "slug", rule: "slug", from: "name" },
|
|
{ field: "updated_at", rule: "clock", format: ISO_SECONDS },
|
|
],
|
|
checked_record_ordinals: [6, 9],
|
|
});
|
|
expect(planOf(state, "delete_books_by_id")).toMatchObject({
|
|
effect: "delete",
|
|
served: true,
|
|
exemplar_ordinal: 7,
|
|
response: { ordinal: 7, shape: "empty", pointer: null },
|
|
checked_record_ordinals: [8, 9],
|
|
});
|
|
expect(planOf(state, "post_exports")).toMatchObject({
|
|
effect: "none",
|
|
target: null,
|
|
served: false,
|
|
reason: "no-state-target",
|
|
});
|
|
});
|
|
|
|
it("starts the clock from the records a date can hold when one lies past its range", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
RENAMED_AT_3,
|
|
200,
|
|
{ name: "Renamed Book" },
|
|
9_000_000_000_000_000,
|
|
],
|
|
]);
|
|
// The second read ends at 18:00:01.005, so the clock starts at the next whole second.
|
|
expect(state.write_clock).toBe("2026-10-17T18:00:02.000Z");
|
|
});
|
|
|
|
it("starts no clock on a record-order timeline, where no value is generated by a clock", () => {
|
|
const state = environmentStateViewOf(
|
|
rawCaptureEvidence(
|
|
created(THIRD_BOOK, ["GET", "/api/books/3", THIRD_BOOK]),
|
|
{
|
|
mimeType: "application/json",
|
|
timed: false,
|
|
},
|
|
),
|
|
);
|
|
expect(state.timeline).toBe("record-order");
|
|
expect(state.write_clock).toBeNull();
|
|
const plan = planOf(state, "post_books");
|
|
expect(plan).toMatchObject({ served: true, checked_record_ordinals: [4] });
|
|
// Without start times the clock fields keep the recorded values as constants.
|
|
expect(plan.rules.map(({ field }) => field)).toEqual([
|
|
"id",
|
|
"name",
|
|
"slug",
|
|
]);
|
|
});
|
|
});
|
|
|
|
describe("wider write coverage", () => {
|
|
it("drops a field from an item view's required ones once a read shows the application leaves it out", () => {
|
|
const state = stateOf(OMITTED_FIELD_ROWS);
|
|
expect(planOf(state, "post_books")).toMatchObject({ served: true });
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({
|
|
shape: "item",
|
|
fields: expect.arrayContaining(["detail"]),
|
|
});
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).not.toMatchObject({
|
|
required_fields: expect.arrayContaining(["detail"]),
|
|
});
|
|
});
|
|
|
|
it("proves an item's identity past a read that asked for some fields only, leaving that read to replay", () => {
|
|
expect(
|
|
stateOf(PROJECTED_ROWS).views.find(
|
|
(view) => view.tool === "get_books_by_id",
|
|
),
|
|
).toMatchObject({
|
|
shape: "item",
|
|
checked_record_ordinals: [1, 2],
|
|
projected_record_ordinals: [3],
|
|
});
|
|
});
|
|
|
|
it("leaves a list line that expands its books to replay, serving the create the plain list confirms", () => {
|
|
const state = stateOf(EXPANDED_LIST_ROWS);
|
|
expect(state.views.find((view) => view.tool === "get_books")).toMatchObject(
|
|
{
|
|
shape: "list",
|
|
checked_record_ordinals: [0],
|
|
projected_record_ordinals: [1],
|
|
projected_query_keys: [{ name: "expand" }],
|
|
},
|
|
);
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("leaves a list line that asks for some fields only to replay", () => {
|
|
const view = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
[
|
|
"GET",
|
|
"/api/books?fields=id,name",
|
|
[
|
|
{ id: 1, name: "First Book" },
|
|
{ id: 2, name: "Second Book" },
|
|
],
|
|
],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
]).views.find((candidate) => candidate.tool === "get_books");
|
|
expect(view).toMatchObject({
|
|
shape: "list",
|
|
checked_record_ordinals: [0],
|
|
projected_record_ordinals: [1],
|
|
projected_query_keys: [{ name: "fields" }],
|
|
});
|
|
});
|
|
|
|
it("tells a line that adds a parameter apart by the members its books show, not by the parameters it shares", () => {
|
|
const view = stateOf([
|
|
["GET", "/api/books?sort=name&limit=1", [FIRST_BOOK]],
|
|
["GET", "/api/books?sort=name&q=first", [FIRST_BOOK]],
|
|
[
|
|
"GET",
|
|
"/api/books?sort=name&with=stats&offset=1",
|
|
[{ ...SECOND_BOOK, stats: { reads: 4 } }],
|
|
],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
]).views.find((candidate) => candidate.tool === "get_books");
|
|
expect(view).toMatchObject({
|
|
shape: "list",
|
|
checked_record_ordinals: [0, 1],
|
|
projected_record_ordinals: [2],
|
|
projected_query_keys: [{ name: "with" }],
|
|
});
|
|
});
|
|
|
|
it("confirms a delete by a missing book's read on a line that expands its shelf", () => {
|
|
const state = stateOf([
|
|
...BOOK_INIT_ROWS,
|
|
["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
|
|
["DELETE", "/api/books/2", "", 204],
|
|
["GET", "/api/books/2?expand=shelf", BOOK_NOT_FOUND, 404],
|
|
]);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({
|
|
projected_record_ordinals: [3],
|
|
projected_query_keys: [{ name: "expand" }],
|
|
});
|
|
expect(planOf(state, "delete_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("serves creates whose number follows the largest held one in its digit groups", () => {
|
|
expect(planOf(stateOf(ASSET_ROWS), "post_books")).toMatchObject({
|
|
served: true,
|
|
rules: expect.arrayContaining([
|
|
{ field: "asset", rule: "sequence", scope: "collection" },
|
|
]),
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("values the application assigns", () => {
|
|
it("serves updates that renew a sent version and the ids of rewritten child rows", () => {
|
|
expect(planOf(stateOf(VERSIONED_ROWS), "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
body: { accepted: ["name", "version_id"], fixed: [] },
|
|
rules: expect.arrayContaining([
|
|
{ field: "version_id", rule: "unique" },
|
|
{ field: "chapters", rule: "renewed", pointers: ["/*/id"] },
|
|
]),
|
|
});
|
|
});
|
|
|
|
it("serves no update whose renewed values another recorded call kept, before or after the calls that renewed them", () => {
|
|
const kept = renamedBook(
|
|
versionedBook(FIRST_BOOK, 7, 8),
|
|
"Kept Version",
|
|
7,
|
|
);
|
|
const keeping: TimedCaptureRow[] = [
|
|
["PATCH", "/api/books/1", kept, 200, { name: "Kept Version" }],
|
|
["GET", "/api/books/1", kept],
|
|
];
|
|
expect(
|
|
planOf(stateOf([...VERSIONED_ROWS, ...keeping]), "patch_books_by_id"),
|
|
).toMatchObject({ served: false, reason: "unexplained-change" });
|
|
const first = renamedBook(
|
|
versionedBook(FIRST_BOOK, 1, 2),
|
|
"Kept Version",
|
|
3,
|
|
);
|
|
const renamed = versionedBook(
|
|
renamedBook(FIRST_BOOK, "Renamed Book", 5),
|
|
5,
|
|
6,
|
|
);
|
|
expect(
|
|
planOf(
|
|
stateOf([
|
|
...VERSIONED_ROWS.slice(0, 3),
|
|
["PATCH", "/api/books/1", first, 200, { name: "Kept Version" }],
|
|
["GET", "/api/books/1", first],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
renamed,
|
|
200,
|
|
{ name: "Renamed Book", version_id: numberedUuid(1) },
|
|
],
|
|
["GET", "/api/books/1", renamed],
|
|
]),
|
|
"patch_books_by_id",
|
|
),
|
|
).toMatchObject({ served: false, reason: "unexplained-change" });
|
|
});
|
|
|
|
it("serves creates that store a sent member under another name and embed it in a link", () => {
|
|
expect(planOf(stateOf(HANDLE_ROWS), "post_books")).toMatchObject({
|
|
served: true,
|
|
body: { accepted: ["name", "handle"], fixed: [] },
|
|
rules: expect.arrayContaining([
|
|
{ field: "code", rule: "copy", from: "/handle" },
|
|
{ field: "link", rule: "template", from: "code" },
|
|
]),
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("write coverage limits", () => {
|
|
const WHOLE_BOOK = ["slug", "created_at", "updated_at"];
|
|
const itemView = (rows: readonly TimedCaptureRow[]) =>
|
|
stateOf(rows).views.find((view) => view.tool === "get_books_by_id");
|
|
|
|
it("notes no omission from a read that asked for some fields, nor from one of a book the state no longer holds", () => {
|
|
const projected: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["PATCH", "/api/books/1", RENAMED_BOOK, 200, { name: "Renamed Book" }],
|
|
["GET", "/api/books/1?fields=id,name", { id: 1, name: "Renamed Book" }],
|
|
];
|
|
const tombstone: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
["DELETE", "/api/books/3", "", 204],
|
|
["GET", "/api/books/3", { id: 3, deleted: true }],
|
|
];
|
|
for (const rows of [projected, tombstone])
|
|
expect(itemView(rows)).toMatchObject({
|
|
required_fields: expect.arrayContaining(WHOLE_BOOK),
|
|
});
|
|
const partial = { id: 3, name: "Third Book" };
|
|
const created: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", partial, 201, { name: "Third Book" }],
|
|
["GET", "/api/books/3?fields=id,name", partial],
|
|
];
|
|
expect(planOf(stateOf(created), "post_books")).toMatchObject({
|
|
served: false,
|
|
});
|
|
});
|
|
|
|
it("stops requiring a field in every view of the type once a read shows it left out", () => {
|
|
const state = stateOf(DETAILED_LIST_ROWS);
|
|
expect(planOf(state, "post_books")).toMatchObject({ served: true });
|
|
const list = state.views.find((view) => view.tool === "get_books");
|
|
expect(list).toMatchObject({ fields: expect.arrayContaining(["detail"]) });
|
|
expect(list).not.toMatchObject({
|
|
required_fields: expect.arrayContaining(["detail"]),
|
|
});
|
|
});
|
|
|
|
it("leaves a read that asked for some fields only out of the gate, even where it would resynchronise a book", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["GET", "/api/books/2?fields=name", { name: "Second Book" }],
|
|
[
|
|
"PATCH",
|
|
"/api/books/2",
|
|
renamedBook(SECOND_BOOK, "Renamed", 5),
|
|
200,
|
|
{ name: "Renamed" },
|
|
],
|
|
// A redirected write leaves book 2 unknown.
|
|
["PATCH", "/api/books/2", "", 302, { name: "Renamed" }],
|
|
["GET", "/api/books/2?fields=slug", { slug: "renamed" }],
|
|
];
|
|
expect(planOf(stateOf(rows), "patch_books_by_id")).toMatchObject({
|
|
contradicted_by: null,
|
|
});
|
|
});
|
|
|
|
it("learns no update's effect from a read-back that asked for some fields only", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["PATCH", "/api/books/1", "", 204, { name: "Renamed Book" }],
|
|
["GET", "/api/books/1?fields=id,name", { id: 1, name: "Renamed Book" }],
|
|
["GET", "/api/books/1", RENAMED_BOOK],
|
|
["GET", "/api/books", [RENAMED_BOOK, SECOND_BOOK]],
|
|
];
|
|
expect(planOf(stateOf(rows), "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
observation: { ordinal: 5 },
|
|
});
|
|
});
|
|
|
|
it("confirms a delete from a read that asked for some fields and found no book", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["DELETE", "/api/books/2", "", 204],
|
|
["GET", "/api/books/2?fields=id,name", BOOK_NOT_FOUND, 404],
|
|
];
|
|
expect(planOf(stateOf(rows), "delete_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4],
|
|
});
|
|
});
|
|
|
|
it("follows a sequence past its mask's width, as serving spells it", () => {
|
|
const numbered = (id: number, asset: string): Book =>
|
|
assetBook(book(id, `Book ${String(id)}`, bookClock(id + 2)), asset);
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [numbered(1, "99-97"), numbered(2, "99-98")]],
|
|
["GET", "/api/books/1", numbered(1, "99-97")],
|
|
["GET", "/api/books/2", numbered(2, "99-98")],
|
|
];
|
|
for (const [id, asset] of [
|
|
[3, "99-99"],
|
|
[4, "100-00"],
|
|
[5, "100-01"],
|
|
] as const)
|
|
rows.push(
|
|
[
|
|
"POST",
|
|
"/api/books",
|
|
numbered(id, asset),
|
|
201,
|
|
{ name: `Book ${String(id)}` },
|
|
],
|
|
["GET", `/api/books/${String(id)}`, numbered(id, asset)],
|
|
);
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: true,
|
|
rules: expect.arrayContaining([
|
|
{ field: "asset", rule: "sequence", scope: "collection" },
|
|
]),
|
|
});
|
|
});
|
|
|
|
it("withholds creates whose later call spells its sequence otherwise than serving would", () => {
|
|
const spelled = (asset: JsonValue): TimedCaptureRow[] => {
|
|
const fourth = { ...book(4, "Fourth Book", bookClock(5)), asset };
|
|
return [
|
|
...ASSET_ROWS.slice(0, 5),
|
|
["POST", "/api/books", fourth, 201, { name: "Fourth Book" }],
|
|
["GET", "/api/books/4", fourth],
|
|
];
|
|
};
|
|
for (const asset of ["00-04", 4])
|
|
expect(planOf(stateOf(spelled(asset)), "post_books")).toMatchObject({
|
|
served: false,
|
|
});
|
|
expect(planOf(stateOf(spelled("000-004")), "post_books")).toMatchObject({
|
|
served: true,
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("omissions shown by reads the gate ignores", () => {
|
|
it("notes no omission from a read begun while the create still ran, nor from a page the collection outgrew", () => {
|
|
const first = detailedBook(FIRST_BOOK);
|
|
const second = detailedBook(SECOND_BOOK);
|
|
const running: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [first, second]],
|
|
["GET", "/api/books/1", first],
|
|
["GET", "/api/books/2", second],
|
|
// The create runs from second 3 to 4.5, so the read at second 4 may show the book before its detail.
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }, 1500],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
];
|
|
const outgrown: TimedCaptureRow[] = [
|
|
["GET", "/api/books?_start=0&_end=2", [second, first]],
|
|
["GET", "/api/books/1", first],
|
|
["GET", "/api/books/2", second],
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
|
|
// Serving answers the range from its recording once the collection outgrows it.
|
|
["GET", "/api/books?_start=0&_end=2", [THIRD_BOOK, second]],
|
|
];
|
|
const requiresDetail = {
|
|
required_fields: expect.arrayContaining(["detail"]),
|
|
};
|
|
const itemView = (rows: readonly TimedCaptureRow[]) =>
|
|
stateOf(rows).views.find((view) => view.tool === "get_books_by_id");
|
|
expect([running, outgrown].map(itemView)).toMatchObject([
|
|
requiresDetail,
|
|
requiresDetail,
|
|
]);
|
|
});
|
|
});
|
|
|
|
describe("clock spellings per view", () => {
|
|
it("serves a create that a list spelling clocks otherwise than item reads confirms", () => {
|
|
const state = stateOf(OFFSET_LIST_ROWS);
|
|
const offset = { ...ISO_SECONDS, zone: "+00:00" };
|
|
expect(state.views.find((view) => view.tool === "get_books")).toMatchObject(
|
|
{
|
|
membership: "all",
|
|
clock_formats: { created_at: offset, updated_at: offset },
|
|
},
|
|
);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).not.toHaveProperty("clock_formats");
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4, 5],
|
|
});
|
|
});
|
|
|
|
it("serves a create whose clock has a fraction where the list spelling was learned from whole seconds", () => {
|
|
const third = book(3, "Third Book", "2026-10-17T18:00:03.250Z");
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK].map(offsetListed)],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["POST", "/api/books", third, 201, { name: "Third Book" }],
|
|
["GET", "/api/books/3", third],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK, third].map(offsetListed)],
|
|
]);
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4, 5],
|
|
});
|
|
});
|
|
|
|
it("learns no spelling for a field another recorded value spells as stored, at another instant", () => {
|
|
const moved = {
|
|
...SECOND_BOOK,
|
|
created_at: "2026-10-01T09:30:00Z",
|
|
updated_at: "2026-10-01T09:30:00Z",
|
|
};
|
|
const state = stateOf([
|
|
["GET", "/api/books", [offsetListed(FIRST_BOOK), moved]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
]);
|
|
const list = state.views.find((view) => view.tool === "get_books");
|
|
expect(list).toMatchObject({ shape: "list" });
|
|
expect(list).not.toHaveProperty("clock_formats");
|
|
});
|
|
|
|
it("learns no spelling for a field the view spells both ways", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, offsetListed(SECOND_BOOK)]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
]);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books"),
|
|
).not.toHaveProperty("clock_formats");
|
|
});
|
|
});
|
|
|
|
describe("unserved write plans", () => {
|
|
it("names a write to no state type and a tool with no successful call", () => {
|
|
expect(
|
|
verdicts([
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/session", { token: "t0" }, 200, { user: "ada" }],
|
|
["POST", "/api/books", { errors: ["name"] }, 422, { name: "" }],
|
|
["DELETE", "/api/books/9", BOOK_NOT_FOUND, 404],
|
|
]),
|
|
).toEqual({
|
|
post_session: "no-state-target",
|
|
post_books: "no-call",
|
|
delete_books_by_id: "no-call",
|
|
});
|
|
});
|
|
|
|
it("refuses a create whose request body cannot enter the state", () => {
|
|
/** The create of the third book sending `sent`, or no body, then a read that shows it. */
|
|
const sending = (...sent: [] | [JsonValue]): TimedCaptureRow[] => [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", THIRD_BOOK, 201, ...sent],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
];
|
|
const recorded = (mimeType: string, text: string) =>
|
|
environmentStateViewOf(
|
|
rawCaptureEvidence(sending(text), { mimeType, timed: true }),
|
|
);
|
|
for (const state of [
|
|
stateOf(sending()),
|
|
stateOf(sending([{ name: "Third Book" }])),
|
|
recorded("application/x-www-form-urlencoded", "name=Third+Book"),
|
|
recorded(
|
|
"application/json",
|
|
'{"name":"Third Book","copies":12345678901234567890}',
|
|
),
|
|
])
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: false,
|
|
reason: "body-unusable",
|
|
exemplar_ordinal: null,
|
|
});
|
|
});
|
|
|
|
it("reports no observation when neither the response nor a read before the next write shows the entity", () => {
|
|
expect(verdicts(created({ ok: true }))).toEqual({
|
|
post_books: "no-observation",
|
|
});
|
|
// The read of the created book comes after the next write; the update names a book never held.
|
|
expect(
|
|
verdicts(
|
|
created(
|
|
"",
|
|
[
|
|
"PATCH",
|
|
"/api/books/7",
|
|
{ id: 7, name: "Seventh" },
|
|
200,
|
|
{ name: "Seventh" },
|
|
],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
),
|
|
),
|
|
).toEqual({
|
|
post_books: "no-observation",
|
|
patch_books_by_id: "no-observation",
|
|
});
|
|
});
|
|
|
|
it("reports an update that changed an unsent field no clock, increment or slug explains", () => {
|
|
const changed = { ...RENAMED_AT_3, slug: "first-book-v2" };
|
|
expect(verdicts(rename(changed, ["GET", "/api/books/1", changed]))).toEqual(
|
|
{
|
|
patch_books_by_id: "unexplained-change",
|
|
},
|
|
);
|
|
});
|
|
|
|
it("names the first later read that contradicts a write", () => {
|
|
const other = renamedBook(RENAMED_AT_3, "Other Name", 3);
|
|
const plan = planOf(
|
|
stateOf(
|
|
rename(
|
|
RENAMED_AT_3,
|
|
["GET", "/api/books/1", other],
|
|
["GET", "/api/books/1", other],
|
|
),
|
|
),
|
|
"patch_books_by_id",
|
|
);
|
|
expect(plan).toMatchObject({
|
|
served: false,
|
|
reason: "contradicted",
|
|
contradicted_by: 4,
|
|
checked_record_ordinals: [],
|
|
});
|
|
});
|
|
|
|
it("blames a related write when a book no write touched changed after it", () => {
|
|
const plan = planOf(
|
|
stateOf(
|
|
created(
|
|
THIRD_BOOK,
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
[
|
|
"GET",
|
|
"/api/books/2",
|
|
renamedBook(SECOND_BOOK, "Second Edition", 5),
|
|
],
|
|
),
|
|
),
|
|
"post_books",
|
|
);
|
|
// The create's own read confirmed it, but the changed sibling outweighs that.
|
|
expect(plan).toMatchObject({
|
|
served: false,
|
|
reason: "side-effect",
|
|
checked_record_ordinals: [4],
|
|
contradicted_by: null,
|
|
});
|
|
});
|
|
|
|
it("leaves a write that no later read checks unconfirmed", () => {
|
|
expect(planOf(stateOf(created(THIRD_BOOK)), "post_books")).toMatchObject({
|
|
served: false,
|
|
reason: "unconfirmed",
|
|
exemplar_ordinal: 3,
|
|
checked_record_ordinals: [],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("delete confirmation", () => {
|
|
it("confirms a delete by a later 404, 400 or JSON null item read", () => {
|
|
const absences: [body: JsonValue, status: number][] = [
|
|
[BOOK_NOT_FOUND, 404],
|
|
[{ detail: "Invalid book id." }, 400],
|
|
[null, 200],
|
|
];
|
|
for (const [body, status] of absences)
|
|
expect(
|
|
planOf(
|
|
stateOf([
|
|
...BOOK_INIT_ROWS,
|
|
["DELETE", "/api/books/2", "", 204],
|
|
["GET", "/api/books/2", body, status],
|
|
]),
|
|
"delete_books_by_id",
|
|
),
|
|
).toMatchObject({ served: true, checked_record_ordinals: [4] });
|
|
});
|
|
it("withholds a delete whose recorded answer shows fields no initial entity holds", () => {
|
|
const answered = (previous: JsonValue) =>
|
|
planOf(
|
|
stateOf([
|
|
...BOOK_INIT_ROWS,
|
|
["DELETE", "/api/books/2", { deleted: true, previous }, 200],
|
|
["GET", "/api/books/2", BOOK_NOT_FOUND, 404],
|
|
]),
|
|
"delete_books_by_id",
|
|
);
|
|
// An edit view of the book: the read views never showed its draft field.
|
|
expect(answered({ ...SECOND_BOOK, draft: false })).toMatchObject({
|
|
served: false,
|
|
reason: "incomplete-entities",
|
|
checked_record_ordinals: [4],
|
|
});
|
|
expect(answered(SECOND_BOOK)).toMatchObject({
|
|
served: true,
|
|
response: { shape: "entity", pointer: "/previous" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("update answers", () => {
|
|
it("serves an update whose recorded answer shows a field only the update writes", () => {
|
|
const summary = (name: string) => [
|
|
{ id: 1, name },
|
|
{ id: 2, name: "B" },
|
|
];
|
|
// No read showed a note before the update sent one, which its answer echoes.
|
|
const plan = planOf(
|
|
stateOf([
|
|
["GET", "/api/books", summary("A")],
|
|
["GET", "/api/books/1", { id: 1, name: "A" }],
|
|
["GET", "/api/books/2", { id: 2, name: "B" }],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
{ id: 1, name: "Z", note: "n" },
|
|
200,
|
|
{ name: "Z", note: "n" },
|
|
],
|
|
["GET", "/api/books", summary("Z")],
|
|
]),
|
|
"patch_books_by_id",
|
|
);
|
|
expect(plan).toMatchObject({
|
|
served: true,
|
|
reason: null,
|
|
response: { shape: "entity", pointer: "" },
|
|
checked_record_ordinals: [4],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("insert rules", () => {
|
|
it("learns where a create inserts from the recorded collection order", () => {
|
|
// Listed by name, while neither identities nor clocks are in order.
|
|
const shelf = [
|
|
book(3, "Alpha", "2026-10-01T10:00:00Z"),
|
|
book(1, "Delta", "2026-10-01T09:00:00Z"),
|
|
book(2, "Zulu", "2026-10-01T11:00:00Z"),
|
|
];
|
|
const mike = book(4, "Mike", bookClock(6));
|
|
const state = stateOf([
|
|
["GET", "/api/books", shelf],
|
|
...shelf.map((entry): TimedCaptureRow => [
|
|
"GET",
|
|
`/api/books/${String(entry.id)}`,
|
|
entry,
|
|
]),
|
|
["GET", "/api/books", shelf],
|
|
["GET", "/api/books", shelf],
|
|
["POST", "/api/books", mike, 201, { name: "Mike" }],
|
|
["GET", "/api/books", [shelf[0]!, shelf[1]!, mike, shelf[2]!]],
|
|
]);
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
insert: { rule: "sorted", field: "name", direction: "ascending" },
|
|
checked_record_ordinals: [7],
|
|
});
|
|
});
|
|
|
|
it("takes the position a later list shows when the recorded order admits several", () => {
|
|
const zed = book(3, "Zed", bookClock(3));
|
|
const plan = planOf(
|
|
stateOf(
|
|
created(zed, ["GET", "/api/books", [zed, FIRST_BOOK, SECOND_BOOK]]),
|
|
),
|
|
"post_books",
|
|
);
|
|
expect(plan).toMatchObject({
|
|
served: true,
|
|
insert: { rule: "first" },
|
|
checked_record_ordinals: [4],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("unmodelled writes", () => {
|
|
const shelved = (entry: Book, archived = false): Book => ({
|
|
...entry,
|
|
archived,
|
|
});
|
|
/** The rename, an archive the gate does not model when `archive` is set, then a read of both changes. */
|
|
const archivedAfterRename = (archive: boolean) =>
|
|
stateOf([
|
|
["GET", "/api/books", [shelved(FIRST_BOOK), shelved(SECOND_BOOK)]],
|
|
["GET", "/api/books/1", shelved(FIRST_BOOK)],
|
|
["GET", "/api/books/2", shelved(SECOND_BOOK)],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
shelved(RENAMED_AT_3),
|
|
200,
|
|
{ name: "Renamed Book" },
|
|
],
|
|
...(archive
|
|
? [
|
|
[
|
|
"POST",
|
|
"/api/books/1/archive",
|
|
{ archived: true },
|
|
200,
|
|
{},
|
|
] as TimedCaptureRow,
|
|
]
|
|
: []),
|
|
["GET", "/api/books/1", shelved(RENAMED_AT_3, true)],
|
|
]);
|
|
|
|
it("confirms an update on the members it sent when an unmodelled write also changed the entity", () => {
|
|
const state = archivedAfterRename(true);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
contradicted_by: null,
|
|
});
|
|
expect(planOf(state, "post_books_archive_by_id")).toMatchObject({
|
|
effect: "none",
|
|
reason: "no-state-target",
|
|
});
|
|
// With no unmodelled write the same read contradicts the update.
|
|
expect(
|
|
planOf(archivedAfterRename(false), "patch_books_by_id"),
|
|
).toMatchObject({
|
|
reason: "contradicted",
|
|
contradicted_by: 4,
|
|
});
|
|
});
|
|
|
|
it("does not blame a modelled write for a check that fails after an unmodelled write", () => {
|
|
const changedSibling = renamedBook(SECOND_BOOK, "Second Edition", 4);
|
|
const reindex: TimedCaptureRow = [
|
|
"POST",
|
|
"/api/jobs/reindex",
|
|
{ queued: true },
|
|
202,
|
|
{},
|
|
];
|
|
const list: TimedCaptureRow = [
|
|
"GET",
|
|
"/api/books",
|
|
[RENAMED_AT_3, changedSibling],
|
|
];
|
|
expect(
|
|
planOf(stateOf(rename(RENAMED_AT_3, list)), "patch_books_by_id"),
|
|
).toMatchObject({
|
|
reason: "contradicted",
|
|
contradicted_by: 4,
|
|
});
|
|
expect(
|
|
planOf(stateOf(rename(RENAMED_AT_3, reindex, list)), "patch_books_by_id"),
|
|
).toMatchObject({ reason: "unconfirmed", contradicted_by: null });
|
|
// A create wrote every field, so after an unmodelled write a differing read checks none of them.
|
|
const reslugged = { ...THIRD_BOOK, slug: "third-book-1" };
|
|
const read: TimedCaptureRow = ["GET", "/api/books/3", reslugged];
|
|
expect(
|
|
planOf(stateOf(created(THIRD_BOOK, read)), "post_books"),
|
|
).toMatchObject({
|
|
reason: "contradicted",
|
|
contradicted_by: 4,
|
|
});
|
|
expect(
|
|
planOf(stateOf(created(THIRD_BOOK, reindex, read)), "post_books"),
|
|
).toMatchObject({
|
|
reason: "unconfirmed",
|
|
contradicted_by: null,
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("observation from a later read", () => {
|
|
it("observes a created entity in the first later item read when the response names only its identity", () => {
|
|
const later: TimedCaptureRow[] = [
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK, THIRD_BOOK]],
|
|
];
|
|
const bare = planOf(stateOf(created({ id: 3 }, ...later)), "post_books");
|
|
// The read that showed the entity does not check the create; the later list does.
|
|
expect(bare).toMatchObject({
|
|
served: true,
|
|
exemplar_ordinal: 3,
|
|
observation: { ordinal: 4, pointer: "" },
|
|
response: { ordinal: 3, shape: "entity", pointer: "" },
|
|
checked_record_ordinals: [5],
|
|
});
|
|
const named = planOf(
|
|
stateOf(created({ created_id: 3 }, ...later)),
|
|
"post_books",
|
|
);
|
|
expect(named).toMatchObject({
|
|
served: true,
|
|
observation: { ordinal: 4, pointer: "" },
|
|
response: { ordinal: 3, shape: "identity", pointer: "/created_id" },
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("list lines", () => {
|
|
it("confirms the same create when a learned filter repeats identical decoded query values", () => {
|
|
for (const query of [
|
|
"shelf=a&shelf=a",
|
|
"shelf=%61&shelf=a",
|
|
"shelf=a&include=all&shelf=a",
|
|
]) {
|
|
const rows = QUERY_ROWS.map((row, index): TimedCaptureRow => {
|
|
if (index !== QUERY_ROWS.length - 1) return row;
|
|
const [method, , ...response] = row;
|
|
return [method, `/api/books?${query}`, ...response];
|
|
});
|
|
expect(planOf(stateOf(rows), "post_books"), query).toMatchObject({
|
|
served: true,
|
|
contradicted_by: null,
|
|
});
|
|
}
|
|
});
|
|
|
|
it("lists every entity on a line that lists its whole collection, though another line of the tool is filtered", () => {
|
|
const state = stateOf(LIST_LINE_ROWS);
|
|
expect(state.views.find((view) => view.tool === "get_books")).toMatchObject(
|
|
{
|
|
shape: "list",
|
|
pointer: "/content",
|
|
membership: "recorded",
|
|
all_record_ordinals: [0],
|
|
counters: ["numberOfElements", "totalElements"],
|
|
checked_record_ordinals: [0, 1],
|
|
},
|
|
);
|
|
// The whole list after the create shows the created book, which confirms it.
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5, 6],
|
|
});
|
|
});
|
|
|
|
it("confirms no create by a whole list taken after a read showed its entity gone", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
|
|
// A redirected delete is not modelled; the read after it shows the book gone.
|
|
["DELETE", "/api/books/3", "", 302],
|
|
["GET", "/api/books/3", BOOK_NOT_FOUND, 404],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: false,
|
|
reason: "unconfirmed",
|
|
});
|
|
});
|
|
|
|
it("confirms no create by a whole list after an item read showed nothing of its entity", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
|
|
// An unmodelled write elsewhere may explain the next read, which the state then takes.
|
|
["POST", "/api/exports", { queued: true }, 202, { format: "csv" }],
|
|
["GET", "/api/books/3", null],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: false,
|
|
checked_record_ordinals: [],
|
|
});
|
|
});
|
|
|
|
it("names no line when every line lists its whole collection, or none does", () => {
|
|
const listOf = (rows: readonly TimedCaptureRow[]) =>
|
|
stateOf(rows).views.find((view) => view.tool === "get_books");
|
|
const whole = listOf(LIST_LINE_ROWS.filter((_, index) => index !== 1));
|
|
expect(whole).toMatchObject({ membership: "all" });
|
|
expect(whole).not.toHaveProperty("all_record_ordinals");
|
|
expect(listOf(LIST_LINE_ROWS.slice(1))).not.toHaveProperty(
|
|
"all_record_ordinals",
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("list queries", () => {
|
|
it("learns a filter, a search, a sort and an inert flag from the lines the whole collection does not explain", () => {
|
|
const state = stateOf(QUERY_ROWS);
|
|
expect(state.views.find((view) => view.tool === "get_books")).toMatchObject(
|
|
{
|
|
shape: "list",
|
|
membership: "recorded",
|
|
all_record_ordinals: [0],
|
|
query: {
|
|
parameters: {
|
|
shelf: { role: "filter", field: "shelf" },
|
|
q: { role: "search", fields: ["name", "slug"] },
|
|
sort: { role: "sort" },
|
|
include: { role: "inert", values: ["all"] },
|
|
},
|
|
record_ordinals: [1, 2, 3, 4],
|
|
totals: [],
|
|
},
|
|
checked_record_ordinals: [0, 1, 2, 3, 4],
|
|
},
|
|
);
|
|
// The shelf filter after the create lists the created book, which confirms it.
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [8],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("list reads with query values no line recorded", () => {
|
|
it("serves no create that a filtered read on a new value omits, as serving would list it", () => {
|
|
const third = { ...book(3, "Third Book", bookClock(7)), shelf: "b" };
|
|
const rows: TimedCaptureRow[] = [
|
|
...QUERY_ROWS.slice(0, 7),
|
|
["POST", "/api/books", third, 201, { name: "Third Book", shelf: "b" }],
|
|
["GET", "/api/books/3", third],
|
|
// Serving evaluates `shelf=b` over the state, which lists the created book; the recording does not.
|
|
["GET", "/api/books?shelf=b", [QUERY_ROWS[6]![2] as Book]],
|
|
];
|
|
// The item read confirmed the book, so the failing filtered read blames the related create as a side effect.
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: false,
|
|
reason: "side-effect",
|
|
});
|
|
});
|
|
|
|
it("checks what the state answers on a line the read did not name, not the envelope that line's own call recorded", () => {
|
|
const first = { ...FIRST_BOOK, shelf: "a" };
|
|
const second = { ...SECOND_BOOK, shelf: "b" };
|
|
const third = { ...book(3, "Third Book", bookClock(4)), shelf: "c" };
|
|
// Each page links the next under its own query.
|
|
const page = (query: string, books: readonly Book[]) => ({
|
|
data: [...books],
|
|
next: `/api/books?${query}offset=20`,
|
|
});
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", page("", [first, second])],
|
|
["GET", "/api/books?shelf=a", page("shelf=a&", [first])],
|
|
["GET", "/api/books/1", first],
|
|
["GET", "/api/books/2", second],
|
|
["POST", "/api/books", third, 201, { name: "Third Book", shelf: "c" }],
|
|
// Serving lists `shelf=c` from the state in the `shelf=a` line's envelope, whose link names shelf a.
|
|
["GET", "/api/books?shelf=c", page("shelf=c&", [third])],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("checks a recorded-member line with the total it recorded, as serving answers it", () => {
|
|
const envelope = (books: readonly Book[]) => ({
|
|
items: [...books],
|
|
total: 3,
|
|
});
|
|
const renamed = renamedBook(SECOND_BOOK, "Renamed Second", 6);
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", envelope([FIRST_BOOK, SECOND_BOOK, THIRD_BOOK])],
|
|
["GET", "/api/books?limit=1", envelope([FIRST_BOOK])],
|
|
// A cursor no role explains keeps its recorded member and total.
|
|
["GET", "/api/books?cursor=abc", envelope([FIRST_BOOK])],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
["PATCH", "/api/books/2", renamed, 200, { name: "Renamed Second" }],
|
|
["GET", "/api/books/2", renamed],
|
|
["GET", "/api/books?cursor=abc", envelope([FIRST_BOOK])],
|
|
// Failing that read would taint book 1 and leave its confirmed delete unserved.
|
|
["DELETE", "/api/books/1", "", 204],
|
|
["GET", "/api/books/1", BOOK_NOT_FOUND, 404],
|
|
];
|
|
const state = stateOf(rows);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({ served: true });
|
|
expect(planOf(state, "delete_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [10],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("list reads on a line they did not name", () => {
|
|
const first = { ...FIRST_BOOK, shelf: "a" };
|
|
const second = { ...SECOND_BOOK, shelf: "b" };
|
|
|
|
it("checks a read with no query on a query line by that line's recorded members, as serving lists them", () => {
|
|
const third = { ...book(3, "Third Book", bookClock(3)), shelf: "c" };
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books?shelf=a", [first]],
|
|
["GET", "/api/books/1", first],
|
|
["GET", "/api/books/2", second],
|
|
["POST", "/api/books", third, 201, { name: "Third Book", shelf: "c" }],
|
|
// Serving answers this call on the `shelf=a` line with its recorded book, not the created one.
|
|
["GET", "/api/books", [first, second, third]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: false,
|
|
checked_record_ordinals: [],
|
|
});
|
|
});
|
|
|
|
it("confirms no delete by a filtered read on another value, whose answer never listed the deleted book", () => {
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [first, second]],
|
|
["GET", "/api/books?shelf=a", [first]],
|
|
["GET", "/api/books/1", first],
|
|
["GET", "/api/books/2", second],
|
|
["DELETE", "/api/books/1", "", 204],
|
|
["GET", "/api/books?shelf=b", [second]],
|
|
];
|
|
expect(planOf(stateOf(rows), "delete_books_by_id")).toMatchObject({
|
|
served: false,
|
|
reason: "unconfirmed",
|
|
checked_record_ordinals: [],
|
|
});
|
|
});
|
|
|
|
it("lets a sorted read whose values tie fix a create's position, as its order shows where the create put it", () => {
|
|
const shelved = (id: number, name: string, shelf: string, at: number) => ({
|
|
...book(id, name, bookClock(at)),
|
|
shelf,
|
|
});
|
|
const beta = shelved(1, "Beta", "a", 0);
|
|
const mike = shelved(2, "Mike", "b", 1);
|
|
const zulu = shelved(3, "Zulu", "a", 2);
|
|
const alpha = shelved(4, "Alpha", "a", 6);
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [beta, mike, zulu]],
|
|
["GET", "/api/books?shelf=a", [beta, zulu]],
|
|
["GET", "/api/books?sort=-id", [zulu, mike, beta]],
|
|
["GET", "/api/books/1", beta],
|
|
["GET", "/api/books/2", mike],
|
|
["GET", "/api/books/3", zulu],
|
|
["POST", "/api/books", alpha, 201, { name: "Alpha", shelf: "a" }],
|
|
// Every match shares the shelf, so the order is the state's: the create went last.
|
|
["GET", "/api/books?shelf=a&sort=shelf", [beta, zulu, alpha]],
|
|
// A name order would put it first, which the read before contradicts.
|
|
["GET", "/api/books", [alpha, beta, mike, zulu]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: false,
|
|
contradicted_by: 8,
|
|
});
|
|
});
|
|
|
|
it("leaves a create's position open after a sorted read that ties other books but not the created one", () => {
|
|
const shelved = (id: number, name: string, shelf: string, at: number) => ({
|
|
...book(id, name, bookClock(at)),
|
|
category: "x",
|
|
shelf,
|
|
});
|
|
const beta = shelved(1, "Beta", "a", 0);
|
|
const mike = { ...shelved(2, "Mike", "b", 1), category: "y" };
|
|
const zulu = shelved(3, "Zulu", "a", 2);
|
|
const alpha = shelved(4, "Alpha", "c", 6);
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [beta, mike, zulu]],
|
|
["GET", "/api/books?category=x", [beta, zulu]],
|
|
["GET", "/api/books?sort=-id", [zulu, mike, beta]],
|
|
["GET", "/api/books/1", beta],
|
|
["GET", "/api/books/2", mike],
|
|
["GET", "/api/books/3", zulu],
|
|
[
|
|
"POST",
|
|
"/api/books",
|
|
alpha,
|
|
201,
|
|
{ name: "Alpha", category: "x", shelf: "c" },
|
|
],
|
|
// Beta and Zulu tie on shelf a, but the created book's shelf c sorts it last wherever it was put.
|
|
["GET", "/api/books?category=x&sort=shelf", [beta, zulu, alpha]],
|
|
["GET", "/api/books", [alpha, beta, mike, zulu]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [7, 8],
|
|
insert: { rule: "sorted", field: "name", direction: "ascending" },
|
|
});
|
|
});
|
|
|
|
it("leaves a create's position open after a sorted read, for a later whole list to settle", () => {
|
|
const shelved = (id: number, name: string, shelf: string, at: number) => ({
|
|
...book(id, name, bookClock(at)),
|
|
shelf,
|
|
});
|
|
const beta = shelved(1, "Beta", "a", 0);
|
|
const mike = shelved(2, "Mike", "b", 1);
|
|
const zulu = shelved(3, "Zulu", "a", 2);
|
|
const alpha = shelved(4, "Alpha", "a", 6);
|
|
const rows: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [beta, mike, zulu]],
|
|
["GET", "/api/books?shelf=a", [beta, zulu]],
|
|
["GET", "/api/books?sort=-id", [zulu, mike, beta]],
|
|
["GET", "/api/books/1", beta],
|
|
["GET", "/api/books/2", mike],
|
|
["GET", "/api/books/3", zulu],
|
|
["POST", "/api/books", alpha, 201, { name: "Alpha", shelf: "a" }],
|
|
// The sorted shelf passes wherever the create placed its book; the whole list orders by name.
|
|
["GET", "/api/books?shelf=a&sort=-id", [alpha, zulu, beta]],
|
|
["GET", "/api/books", [alpha, beta, mike, zulu]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [7, 8],
|
|
insert: { rule: "sorted", field: "name", direction: "ascending" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("what a list query read shows of writes", () => {
|
|
const shelved = (id: number, name: string, shelf: string, at: number) => ({
|
|
...book(id, name, bookClock(at)),
|
|
shelf,
|
|
});
|
|
const beta = shelved(1, "Beta", "a", 0);
|
|
const mike = shelved(2, "Mike", "b", 1);
|
|
const zulu = shelved(3, "Zulu", "a", 2);
|
|
const INIT: TimedCaptureRow[] = [
|
|
["GET", "/api/books", [beta, mike, zulu]],
|
|
["GET", "/api/books?shelf=a", [beta, zulu]],
|
|
["GET", "/api/books/1", beta],
|
|
["GET", "/api/books/2", mike],
|
|
["GET", "/api/books/3", zulu],
|
|
];
|
|
|
|
it("blames a write that moved a book off a filter whose failed read still lists it", () => {
|
|
const moved = { ...beta, shelf: "b", updated_at: bookClock(5) };
|
|
const renamed = renamedBook(zulu, "Zulu Two", 7);
|
|
const rows: TimedCaptureRow[] = [
|
|
...INIT,
|
|
["PATCH", "/api/books/1", moved, 200, { shelf: "b" }],
|
|
["PUT", "/api/books/3", renamed, 200, { name: "Zulu Two", shelf: "a" }],
|
|
// Serving lists Zulu alone on shelf a; the recording still lists the moved book there.
|
|
["GET", "/api/books?shelf=a", [beta, renamed]],
|
|
["GET", "/api/books/1", moved],
|
|
];
|
|
const state = stateOf(rows);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: false,
|
|
contradicted_by: 7,
|
|
});
|
|
expect(planOf(state, "put_books_by_id")).toMatchObject({
|
|
served: false,
|
|
contradicted_by: 7,
|
|
});
|
|
});
|
|
|
|
it("leaves a create's position open after a filter that lists only its book, for a later whole list to settle", () => {
|
|
const alpha = shelved(4, "Alpha", "c", 5);
|
|
const rows: TimedCaptureRow[] = [
|
|
...INIT,
|
|
["POST", "/api/books", alpha, 201, { name: "Alpha", shelf: "c" }],
|
|
// A lone match shows nothing of where the create put it among the other books.
|
|
["GET", "/api/books?shelf=c", [alpha]],
|
|
["GET", "/api/books", [alpha, beta, mike, zulu]],
|
|
];
|
|
expect(planOf(stateOf(rows), "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [6, 7],
|
|
insert: { rule: "sorted", field: "name", direction: "ascending" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("calls the capture shows reading only", () => {
|
|
const LOOKUP: TimedCaptureRow = [
|
|
"POST",
|
|
"/api/books/ids",
|
|
[FIRST_BOOK, SECOND_BOOK],
|
|
200,
|
|
{ ids: [1, 2] },
|
|
];
|
|
|
|
it("replays a lookup POST and plans no write for it", () => {
|
|
const state = stateOf([...BOOK_INIT_ROWS, LOOKUP]);
|
|
expect(state.writes.map((plan) => plan.tool)).not.toContain(
|
|
"post_books_ids",
|
|
);
|
|
expect(state.views).toContainEqual({
|
|
tool: "post_books_ids",
|
|
shape: "recorded",
|
|
reason: "query-body",
|
|
});
|
|
});
|
|
|
|
it("keeps a read after a lookup POST among the initial recordings", () => {
|
|
// The lookup changes nothing, so the second book's only read, after it, still seeds the state.
|
|
const state = stateOf([
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
LOOKUP,
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
]);
|
|
expect(state.entities.map((entity) => entity.id).sort()).toEqual([
|
|
"1",
|
|
"2",
|
|
]);
|
|
});
|
|
});
|
|
|
|
describe("types whose reads disagree across a write", () => {
|
|
const recipe = (id: number, name: string, views: number) => ({
|
|
id,
|
|
name,
|
|
views,
|
|
});
|
|
|
|
it("plans a type its reads disagree on across an unrelated write from the reads before it, and serves its create", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/recipes", [recipe(1, "Soup", 1), recipe(2, "Stew", 4)]],
|
|
["GET", "/api/recipes/1", recipe(1, "Soup", 1)],
|
|
// Logging a view bumps the counter, so the reads after it disagree with those before.
|
|
["POST", "/api/view-log", { ok: true }, 200, { recipe: 1 }],
|
|
["GET", "/api/recipes/1", recipe(1, "Soup", 2)],
|
|
["POST", "/api/recipes", recipe(3, "Broth", 0), 201, { name: "Broth" }],
|
|
["GET", "/api/recipes/3", recipe(3, "Broth", 0)],
|
|
]);
|
|
expect(state.types).toMatchObject([
|
|
{ collection_template: "/api/recipes", init_before_ordinal: 2 },
|
|
]);
|
|
expect(planOf(state, "post_recipes")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("ends a type's state at the earlier of a write its reads disagree across and a create that made one of its entities", () => {
|
|
const rows = (disagreeFirst: boolean): TimedCaptureRow[] => {
|
|
const disagreement: TimedCaptureRow[] = [
|
|
["POST", "/api/view-log", { ok: true }, 200, { recipe: 1 }],
|
|
["GET", "/api/recipes/1", recipe(1, "Soup", 2)],
|
|
];
|
|
const creation: TimedCaptureRow[] = [
|
|
["POST", "/api/imports", { id: "rcp-0042" }, 201, { name: "Broth" }],
|
|
["GET", "/api/recipes", [recipe(1, "Soup", 1), { id: "rcp-0042" }]],
|
|
];
|
|
return [
|
|
["GET", "/api/recipes", [recipe(1, "Soup", 1)]],
|
|
["GET", "/api/recipes/1", recipe(1, "Soup", 1)],
|
|
...(disagreeFirst
|
|
? [...disagreement, ...creation]
|
|
: [...creation, ...disagreement]),
|
|
];
|
|
};
|
|
expect(stateOf(rows(true)).types).toMatchObject([
|
|
{ init_before_ordinal: 2 },
|
|
]);
|
|
expect(stateOf(rows(false)).types).toMatchObject([
|
|
{ init_before_ordinal: 2 },
|
|
]);
|
|
});
|
|
});
|
|
|
|
const note = (id: number, title: string) => ({ id, title });
|
|
const A = note(1001, "Alpha");
|
|
const B = note(1002, "Beta");
|
|
const C = note(1003, "Gamma");
|
|
const notesOf = (state: StateView) =>
|
|
state.entities
|
|
.filter((entity) => entity.type === "/api/notes")
|
|
.map((entity) => entity.id);
|
|
/** Two notes read, the given exchanges, then a POST elsewhere whose returned id the notes are read under. */
|
|
const published = (before: readonly TimedCaptureRow[]): TimedCaptureRow[] => [
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
...before,
|
|
["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes/1003", C],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
];
|
|
|
|
describe("creates read under another path", () => {
|
|
it("plans a POST to another path as a create into the type its returned id is first read under", () => {
|
|
const state = stateOf(published([]));
|
|
expect(planOf(state, "post_drafts_publish")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
collection: "/api/notes",
|
|
});
|
|
expect(notesOf(state)).toEqual(["1001", "1002"]);
|
|
});
|
|
|
|
it("ends a type's initial reads at a POST elsewhere that made one of its entities", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/notes", [A, B]],
|
|
["POST", "/api/imports", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
]);
|
|
expect(notesOf(state)).toEqual(["1001", "1002"]);
|
|
expect(
|
|
state.types.find((type) => type.collection_template === "/api/notes"),
|
|
).toMatchObject({ init_before_ordinal: 1 });
|
|
});
|
|
|
|
it("links no create whose returned id a read showed before it", () => {
|
|
const shownBefore = published([
|
|
[
|
|
"PATCH",
|
|
"/api/notes/1001",
|
|
note(1001, "Alpha 2"),
|
|
200,
|
|
{ title: "Alpha 2" },
|
|
],
|
|
["GET", "/api/notes/1003", C],
|
|
]);
|
|
expect(planOf(stateOf(shownBefore), "post_drafts_publish")).toMatchObject({
|
|
effect: "none",
|
|
reason: "no-state-target",
|
|
});
|
|
expect(planOf(stateOf(published([])), "post_drafts_publish")).toMatchObject(
|
|
{ effect: "create" },
|
|
);
|
|
});
|
|
|
|
/** A create linked under project 11, then a call for project 12, whose note a later item read and delete show. */
|
|
const otherProject = (): TimedCaptureRow[] => {
|
|
const D = note(1004, "Delta");
|
|
return [
|
|
["GET", "/api/projects/11/notes", [A, B]],
|
|
["GET", "/api/projects/11/notes/1001", A],
|
|
["GET", "/api/projects/11/notes/1002", B],
|
|
[
|
|
"POST",
|
|
"/api/projects/11/publish",
|
|
{ id: 1003 },
|
|
201,
|
|
{ title: "Gamma" },
|
|
],
|
|
["GET", "/api/projects/11/notes/1003", C],
|
|
["GET", "/api/projects/11/notes", [A, B, C]],
|
|
["POST", "/api/projects/12/publish", D, 201, { title: "Delta" }],
|
|
["GET", "/api/projects/12/notes/1004", D],
|
|
["GET", "/api/projects/11/notes", [A, B, C]],
|
|
["DELETE", "/api/projects/12/notes/1004", "", 204],
|
|
["GET", "/api/projects/12/notes/1004", { error: "Not found" }, 404],
|
|
];
|
|
};
|
|
|
|
it("puts no linked create's call that sends other path arguments into the linked collection", () => {
|
|
// Project 12's note never reaches project 11, so the later read of project 11 confirms the create.
|
|
expect(
|
|
planOf(stateOf(otherProject()), "post_projects_publish_by_id"),
|
|
).toMatchObject({
|
|
served: true,
|
|
collection: "/api/projects/11/notes",
|
|
checked_record_ordinals: [5],
|
|
contradicted_by: null,
|
|
});
|
|
});
|
|
|
|
it("takes the entity such a call made when a read first shows it", () => {
|
|
expect(
|
|
planOf(stateOf(otherProject()), "delete_projects_notes_by_id_id_2"),
|
|
).toMatchObject({ served: true, checked_record_ordinals: [10] });
|
|
});
|
|
|
|
it("links a create whose response names a short id under an identity member", () => {
|
|
const [one, two, three] = [
|
|
note(1, "Alpha"),
|
|
note(2, "Beta"),
|
|
note(3, "Gamma"),
|
|
];
|
|
const rows = (response: JsonValue): TimedCaptureRow[] => [
|
|
["GET", "/api/notes", [one, two]],
|
|
["GET", "/api/notes/1", one],
|
|
["GET", "/api/notes/2", two],
|
|
["POST", "/api/drafts/publish", response, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes/3", three],
|
|
["GET", "/api/notes", [one, two, three]],
|
|
];
|
|
expect(
|
|
planOf(stateOf(rows({ id: 3 })), "post_drafts_publish"),
|
|
).toMatchObject({ effect: "create", target: "/api/notes", served: true });
|
|
// A bare or unnamed short scalar may count rather than name, so it links nothing.
|
|
for (const response of [3, { created: 3 }])
|
|
expect(
|
|
planOf(stateOf(rows(response)), "post_drafts_publish"),
|
|
).toMatchObject({ effect: "none", reason: "no-state-target" });
|
|
});
|
|
|
|
it("links a short id to no type that no read showed before the call", () => {
|
|
// Another type's id 1 may be the one the call returned, so the notes keep their initial reads.
|
|
const [one, two] = [note(1, "Alpha"), note(2, "Beta")];
|
|
const state = stateOf([
|
|
["POST", "/api/imports", { id: 1 }, 201, { source: "csv" }],
|
|
["GET", "/api/notes/1", one],
|
|
["GET", "/api/notes", [one, two]],
|
|
]);
|
|
expect(planOf(state, "post_imports")).toMatchObject({
|
|
effect: "none",
|
|
reason: "no-state-target",
|
|
});
|
|
expect(notesOf(state)).toEqual(["1", "2"]);
|
|
});
|
|
|
|
it("links no create whose returned id the initial state holds", () => {
|
|
const held = stateOf([
|
|
["GET", "/api/notes", [A, B, C]],
|
|
["GET", "/api/notes/1001", A],
|
|
["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes/1003", C],
|
|
]);
|
|
expect(planOf(held, "post_drafts_publish")).toMatchObject({
|
|
effect: "none",
|
|
reason: "no-state-target",
|
|
});
|
|
expect(notesOf(held)).toEqual(["1001", "1002", "1003"]);
|
|
expect(planOf(stateOf(published([])), "post_drafts_publish")).toMatchObject(
|
|
{ effect: "create" },
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("creates a later write may explain", () => {
|
|
it("links no create past a later write, which may have made what the read shows", () => {
|
|
const drafted = (publish: boolean): TimedCaptureRow[] => [
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
["POST", "/api/drafts", C, 201, { title: "Gamma" }],
|
|
...(publish
|
|
? ([
|
|
[
|
|
"POST",
|
|
"/api/drafts/1003/publish",
|
|
{ id: 1003, status: "published" },
|
|
201,
|
|
],
|
|
] as TimedCaptureRow[])
|
|
: []),
|
|
["GET", "/api/notes/1003", C],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
];
|
|
const state = stateOf(drafted(true));
|
|
// The publish call made the note, so the draft's POST creates none.
|
|
expect(planOf(state, "post_drafts")).toMatchObject({
|
|
effect: "none",
|
|
reason: "no-state-target",
|
|
});
|
|
expect(
|
|
state.writes.find((plan) => plan.tool !== "post_drafts"),
|
|
).toMatchObject({ effect: "create", target: "/api/notes" });
|
|
expect(planOf(stateOf(drafted(false)), "post_drafts")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("state order after a variant line is dropped", () => {
|
|
it("orders entities by the lines left, so a plain list listing them in another order lists them all", () => {
|
|
const view = stateOf([
|
|
[
|
|
"GET",
|
|
"/api/books?expand=shelf",
|
|
[expandedBook(SECOND_BOOK), expandedBook(FIRST_BOOK)],
|
|
],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
]).views.find((candidate) => candidate.tool === "get_books");
|
|
expect(view).toMatchObject({
|
|
shape: "list",
|
|
membership: "all",
|
|
projected_record_ordinals: [0],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("item lines first recorded after a write", () => {
|
|
it("replays an item line that shows another representation, though first recorded after a write", () => {
|
|
const created = book(3, "Third Book", bookClock(4));
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["POST", "/api/books", created, 201, { name: "Third Book" }],
|
|
["GET", "/api/books/3", created],
|
|
["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
|
|
]);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({
|
|
projected_record_ordinals: [5],
|
|
projected_query_keys: [{ name: "expand" }],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("item lines first recorded after a write, against the lines left", () => {
|
|
const created = book(3, "Third Book", bookClock(4));
|
|
const lines = (late: TimedCaptureRow): TimedCaptureRow[] => [
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["GET", "/api/books/1?expand=shelf", expandedBook(FIRST_BOOK)],
|
|
["POST", "/api/books", created, 201, { name: "Third Book" }],
|
|
["GET", "/api/books/3", created],
|
|
late,
|
|
];
|
|
const itemView = (rows: TimedCaptureRow[]) =>
|
|
stateOf(rows).views.find((view) => view.tool === "get_books_by_id");
|
|
|
|
it("compares a later line with the lines left after variants are dropped, not the dropped ones", () => {
|
|
// The early `expand` line is dropped as a variant, so `include` shows a shelf the lines left never show.
|
|
expect(
|
|
itemView(
|
|
lines(["GET", "/api/books/2?include=shelf", expandedBook(SECOND_BOOK)]),
|
|
),
|
|
).toMatchObject({
|
|
projected_record_ordinals: [3, 6],
|
|
projected_query_keys: expect.arrayContaining([{ name: "include" }]),
|
|
});
|
|
});
|
|
|
|
it("replays a later selection of some fields that keeps the identity but leaves members out", () => {
|
|
expect(
|
|
itemView(
|
|
lines([
|
|
"GET",
|
|
"/api/books/2?fields=id,name",
|
|
{ id: 2, name: "Second Book" },
|
|
]),
|
|
),
|
|
).toMatchObject({
|
|
projected_record_ordinals: [3, 6],
|
|
projected_query_keys: expect.arrayContaining([{ name: "fields" }]),
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("reads overlapping a linked create", () => {
|
|
it("links a create whose id only a list still running when it began showed before", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
// Begun before the publish and finished after it, so it may show what the publish made.
|
|
["GET", "/api/notes", [A, B, C], 200, undefined, 2500],
|
|
["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes/1003", C],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
]);
|
|
expect(planOf(state, "post_drafts_publish")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
});
|
|
expect(notesOf(state)).toEqual(["1001", "1002"]);
|
|
});
|
|
});
|
|
|
|
describe("earlier reads of the returned id under other types", () => {
|
|
it("links a create whose id an earlier read of another type named", () => {
|
|
const user = { id: 1003, login: "gamma" };
|
|
const state = stateOf([
|
|
["GET", "/api/users/1003", user],
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/notes/1003", C],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
]);
|
|
expect(planOf(state, "post_drafts_publish")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("item reads that show no entity", () => {
|
|
it("links a create past a read of its id that answered JSON null under another type", () => {
|
|
const user = (id: number, login: string) => ({ id, login });
|
|
const state = stateOf([
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
["GET", "/api/users/1001", user(1001, "alpha")],
|
|
// Ends the users' initial reads, so the null read below plans nothing.
|
|
[
|
|
"PATCH",
|
|
"/api/users/1001",
|
|
user(1001, "alpha2"),
|
|
200,
|
|
{ login: "alpha2" },
|
|
],
|
|
["POST", "/api/drafts/publish", { id: 1003 }, 201, { title: "Gamma" }],
|
|
["GET", "/api/users/1003", null],
|
|
["GET", "/api/notes/1003", C],
|
|
["GET", "/api/notes", [A, B, C]],
|
|
]);
|
|
expect(planOf(state, "post_drafts_publish")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("what a linked create observes", () => {
|
|
it("observes a linked create only in a read of an id its response named, inside an envelope too", () => {
|
|
const D = note(1004, "Delta");
|
|
const state = stateOf([
|
|
["GET", "/api/notes", [A, B]],
|
|
["GET", "/api/notes/1001", A],
|
|
["GET", "/api/notes/1002", B],
|
|
[
|
|
"POST",
|
|
"/api/drafts/publish",
|
|
{ data: { id: 1003 } },
|
|
201,
|
|
{ title: "Gamma" },
|
|
],
|
|
// Another note the state never held, which the publish did not make.
|
|
["GET", "/api/notes/1004", D],
|
|
["GET", "/api/notes/1003", C],
|
|
]);
|
|
expect(planOf(state, "post_drafts_publish")).toMatchObject({
|
|
effect: "create",
|
|
target: "/api/notes",
|
|
observation: { ordinal: 5 },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("creates whose returned id an earlier read showed", () => {
|
|
it("links no create whose returned id a list of its collection showed before it", () => {
|
|
const listed = (shown: JsonValue[]): TimedCaptureRow[] =>
|
|
published([
|
|
[
|
|
"PATCH",
|
|
"/api/notes/1001",
|
|
note(1001, "Alpha 2"),
|
|
200,
|
|
{ title: "Alpha 2" },
|
|
],
|
|
["GET", "/api/notes?include=archived", shown],
|
|
]);
|
|
const alpha = note(1001, "Alpha 2");
|
|
expect(
|
|
planOf(stateOf(listed([alpha, B, C])), "post_drafts_publish"),
|
|
).toMatchObject({ effect: "none", reason: "no-state-target" });
|
|
expect(
|
|
planOf(stateOf(listed([alpha, B])), "post_drafts_publish"),
|
|
).toMatchObject({ effect: "create", target: "/api/notes" });
|
|
});
|
|
});
|
|
|
|
describe("lines left to replay", () => {
|
|
it("plans a list past a line that asks for some fields only and leaves the proved id out", () => {
|
|
const created = book(3, "Third Book", bookClock(4));
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
[
|
|
"GET",
|
|
"/api/books?fields=name",
|
|
[{ name: "First Book" }, { name: "Second Book" }],
|
|
],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["POST", "/api/books", created, 201, { name: "Third Book" }],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK, created]],
|
|
]);
|
|
expect(state.views.find((view) => view.tool === "get_books")).toMatchObject(
|
|
{
|
|
shape: "list",
|
|
checked_record_ordinals: [0],
|
|
projected_record_ordinals: [1],
|
|
projected_query_keys: [{ name: "fields" }],
|
|
},
|
|
);
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("checks a list line asking for every field beside the plain one, as serving answers both from the state", () => {
|
|
const created = book(3, "Third Book", bookClock(4));
|
|
const state = stateOf([
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
["GET", "/api/books?fields=*", [FIRST_BOOK, SECOND_BOOK]],
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
["POST", "/api/books", created, 201, { name: "Third Book" }],
|
|
["GET", "/api/books?fields=*", [FIRST_BOOK, SECOND_BOOK, created]],
|
|
]);
|
|
const view = state.views.find(
|
|
(candidate) => candidate.tool === "get_books",
|
|
);
|
|
expect(view).toMatchObject({
|
|
shape: "list",
|
|
checked_record_ordinals: [0, 1],
|
|
});
|
|
expect(view).not.toHaveProperty("projected_record_ordinals");
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [5],
|
|
});
|
|
});
|
|
|
|
it("keeps a list's whole line when only a replayed line's membership changed across a write", () => {
|
|
// The expanded line lists shelved books only; the whole list still shows both after the export.
|
|
const view = stateOf([
|
|
["GET", "/api/books/1", FIRST_BOOK],
|
|
["GET", "/api/books/2", SECOND_BOOK],
|
|
[
|
|
"GET",
|
|
"/api/books?expand=shelf",
|
|
[FIRST_BOOK, SECOND_BOOK].map(expandedBook),
|
|
],
|
|
["POST", "/api/exports", { queued: true }, 202, { format: "csv" }],
|
|
["GET", "/api/books?expand=shelf", [expandedBook(FIRST_BOOK)]],
|
|
["GET", "/api/books", [FIRST_BOOK, SECOND_BOOK]],
|
|
]).views.find((candidate) => candidate.tool === "get_books");
|
|
expect(view).toMatchObject({
|
|
shape: "list",
|
|
checked_record_ordinals: [5],
|
|
projected_record_ordinals: [4],
|
|
projected_query_keys: [{ name: "expand" }],
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("field selections the gate reads as serving answers them", () => {
|
|
it("approves no create from a read serving replays, a selection no checked line gave", () => {
|
|
const state = stateOf([
|
|
["GET", "/api/books/1?fields=*", FIRST_BOOK],
|
|
["GET", "/api/books/2?fields=*", SECOND_BOOK],
|
|
["GET", "/api/books/2?fields=name", { name: "Second Book" }],
|
|
["POST", "/api/books", THIRD_BOOK, 201, { name: "Third Book" }],
|
|
[
|
|
"GET",
|
|
"/api/books/3?fields=id,name,slug,created_at,updated_at",
|
|
THIRD_BOOK,
|
|
],
|
|
]);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({
|
|
projected_query_keys: [{ name: "fields", value: "name" }],
|
|
});
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: false,
|
|
reason: "unconfirmed",
|
|
});
|
|
});
|
|
|
|
it("checks an update against a read of every field, which serving answers from the state", () => {
|
|
const state = stateOf([
|
|
...BOOK_INIT_ROWS,
|
|
["GET", "/api/books/2?fields=name", { name: "Second Book" }],
|
|
["PATCH", "/api/books/1", RENAMED_BOOK, 200, { name: "Renamed Book" }],
|
|
["GET", "/api/books/1?fields=*", FIRST_BOOK],
|
|
["GET", "/api/books/1", RENAMED_BOOK],
|
|
]);
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({ projected_query_keys: [{ name: "fields" }] });
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: false,
|
|
reason: "contradicted",
|
|
contradicted_by: 5,
|
|
});
|
|
});
|
|
});
|
|
|
|
/** A create and an update whose bodies and responses wrap the book in a one-element array. */
|
|
const ENVELOPED_ROWS: readonly TimedCaptureRow[] = [
|
|
...BOOK_INIT_ROWS,
|
|
[
|
|
"POST",
|
|
"/api/books",
|
|
{ books: [THIRD_BOOK] },
|
|
201,
|
|
{ books: [{ name: "Third Book" }] },
|
|
],
|
|
["GET", "/api/books/3", THIRD_BOOK],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
{ books: [RENAMED_BOOK] },
|
|
200,
|
|
{ books: [{ name: "Renamed Book" }] },
|
|
],
|
|
["GET", "/api/books/1", RENAMED_BOOK],
|
|
];
|
|
|
|
/** A card whose edit info an update restamps: its response and its read-back name instants milliseconds apart. */
|
|
const cardEdit = (milliseconds: number) => ({
|
|
at: new Date(Date.parse(bookClock(3)) + milliseconds).toISOString(),
|
|
by: "rea",
|
|
});
|
|
const FIRST_CARD = {
|
|
id: 1,
|
|
name: "First Card",
|
|
edit: { at: "2026-10-01T09:00:00.000Z", by: "rea" },
|
|
};
|
|
const SECOND_CARD = { ...FIRST_CARD, id: 2, name: "Second Card" };
|
|
|
|
describe("values an application stamps", () => {
|
|
it("serves a create and an update whose bodies wrap the book in a one-element array, as the capture sent them", () => {
|
|
const state = stateOf(ENVELOPED_ROWS);
|
|
expect(planOf(state, "post_books")).toMatchObject({
|
|
served: true,
|
|
body: { accepted: ["name"], envelope: "books" },
|
|
});
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
body: { accepted: ["name"], envelope: "books" },
|
|
});
|
|
});
|
|
|
|
it("serves an update that restamps a nested clock, storing the instant its read-back shows", () => {
|
|
const edited = { ...FIRST_CARD, name: "First Card (edited)" };
|
|
const state = stateOf([
|
|
["GET", "/api/cards", [FIRST_CARD, SECOND_CARD]],
|
|
["GET", "/api/cards/1", FIRST_CARD],
|
|
["GET", "/api/cards/2", SECOND_CARD],
|
|
[
|
|
"PUT",
|
|
"/api/cards/1",
|
|
{ ...edited, edit: cardEdit(64) },
|
|
200,
|
|
{ name: "First Card (edited)" },
|
|
],
|
|
["GET", "/api/cards/1", { ...edited, edit: cardEdit(53) }],
|
|
]);
|
|
expect(planOf(state, "put_cards_by_id")).toMatchObject({
|
|
served: true,
|
|
rules: expect.arrayContaining([
|
|
expect.objectContaining({
|
|
field: "edit",
|
|
rule: "nested-clock",
|
|
members: ["at"],
|
|
}),
|
|
]),
|
|
});
|
|
});
|
|
|
|
it("serves creates whose read-backs store a nested clock at another instant than their responses spell", () => {
|
|
// Each response stamps the edit in milliseconds; its read-back stores microseconds a few milliseconds earlier.
|
|
const card = (id: number, seconds: number, at: string) => ({
|
|
id,
|
|
name: `Card ${String(id)}`,
|
|
edit: { at, by: "rea" },
|
|
});
|
|
const answered = (seconds: number) =>
|
|
new Date(Date.parse(bookClock(seconds)) + 30).toISOString();
|
|
const stored = (seconds: number, micro: string) =>
|
|
`${bookClock(seconds).slice(0, -1)}.${micro}Z`;
|
|
const state = stateOf([
|
|
["GET", "/api/cards", [FIRST_CARD, SECOND_CARD]],
|
|
["GET", "/api/cards/1", FIRST_CARD],
|
|
["GET", "/api/cards/2", SECOND_CARD],
|
|
["POST", "/api/cards", card(3, 3, answered(3)), 201, { name: "Card 3" }],
|
|
["GET", "/api/cards/3", card(3, 3, stored(3, "020123"))],
|
|
["POST", "/api/cards", card(4, 5, answered(5)), 201, { name: "Card 4" }],
|
|
["GET", "/api/cards/4", card(4, 5, stored(5, "021456"))],
|
|
]);
|
|
expect(planOf(state, "post_cards")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4, 6],
|
|
rules: expect.arrayContaining([
|
|
expect.objectContaining({ field: "edit", rule: "nested-clock" }),
|
|
]),
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("nested clocks another recorded call kept", () => {
|
|
const CARD_INIT_ROWS: TimedCaptureRow[] = [
|
|
["GET", "/api/cards", [FIRST_CARD, SECOND_CARD]],
|
|
["GET", "/api/cards/1", FIRST_CARD],
|
|
["GET", "/api/cards/2", SECOND_CARD],
|
|
];
|
|
/** The first card renamed, with its edit stamped 64 ms into the given exchange's second, or kept as it was. */
|
|
const card = (name: string, stampedAt?: number) => ({
|
|
...FIRST_CARD,
|
|
name,
|
|
edit:
|
|
stampedAt === undefined
|
|
? FIRST_CARD.edit
|
|
: {
|
|
at: new Date(Date.parse(bookClock(stampedAt)) + 64).toISOString(),
|
|
by: "rea",
|
|
},
|
|
});
|
|
const put = (written: ReturnType<typeof card>): TimedCaptureRow[] => [
|
|
["PUT", "/api/cards/1", written, 200, { name: written.name }],
|
|
["GET", "/api/cards/1", written],
|
|
];
|
|
const verdictOf = (rows: readonly TimedCaptureRow[]) =>
|
|
planOf(stateOf([...CARD_INIT_ROWS, ...rows]), "put_cards_by_id");
|
|
|
|
it("serves no update whose nested clock another recorded call kept, before or after the call that stamped it", () => {
|
|
expect(
|
|
verdictOf([...put(card("Edited", 3)), ...put(card("Renamed", 5))]),
|
|
).toMatchObject({ served: true });
|
|
const stamped = card("Edited", 3);
|
|
expect(
|
|
verdictOf([...put(stamped), ...put({ ...stamped, name: "Renamed" })]),
|
|
).toMatchObject({ served: false, reason: "unexplained-change" });
|
|
expect(
|
|
verdictOf([...put(card("Edited")), ...put(card("Renamed", 5))]),
|
|
).toMatchObject({ served: false, reason: "unexplained-change" });
|
|
});
|
|
});
|
|
|
|
/** A book with tags, as an application that keeps tags as a set lists them. */
|
|
const tagged = (entry: Book, tags: string[]): Book => ({ ...entry, tags });
|
|
const TAGGED_INIT_ROWS: TimedCaptureRow[] = [
|
|
[
|
|
"GET",
|
|
"/api/books",
|
|
[tagged(FIRST_BOOK, ["alpha", "beta"]), tagged(SECOND_BOOK, ["gamma"])],
|
|
],
|
|
["GET", "/api/books/1", tagged(FIRST_BOOK, ["alpha", "beta"])],
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["gamma"])],
|
|
[
|
|
"PATCH",
|
|
"/api/books/2",
|
|
tagged(SECOND_BOOK, ["zeta", "delta"]),
|
|
200,
|
|
{ tags: ["zeta", "delta"] },
|
|
],
|
|
];
|
|
|
|
describe("array fields a view lists sorted", () => {
|
|
it("serves an update whose read-back lists the written tags sorted, and every view of the type sorts them", () => {
|
|
const state = stateOf([
|
|
...TAGGED_INIT_ROWS,
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["delta", "zeta"])],
|
|
]);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4],
|
|
});
|
|
for (const tool of ["get_books_by_id", "get_books"])
|
|
expect(state.views.find((view) => view.tool === tool)).toMatchObject({
|
|
sorted_arrays: ["tags"],
|
|
});
|
|
});
|
|
|
|
it("learns no sorting from a read after another the gate counted listed the field unsorted", () => {
|
|
const state = stateOf([
|
|
...TAGGED_INIT_ROWS,
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["zeta", "delta"])],
|
|
[
|
|
"PATCH",
|
|
"/api/books/1",
|
|
tagged(FIRST_BOOK, ["omega", "beta"]),
|
|
200,
|
|
{ tags: ["omega", "beta"] },
|
|
],
|
|
["GET", "/api/books/1", tagged(FIRST_BOOK, ["beta", "omega"])],
|
|
]);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: false,
|
|
reason: "contradicted",
|
|
});
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).not.toHaveProperty("sorted_arrays");
|
|
});
|
|
|
|
it("learns no sorting from a read whose order fits the values held first, then the new ones as written", () => {
|
|
// `alpha` was held before the update and `zeta` was not: a store ordering tags by when it made them lists them so too.
|
|
const state = stateOf([
|
|
...TAGGED_INIT_ROWS.slice(0, 3),
|
|
[
|
|
"PATCH",
|
|
"/api/books/2",
|
|
tagged(SECOND_BOOK, ["zeta", "alpha"]),
|
|
200,
|
|
{ tags: ["zeta", "alpha"] },
|
|
],
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["alpha", "zeta"])],
|
|
]);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: false,
|
|
reason: "contradicted",
|
|
});
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).not.toHaveProperty("sorted_arrays");
|
|
});
|
|
|
|
it("keeps the written order a read-back shows, though every initial array was sorted", () => {
|
|
const state = stateOf([
|
|
...TAGGED_INIT_ROWS,
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["zeta", "delta"])],
|
|
]);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4],
|
|
});
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).not.toHaveProperty("sorted_arrays");
|
|
});
|
|
});
|
|
|
|
/** A book on a shelf, in a collection per shelf whose ids repeat across shelves. */
|
|
const shelved = (tags: string[]) => ({ id: 1, name: "Shelved Book", tags });
|
|
|
|
describe("evidence a learned sort keeps answering to", () => {
|
|
it("drops a sort a view learned once a later counted read lists the field as written", () => {
|
|
const state = stateOf([
|
|
...TAGGED_INIT_ROWS,
|
|
["GET", "/api/books/2", tagged(SECOND_BOOK, ["delta", "zeta"])],
|
|
[
|
|
"GET",
|
|
"/api/books",
|
|
[
|
|
tagged(FIRST_BOOK, ["alpha", "beta"]),
|
|
tagged(SECOND_BOOK, ["zeta", "delta"]),
|
|
],
|
|
],
|
|
]);
|
|
expect(planOf(state, "patch_books_by_id")).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4],
|
|
});
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books_by_id"),
|
|
).toMatchObject({ sorted_arrays: ["tags"] });
|
|
expect(
|
|
state.views.find((view) => view.tool === "get_books"),
|
|
).not.toHaveProperty("sorted_arrays");
|
|
});
|
|
|
|
it("learns no sorting from another collection's entity under the read's id", () => {
|
|
// Shelf 1's read-back fits `alpha`, held before the update, then `zeta` as written; shelf 2's book shares its id.
|
|
const state = stateOf([
|
|
["GET", "/api/shelves/1/books", [shelved(["alpha", "beta"])]],
|
|
["GET", "/api/shelves/1/books/1", shelved(["alpha", "beta"])],
|
|
["GET", "/api/shelves/2/books", [shelved(["beta", "gamma"])]],
|
|
["GET", "/api/shelves/2/books/1", shelved(["beta", "gamma"])],
|
|
[
|
|
"PATCH",
|
|
"/api/shelves/1/books/1",
|
|
shelved(["zeta", "alpha"]),
|
|
200,
|
|
{ tags: ["zeta", "alpha"] },
|
|
],
|
|
["GET", "/api/shelves/1/books/1", shelved(["alpha", "zeta"])],
|
|
]);
|
|
expect(state.writes).toEqual([
|
|
expect.objectContaining({ served: false, reason: "contradicted" }),
|
|
]);
|
|
expect(state.views.length).toBeGreaterThan(0);
|
|
for (const view of state.views)
|
|
expect(view).not.toHaveProperty("sorted_arrays");
|
|
});
|
|
});
|
|
|
|
describe("initial order", () => {
|
|
it("orders a collection as a whole list line that applies no sort lists it, after an item read and filtered or sorted lines", () => {
|
|
const alpha = book(1, "Alpha", "2026-10-01T09:00:00Z");
|
|
const charlie = book(2, "Charlie", "2026-10-01T10:00:00Z");
|
|
const bravo = book(3, "Bravo", "2026-10-01T11:00:00Z");
|
|
const state = stateOf([
|
|
["GET", "/api/books/2", charlie],
|
|
["GET", "/api/books?name=Alpha", [alpha]],
|
|
["GET", "/api/books?ordering=name", [alpha, bravo, charlie]],
|
|
["GET", "/api/books", [bravo, alpha, charlie]],
|
|
["GET", "/api/books/1", alpha],
|
|
["GET", "/api/books/3", bravo],
|
|
]);
|
|
expect(
|
|
state.entities
|
|
.filter((entity) => entity.type === "/api/books")
|
|
.map((entity) => entity.id),
|
|
).toEqual(["3", "1", "2"]);
|
|
});
|
|
});
|
|
|
|
describe("insert rules the recorded order cannot settle", () => {
|
|
const listed = (id: string, name: string, created: string) => ({
|
|
id,
|
|
name,
|
|
created_at: created,
|
|
});
|
|
const rowsFor = (
|
|
members: { id: string; name: string; created_at: string }[],
|
|
created: { id: string; name: string; created_at: string },
|
|
): TimedCaptureRow[] => [
|
|
["GET", "/api/items", members],
|
|
...members.map((member): TimedCaptureRow => [
|
|
"GET",
|
|
`/api/items/${member.id}`,
|
|
member,
|
|
]),
|
|
["POST", "/api/items", created, 201, { name: created.name }],
|
|
["GET", `/api/items/${created.id}`, created],
|
|
];
|
|
|
|
it("places a create last, not by identity, when its identities are random UUIDs", () => {
|
|
const at = "2026-10-01T09:00:00Z";
|
|
const plan = planOf(
|
|
stateOf(
|
|
rowsFor(
|
|
[
|
|
listed("1c0e8a2b-7f3d-4e9a-b1c2-d3e4f5a6b7c8", "Delta", at),
|
|
listed("5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "Alpha", at),
|
|
listed("9b2f1c3e-0d4a-4b6e-8f1a-2c3d4e5f6a7b", "Charlie", at),
|
|
],
|
|
listed("e5d6e7f8-1a2b-4c3d-9e4f-5a6b7c8d9e0f", "Echo", bookClock(4)),
|
|
),
|
|
),
|
|
"post_items",
|
|
);
|
|
expect(plan).toMatchObject({ served: true, insert: { rule: "last" } });
|
|
});
|
|
|
|
it("keeps sorting by an identity a creation clock follows", () => {
|
|
const plan = planOf(
|
|
environmentStateViewOf(
|
|
timedCaptureEvidence(
|
|
rowsFor(
|
|
[
|
|
listed(
|
|
"6ad47b491023b50001087124",
|
|
"Alpha",
|
|
"2026-10-01T09:00:00Z",
|
|
),
|
|
listed(
|
|
"6ad47b491023b50001087125",
|
|
"Bravo",
|
|
"2026-10-01T10:00:00Z",
|
|
),
|
|
],
|
|
listed("6ad47b491023b50001087130", "Charlie", bookClock(3)),
|
|
),
|
|
),
|
|
["opaque-token"],
|
|
),
|
|
"post_items",
|
|
);
|
|
expect(plan).toMatchObject({
|
|
served: true,
|
|
insert: { rule: "sorted", field: "id", direction: "ascending" },
|
|
});
|
|
});
|
|
|
|
it("places a create last when the orders the list admits put it in different places", () => {
|
|
const plan = planOf(
|
|
stateOf(
|
|
rowsFor(
|
|
[
|
|
listed("2", "Alpha", "2026-10-01T10:00:00Z"),
|
|
listed("1", "Delta", "2026-10-01T09:00:00Z"),
|
|
],
|
|
listed("3", "Bravo", bookClock(3)),
|
|
),
|
|
),
|
|
"post_items",
|
|
);
|
|
expect(plan).toMatchObject({ served: true, insert: { rule: "last" } });
|
|
});
|
|
});
|
|
|
|
/** A task whose modified clock is stored in whole seconds. */
|
|
const task = (id: number, name: string, modifiedAt: string) => ({
|
|
id,
|
|
name,
|
|
modifiedAt,
|
|
});
|
|
const OLD_CLOCK = "2026-10-01T09:00:00Z";
|
|
|
|
describe("clocks an update may stamp in its own second", () => {
|
|
const sameSecond: TimedCaptureRow[] = [
|
|
[
|
|
"GET",
|
|
"/api/tasks",
|
|
[task(1, "First", bookClock(3)), task(2, "Second", OLD_CLOCK)],
|
|
],
|
|
["GET", "/api/tasks/1", task(1, "First", bookClock(3))],
|
|
["GET", "/api/tasks/2", task(2, "Second", OLD_CLOCK)],
|
|
[
|
|
"PATCH",
|
|
"/api/tasks/1",
|
|
task(1, "Renamed", bookClock(3)),
|
|
200,
|
|
{ name: "Renamed" },
|
|
],
|
|
["GET", "/api/tasks/1", task(1, "Renamed", bookClock(3))],
|
|
];
|
|
|
|
it("confirms no update that left an unsent clock as it was in the second it ran", () => {
|
|
expect(planOf(stateOf(sameSecond), "patch_tasks_by_id")).toMatchObject({
|
|
served: false,
|
|
reason: "unconfirmed",
|
|
});
|
|
});
|
|
|
|
it("serves the update once another call shows it stamping the clock", () => {
|
|
const plan = planOf(
|
|
stateOf([
|
|
...sameSecond,
|
|
[
|
|
"PATCH",
|
|
"/api/tasks/2",
|
|
task(2, "Second (renamed)", bookClock(5)),
|
|
200,
|
|
{ name: "Second (renamed)" },
|
|
],
|
|
["GET", "/api/tasks/2", task(2, "Second (renamed)", bookClock(5))],
|
|
]),
|
|
"patch_tasks_by_id",
|
|
);
|
|
expect(plan).toMatchObject({
|
|
served: true,
|
|
checked_record_ordinals: [4, 6],
|
|
});
|
|
expect(plan.rules).toContainEqual(
|
|
expect.objectContaining({ field: "modifiedAt", rule: "clock" }),
|
|
);
|
|
});
|
|
});
|
|
|
|
/** A book with an `archived` flag, which an item action sets. */
|
|
const withArchived = (entity: Book, archived: boolean): Book => ({
|
|
...entity,
|
|
archived,
|
|
});
|
|
|
|
/** A post whose `status` goes with whether it has a publication clock. */
|
|
const post = (id: number, status: string, publishedAt: string | null) => ({
|
|
id,
|
|
title: `Post ${id}`,
|
|
status,
|
|
published_at: publishedAt,
|
|
});
|
|
|
|
describe("recorded calls serving would refuse", () => {
|
|
it("serves no action that only a call sent with another query showed setting its field", () => {
|
|
const archived = withArchived(FIRST_BOOK, true);
|
|
// Serving pins toggle=true, so the call sent with toggle=false shows nothing of what serving does.
|
|
const plan = planOf(
|
|
stateOf([
|
|
[
|
|
"GET",
|
|
"/api/books",
|
|
[withArchived(FIRST_BOOK, false), withArchived(SECOND_BOOK, false)],
|
|
],
|
|
["GET", "/api/books/1", withArchived(FIRST_BOOK, false)],
|
|
["GET", "/api/books/2", withArchived(SECOND_BOOK, false)],
|
|
["POST", "/api/books/1/archive?toggle=true", archived],
|
|
["GET", "/api/books/1", archived],
|
|
["POST", "/api/books/1/archive?toggle=false", archived],
|
|
["GET", "/api/books/1", archived],
|
|
]),
|
|
"post_books_archive_by_id",
|
|
);
|
|
expect(plan).toMatchObject({ served: false, reason: "unconfirmed" });
|
|
});
|
|
|
|
it("confirms no document write by a call sent with another query than serving pins", () => {
|
|
// The dry run changed nothing; the read after the real call shows only what that call did.
|
|
const plan = planOf(
|
|
stateOf([
|
|
["GET", "/api/settings", { theme: "light", lang: "en" }],
|
|
[
|
|
"PATCH",
|
|
"/api/settings?dry_run=true",
|
|
{ theme: "dark", lang: "en" },
|
|
200,
|
|
{ theme: "dark" },
|
|
],
|
|
[
|
|
"PATCH",
|
|
"/api/settings?dry_run=false",
|
|
{ theme: "dark", lang: "en" },
|
|
200,
|
|
{ theme: "dark" },
|
|
],
|
|
["GET", "/api/settings", { theme: "dark", lang: "en" }],
|
|
]),
|
|
"patch_settings",
|
|
);
|
|
expect(plan).toMatchObject({ served: false, checked_record_ordinals: [] });
|
|
});
|
|
|
|
it("confirms no delete by a call sent with another query than serving pins", () => {
|
|
const plan = planOf(
|
|
stateOf([
|
|
...BOOK_INIT_ROWS,
|
|
["DELETE", "/api/books/2?dry_run=true", "", 204],
|
|
["DELETE", "/api/books/1?dry_run=false", "", 204],
|
|
["GET", "/api/books/1", BOOK_NOT_FOUND, 404],
|
|
]),
|
|
"delete_books_by_id",
|
|
);
|
|
expect(plan).toMatchObject({ served: false, checked_record_ordinals: [] });
|
|
});
|
|
|
|
it("keeps a create's dependent state pinned when another call does not prove its result", () => {
|
|
const draft = post(3, "draft", null);
|
|
const sent = { title: "Post 3", status: "draft" };
|
|
const others: TimedCaptureRow[] = [
|
|
["POST", "/api/posts", { detail: "Invalid." }, 422, { status: "x" }],
|
|
["POST", "/api/posts", "", 204, { title: "Post 4", status: "published" }],
|
|
[
|
|
"POST",
|
|
"/api/posts?import=true",
|
|
post(4, "published", bookClock(6)),
|
|
201,
|
|
{ title: "Post 4", status: "published" },
|
|
],
|
|
];
|
|
for (const other of others) {
|
|
const plan = planOf(
|
|
stateOf([
|
|
[
|
|
"GET",
|
|
"/api/posts",
|
|
[
|
|
post(1, "published", "2026-10-01T09:00:00Z"),
|
|
post(2, "published", "2026-10-01T10:00:00Z"),
|
|
],
|
|
],
|
|
["GET", "/api/posts/1", post(1, "published", "2026-10-01T09:00:00Z")],
|
|
["GET", "/api/posts/2", post(2, "published", "2026-10-01T10:00:00Z")],
|
|
["POST", "/api/posts", draft, 201, sent],
|
|
["GET", "/api/posts/3", draft],
|
|
other,
|
|
]),
|
|
"post_posts",
|
|
);
|
|
expect(plan.served, other[1]).toBe(true);
|
|
expect(plan.body?.fixed, other[1]).toEqual([
|
|
{ member: "status", sent: "draft" },
|
|
]);
|
|
}
|
|
});
|
|
});
|
|
|
|
it.each(["__proto__", "constructor"])(
|
|
"learns a confirmed update of an own %s field",
|
|
(field) => {
|
|
const initial = {
|
|
id: 1,
|
|
name: "One",
|
|
...Object.fromEntries([[field, { label: "old" }]]),
|
|
};
|
|
const body = Object.fromEntries([[field, { label: "stored" }]]);
|
|
const updated = { ...initial, ...body };
|
|
const state = stateOf([
|
|
["GET", "/api/items", [initial, { id: 2, name: "Two" }]],
|
|
["GET", "/api/items/1", initial],
|
|
["PATCH", "/api/items/1", updated, 200, body],
|
|
["GET", "/api/items/1", updated],
|
|
]);
|
|
expect(planOf(state, "patch_items_by_id")).toMatchObject({
|
|
served: true,
|
|
rules: expect.arrayContaining([{ rule: "echo", field }]),
|
|
});
|
|
},
|
|
);
|