@afora/core 0.0.7 → 0.0.8

package/dist/std/use-cases/types.d.ts

@@ -1,10 +1,11 @@
-import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, IBlueprint, IBlueprintCollection, IBlueprintList, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "../../core/blueprint/types/blueprint.interface.js";
+import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, BlueprintValue, IBlueprint, IBlueprintCollection, IBlueprintList, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "../../core/blueprint/types/blueprint.interface.js";
 import type { EntityIdentityKey } from "../../core/entity/types/entity.interface.js";
+import type { EntityVersion } from "../../core/entity/version.js";
 import type { OptionalProperty } from "../../core/property/types/optional-property.type.js";
 import type { AnyPropertyConstructor } from "../../core/property/types/property-collection.type.js";
 import type { AnyRepository, AnyRepositoryEntity, EntityInstanceOf } from "../../core/repository/types/repository.interface.js";
 import type { IUseCasePlugin, UseCaseTarget } from "../../core/use-case/types/plugin.interface.js";
-import type { AnyExceptionClass, StepsUseCaseConstructor } from "../../core/use-case/use-case.js";
+import type { AnyExceptionClass, DependencyFunctions, StepsUseCaseConstructor, UseCaseCollection } from "../../core/use-case/use-case.js";
 import type { Integer, StringProperty } from "../properties/primitives.js";
 type EntityOf<Repository> = Repository extends {
     readonly entity: infer Entity extends AnyRepositoryEntity;
@@ -88,6 +89,79 @@ export interface StdListOptions<Repository> extends StdUseCaseOptions, StdOwnerO
     }[];
 }
 type None = Record<never, never>;
+/** What `before` and `after` get of the call. */
+export interface StdHookArgs<Input, Dependencies, Context> {
+    /** The input of the call, parsed; for `after`, the one `before` gave back. */
+    readonly input: Input;
+    /**
+     * The dependencies of the call, as `execute` resolved them (overrides
+     * included): `repository`, those the use case makes to load what the
+     * input names, and those of the option `dependencies`.
+     */
+    readonly dependencies: Dependencies;
+    /** The context of the call: the id of the caller with `owner`, else `undefined`. */
+    readonly context: Context;
+}
+/**
+ * The options of a standard use case that writes: `before` runs before the
+ * write and may give back the input to write in place of the one given;
+ * `after` runs after it, within the transaction of the command; both get the
+ * dependencies of the use case and those of `dependencies`, and `throws` adds
+ * the exceptions they may throw to its errors (for `describe()` and statuses).
+ */
+export interface StdHookOptions<Input, Entity, Dependencies extends UseCaseCollection, Bound, Context, Loaded extends boolean> {
+    /** Repositories, use cases or environments the hooks use, by name, beside those the use case makes. */
+    readonly dependencies?: Dependencies;
+    /**
+     * Runs before the write (after the entity is loaded and its owner
+     * checked, for a use case over one entity, which gets it as `entity`);
+     * what it gives back, if anything, is the input the use case goes on with.
+     */
+    readonly before?: (args: StdHookArgs<Input, Bound, Context> & (Loaded extends true ? {
+        readonly entity: Entity;
+    } : unknown)) => Input | void | Promise<Input | void>;
+    /** Runs after the write, with the entity written, before the response is given. */
+    readonly after?: (args: StdHookArgs<Input, Bound, Context> & {
+        readonly entity: Entity;
+    }) => unknown;
+    /** Exceptions (made by `exceptionOf`) `before` or `after` may throw: added to the errors of the use case. */
+    readonly throws?: readonly AnyExceptionClass[];
+}
+/** What `get`, `list` and `login` take in place of the hooks: none. */
+export interface StdNoHookOptions {
+    readonly before?: never;
+    readonly after?: never;
+    readonly dependencies?: never;
+    readonly throws?: never;
+}
+type ContextValue<Repository, Options> = OwnerContext<Repository, Options> extends infer Context extends IBlueprintCollection ? Readonly<BlueprintValue<Context>> : undefined;
+/** `Options` as `Hookable` infers them. */
+type Shape<Omitted, Values, Owner> = {
+    readonly omit: readonly Omitted[];
+    readonly values: Values;
+} & ([Owner] extends [undefined] ? unknown : {
+    readonly owner: Owner;
+});
+/** `StdHookOptions` for a use case over `Repository` that takes `Input`. */
+type HookOptionsOf<Repository extends AnyRepository, Options, Input extends IBlueprintCollection, Dependencies extends UseCaseCollection, Loaded extends boolean> = StdHookOptions<BlueprintValue<Input>, EntityInstanceOf<EntityOf<Repository>>, Dependencies, DependencyFunctions<{
+    readonly repository: Repository;
+} & Dependencies>, ContextValue<Repository, Options>, Loaded>;
+/**
+ * The options of a use case that writes, as its maker reads them: those that
+ * type its input and context, inferred one by one (`Options` is inferred from
+ * the whole object only once the hooks are typed), and the hooks, typed by
+ * them and not inferred from. The types of `before` and `after` are only
+ * worked out for a call that gives them.
+ */
+interface Hookable<Repository extends AnyRepository, Input extends IBlueprintCollection, Omitted, Values, Owner, Dependencies extends UseCaseCollection, Loaded extends boolean> {
+    readonly omit?: readonly Omitted[];
+    readonly values?: Values;
+    readonly owner?: Owner;
+    readonly dependencies?: Dependencies;
+    readonly throws?: readonly AnyExceptionClass[];
+    readonly before?: NoInfer<HookOptionsOf<Repository, Shape<Omitted, Values, Owner>, Input, Dependencies, Loaded>["before"]>;
+    readonly after?: NoInfer<HookOptionsOf<Repository, Shape<Omitted, Values, Owner>, Input, Dependencies, Loaded>["after"]>;
+}
 type AsOf<Options> = Options extends {
     readonly as: infer Key extends string;
 } ? Key : "item";
@@ -111,9 +185,13 @@ type LeftOut<Options> = EntityIdentityKey | OwnerKey<Options> | (Options extends
 } ? Key : never) | (Options extends {
     readonly values: infer Values;
 } ? keyof Values : never);
+/** `"version"` for a versioned entity, whose `version` is part of its identity. */
+type VersionKey<Repository> = Props<Repository> extends {
+    readonly version: typeof EntityVersion;
+} ? "version" : never;
 /** The input of `create`: the keys of the entity, an entity it holds by `<key>Id`. */
 type CreateInput<Repository, Options> = {
-    readonly [Key in KeyOf<Repository> as Key extends LeftOut<Options> ? never : Props<Repository>[Key] extends AnyRepositoryEntity ? `${Key}Id` : HoldsEntity<Props<Repository>[Key]> extends true ? never : Key]: Props<Repository>[Key] extends AnyRepositoryEntity ? FieldAt<PropertiesOf<Props<Repository>[Key]>, "id"> : Props<Repository>[Key];
+    readonly [Key in KeyOf<Repository> as Key extends LeftOut<Options> | VersionKey<Repository> ? never : Props<Repository>[Key] extends AnyRepositoryEntity ? `${Key}Id` : HoldsEntity<Props<Repository>[Key]> extends true ? never : Key]: Props<Repository>[Key] extends AnyRepositoryEntity ? FieldAt<PropertiesOf<Props<Repository>[Key]>, "id"> : Props<Repository>[Key];
 };
 type ChangeKey<Repository> = EntityInstanceOf<EntityOf<Repository>> extends {
     readonly change: infer Changes;
@@ -122,18 +200,18 @@ type ChangeKey<Repository> = EntityInstanceOf<EntityOf<Repository>> extends {
 type UpdateInput<Repository> = {
     readonly [Key in "id" | ChangeKey<Repository> as Key extends "id" ? Key : HoldsEntity<Props<Repository>[Key]> extends true ? never : Key]: Key extends "id" ? IdField<Repository> : Optional<Props<Repository>[Key]>;
 };
-type EntityUseCase<Repository extends AnyRepository, Options, Input extends IBlueprintCollection> = StepsUseCaseConstructor<Input, EntityResponse<Repository, Options>, {
+type EntityUseCase<Repository extends AnyRepository, Options, Input extends IBlueprintCollection, Dependencies extends UseCaseCollection = None> = StepsUseCaseConstructor<Input, EntityResponse<Repository, Options>, {
     readonly repository: Repository;
-}, OwnerContext<Repository, Options>>;
+} & Dependencies, OwnerContext<Repository, Options>>;
 type ById<Repository> = {
     readonly id: IdField<Repository>;
 };
 /** `create`: for a repository with the `create` action. */
-export type CreateMaker = <Repository extends AnyRepository, const Options extends StdCreateOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "create">, options?: Options) => EntityUseCase<Repository, Options, CreateInput<Repository, Options>>;
+export type CreateMaker = <Repository extends AnyRepository, const Options extends StdCreateOptions<Repository> = None, const Omitted extends KeyOf<Repository> = never, const Values = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "create">, options?: Options & Hookable<Repository, CreateInput<Repository, Shape<Omitted, Values, Owner>>, Omitted, Values, Owner, Dependencies, false>) => EntityUseCase<Repository, Options, CreateInput<Repository, Options>, Dependencies>;
 /** `get`: for a repository with `findById`. */
-export type GetMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository>>;
+export type GetMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> & StdNoHookOptions = None>(repository: Repository & UseCaseTarget<Repository, "findById">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository>>;
 /** `list`: for a repository with `findPage`. */
-export type ListMaker = <Repository extends AnyRepository, const Options extends StdListOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findPage">, options?: Options) => StepsUseCaseConstructor<{
+export type ListMaker = <Repository extends AnyRepository, const Options extends StdListOptions<Repository> & StdNoHookOptions = None>(repository: Repository & UseCaseTarget<Repository, "findPage">, options?: Options) => StepsUseCaseConstructor<{
     readonly limit: OptionalProperty<typeof Integer>;
     readonly offset: OptionalProperty<typeof Integer>;
 }, {
@@ -145,41 +223,42 @@ export type ListMaker = <Repository extends AnyRepository, const Options extends
     readonly repository: Repository;
 }, OwnerContext<Repository, Options>>;
 /** `update`: for a repository with `findById` and `update`. */
-export type UpdateMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update">, options?: Options) => EntityUseCase<Repository, Options, UpdateInput<Repository>>;
+export type UpdateMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update">, options?: Options & Hookable<Repository, UpdateInput<Repository>, never, None, Owner, Dependencies, true>) => EntityUseCase<Repository, Options, UpdateInput<Repository>, Dependencies>;
 /** `delete`: for a repository with `findById` and `delete`. */
-export type DeleteMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "delete">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository>>;
+export type DeleteMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "delete">, options?: Options & Hookable<Repository, ById<Repository>, never, None, Owner, Dependencies, true>) => EntityUseCase<Repository, Options, ById<Repository>, Dependencies>;
 /** `restore`: for a repository with soft deletion and the `restore` action. */
 export type RestoreMaker = <Repository extends AnyRepository, const Options extends StdUseCaseOptions & {
     readonly as?: string;
-} = None>(repository: Repository & UseCaseTarget<Repository, "restore">, options?: Options) => StepsUseCaseConstructor<ById<Repository>, EntityResponse<Repository, Options>, {
+} = None, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "restore">, options?: Options & Hookable<Repository, ById<Repository>, never, None, undefined, Dependencies, false>) => StepsUseCaseConstructor<ById<Repository>, EntityResponse<Repository, Options>, {
     readonly repository: Repository;
-}>;
+} & Dependencies>;
 /** `publish` and `unpublish`: for a publishable entity. */
-export type PublishMaker = <Repository extends AnyRepository, const Options extends StdLifecycleOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
+export type PublishMaker = <Repository extends AnyRepository, const Options extends StdLifecycleOptions<Repository> = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
     publish(at?: string): unknown;
     unpublish(): unknown;
-}, "publishable">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository>>;
+}, "publishable">, options?: Options & Hookable<Repository, ById<Repository>, never, None, Owner, Dependencies, true>) => EntityUseCase<Repository, Options, ById<Repository>, Dependencies>;
 /** `archive` and `unarchive`: for an archivable entity. */
-export type ArchiveMaker = <Repository extends AnyRepository, const Options extends StdLifecycleOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
+export type ArchiveMaker = <Repository extends AnyRepository, const Options extends StdLifecycleOptions<Repository> = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
     archive(at?: string): unknown;
     readonly isArchived: boolean;
-}, "archivable">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository>>;
+}, "archivable">, options?: Options & Hookable<Repository, ById<Repository>, never, None, Owner, Dependencies, true>) => EntityUseCase<Repository, Options, ById<Repository>, Dependencies>;
 /** `tag` and `untag`: for a taggable entity. */
-export type TagMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
+export type TagMaker = <Repository extends AnyRepository, const Options extends StdEntityOptions<Repository> = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findById" | "update", {
     tag(...tags: string[]): unknown;
     untag(...tags: string[]): unknown;
-}, "taggable">, options?: Options) => EntityUseCase<Repository, Options, ById<Repository> & {
+}, "taggable">, options?: Options & Hookable<Repository, TagInput<Repository>, never, None, Owner, Dependencies, true>) => EntityUseCase<Repository, Options, TagInput<Repository>, Dependencies>;
+type TagInput<Repository> = ById<Repository> & {
     readonly tags: IBlueprintList<typeof StringProperty>;
-}>;
+};
 type Authenticatable = {
     verifyPassword(plain: string): Promise<boolean>;
 };
 /** `register`: for an authenticatable entity, with `findByEmail` and `create`. */
-export type RegisterMaker = <Repository extends AnyRepository, const Options extends StdCreateOptions<Repository> = None>(repository: Repository & UseCaseTarget<Repository, "findByEmail" | "create", Authenticatable, "authenticatable">, options?: Options) => EntityUseCase<Repository, Options, CreateInput<Repository, Options>>;
+export type RegisterMaker = <Repository extends AnyRepository, const Options extends StdCreateOptions<Repository> = None, const Omitted extends KeyOf<Repository> = never, const Values = None, const Owner = undefined, const Dependencies extends UseCaseCollection = None>(repository: Repository & UseCaseTarget<Repository, "findByEmail" | "create", Authenticatable, "authenticatable">, options?: Options & Hookable<Repository, CreateInput<Repository, Shape<Omitted, Values, Owner>>, Omitted, Values, Owner, Dependencies, false>) => EntityUseCase<Repository, Options, CreateInput<Repository, Options>, Dependencies>;
 /** `login`: for an authenticatable entity, with `findByEmail`. */
 export type LoginMaker = <Repository extends AnyRepository, const Options extends StdUseCaseOptions & {
     readonly as?: string;
-} = None>(repository: Repository & UseCaseTarget<Repository, "findByEmail", Authenticatable, "authenticatable">, options?: Options) => StepsUseCaseConstructor<{
+} & StdNoHookOptions = None>(repository: Repository & UseCaseTarget<Repository, "findByEmail", Authenticatable, "authenticatable">, options?: Options) => StepsUseCaseConstructor<{
     readonly email: FieldAt<Props<Repository>, "email">;
     readonly password: typeof StringProperty;
 }, EntityResponse<Repository, Options>, {

package/dist/testing/index.d.ts

@@ -1,2 +1,4 @@
+export type { MemoryPublisher } from "./memory-publisher.js";
+export { memoryPublisher } from "./memory-publisher.js";
 export type { ContractRunner, ProviderContractOptions, } from "./provider-contract.js";
 export { providerContract } from "./provider-contract.js";

package/dist/testing/index.js

@@ -1,11 +1,25 @@
-import"../index-r78dsvtc.js";
+import"../index-qxfkyd6k.js";
 import {
   RepositoryUniqueViolation2,
   RepositoryEntityNotFound2,
+  RepositoryConcurrencyConflict2,
   blueprintOf2,
   entityOf2
-} from "../index-q6hggpzw.js";
+} from "../index-t5qwtyj5.js";
 
+// src/testing/memory-publisher.ts
+function memoryPublisher() {
+  const published = [];
+  return {
+    published,
+    publish(topic, event) {
+      published.push({ topic, event });
+    },
+    clear() {
+      published.length = 0;
+    }
+  };
+}
 // src/testing/provider-contract.ts
 function contextOf(name = "Accounts") {
   class Account extends entityOf2(blueprintOf2((ctx) => ({ email: ctx.string, name: ctx.string }))) {
@@ -43,6 +57,11 @@ function providerContract(runner, makeProvider, options = {}) {
     };
     return { provider, context, seed };
   }
+  const gated = (capability) => (name, body) => it(name, async () => {
+    const enabled = options[capability] ?? (await makeProvider()).capabilities?.[capability];
+    if (enabled === true)
+      await body();
+  });
   describe("provider contract", () => {
     describe("writes and reads", () => {
       it("inserts and finds by id, empty provider counts zero", async () => {
@@ -468,6 +487,80 @@ function providerContract(runner, makeProvider, options = {}) {
         })).toBe(5);
       });
     });
+    describe("indexes", () => {
+      const indexed = (name, body) => it(name, async () => {
+        const enabled = options.indexes ?? (await makeProvider()).capabilities?.indexes;
+        if (enabled === true)
+          await body();
+      });
+      const seeded = async () => {
+        const f = await fixture();
+        const context = {
+          ...f.context,
+          indexes: {
+            byGroup: { where: ["group"], orderBy: "n" },
+            byName: { where: ["name"] }
+          }
+        };
+        const rows = [
+          row({ n: 3, group: 1, name: "Gil" }),
+          row({ group: 1, name: "Érico" }),
+          row({ n: 2, group: 2, name: "Ana" }),
+          row({ n: 2, group: 1, name: "Ana" }),
+          row({ n: 1, group: 1, name: "Bia" }),
+          row({ n: 4, group: 2, name: "Zoe" })
+        ];
+        for (const data of rows)
+          await f.provider.insert(context, data);
+        await f.provider.update(context, {
+          ...rows[4],
+          deletedAt: "2024-01-01T00:00:00.000Z"
+        });
+        return { ...f, context };
+      };
+      indexed("an indexed query gives what the scan gives", async () => {
+        const { provider, context } = await seeded();
+        const queries = [
+          ["byGroup", { where: { group: 1 } }],
+          [
+            "byGroup",
+            {
+              where: { group: 1 },
+              orderBy: [{ key: "n" }, { key: "id" }]
+            }
+          ],
+          [
+            "byGroup",
+            {
+              where: { group: 1, name: "Ana" },
+              orderBy: [{ key: "n", direction: "desc" }, { key: "id" }],
+              limit: 2,
+              offset: 1
+            }
+          ],
+          [
+            "byGroup",
+            {
+              where: { group: 1 },
+              orderBy: [{ key: "n" }, { key: "id" }],
+              withDeleted: true
+            }
+          ],
+          ["byName", { where: { name: "Ana" }, orderBy: [{ key: "id" }] }]
+        ];
+        for (const [index, query] of queries) {
+          expect(ids(await provider.findMany(context, { ...query, index }))).toEqual(ids(await provider.findMany(context, query)));
+          expect(await provider.count(context, {
+            ...query,
+            index
+          })).toBe(await provider.count(context, query));
+          expect((await provider.findOne(context, {
+            ...query,
+            index
+          }))?.id).toBe((await provider.findOne(context, query))?.id);
+        }
+      });
+    });
     const withTransactions = async () => {
       const enabled = options.transactions ?? (await makeProvider()).capabilities?.transactions;
       return enabled === true;
@@ -592,8 +685,260 @@ function providerContract(runner, makeProvider, options = {}) {
         expect(await provider.count(context)).toBe(0);
       });
     });
+    describe("versioning", () => {
+      const versioned = gated("versioning");
+      versioned("update writes with the expected version, and throws RepositoryConcurrencyConflict with a stale one", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 1 });
+        await seed(data);
+        await provider.update(context, { ...data, name: "Bia", version: 2 }, { expectedVersion: 1 });
+        const stale = await failure(provider.update(context, { ...data, name: "Caio", version: 2 }, { expectedVersion: 1 }));
+        expect(stale instanceof RepositoryConcurrencyConflict2).toBe(true);
+        const { details } = stale;
+        expect([details.id, details.expected]).toEqual([data.id, 1]);
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual({ ...data, name: "Bia", version: 2 });
+      });
+      versioned("two updates with the same expected version: exactly one succeeds", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 1 });
+        await seed(data);
+        const results = await Promise.allSettled(["Bia", "Caio"].map((name) => provider.update(context, { ...data, name, version: 2 }, { expectedVersion: 1 })));
+        const rejected = results.filter((result) => result.status === "rejected");
+        expect(rejected.length).toBe(1);
+        expect(rejected[0]?.reason instanceof RepositoryConcurrencyConflict2).toBe(true);
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.version).toBe(2);
+      });
+      versioned("update without an expected version ignores the stored one", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ version: 3 });
+        await seed(data);
+        await provider.update(context, { ...data, name: "Bia", version: 1 });
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual({ ...data, name: "Bia", version: 1 });
+      });
+      versioned("an unknown id is still RepositoryEntityNotFound", async () => {
+        const { provider, context } = await fixture();
+        const error = await failure(provider.update(context, row({ version: 2 }), {
+          expectedVersion: 1
+        }));
+        expect(error instanceof RepositoryEntityNotFound2).toBe(true);
+      });
+    });
+    describe("atomic", () => {
+      const atomic = gated("atomic");
+      const increment = (provider, ...args) => provider.increment(...args);
+      atomic("increment adds the deltas, stores set and gives the row", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 2, age: 30 });
+        await seed(data);
+        const stored = await increment(provider, context, data.id, { visits: 3, age: -1, n: 5 }, { set: { name: "Bia" } });
+        const expected = { ...data, visits: 5, age: 29, n: 5, name: "Bia" };
+        expect(stored).toEqual(expected);
+        expect(await provider.findOne(context, { where: { id: data.id } })).toEqual(expected);
+      });
+      atomic("N concurrent increments sum to N", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 0 });
+        await seed(data);
+        await Promise.all(Array.from({ length: 25 }, () => increment(provider, context, data.id, { visits: 1 })));
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.visits).toBe(25);
+      });
+      atomic("a missing id is RepositoryEntityNotFound without create, and inserted with it", async () => {
+        const { provider, context } = await fixture();
+        const data = row({ visits: 1 });
+        const missing = await failure(increment(provider, context, data.id, { visits: 1 }));
+        expect(missing instanceof RepositoryEntityNotFound2).toBe(true);
+        expect(await provider.count(context)).toBe(0);
+        const created = await increment(provider, context, data.id, { visits: 1 }, { create: data, set: { name: "Bia" } });
+        expect(created).toEqual(data);
+        const again = await increment(provider, context, data.id, { visits: 1 }, { create: data });
+        expect(again.visits).toBe(2);
+        expect(await provider.count(context)).toBe(1);
+      });
+      atomic("concurrent increments with create lose nothing", async () => {
+        const { provider, context } = await fixture();
+        const data = row({ visits: 1 });
+        await Promise.all(Array.from({ length: 10 }, () => increment(provider, context, data.id, { visits: 1 }, { create: data })));
+        const stored = await provider.findOne(context, {
+          where: { id: data.id }
+        });
+        expect(stored?.visits).toBe(10);
+      });
+      atomic("soft-deleted rows are not incremented", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ visits: 1, deletedAt: "2024-01-01T00:00:00.000Z" });
+        await seed(data);
+        const error = await failure(increment(provider, context, data.id, { visits: 1 }));
+        expect(error instanceof RepositoryEntityNotFound2).toBe(true);
+        const stored = await provider.findOne(context, {
+          where: { id: data.id },
+          withDeleted: true
+        });
+        expect(stored?.visits).toBe(1);
+      });
+      atomic("an increment of version makes an update with the old one conflict", async () => {
+        const { provider, context, seed } = await fixture();
+        if ((options.versioning ?? provider.capabilities?.versioning) !== true)
+          return;
+        const data = row({ visits: 0, version: 1 });
+        await seed(data);
+        const stored = await increment(provider, context, data.id, {
+          visits: 1,
+          version: 1
+        });
+        expect(stored.version).toBe(2);
+        const error = await failure(provider.update(context, { ...data, name: "Bia", version: 2 }, { expectedVersion: 1 }));
+        expect(error instanceof RepositoryConcurrencyConflict2).toBe(true);
+        expect((await provider.findOne(context, { where: { id: data.id } }))?.visits).toBe(1);
+      });
+      atomic("an expired row counts as absent: not found, or replaced by create", async () => {
+        const provider = await makeProvider();
+        if ((options.expiry ?? provider.capabilities?.expiry) !== true)
+          return;
+        const now = "2026-06-01T12:00:00.000Z";
+        const context = {
+          ...contextOf(),
+          expiry: { key: "expiresAt" }
+        };
+        const window = row({
+          visits: 7,
+          expiresAt: "2026-06-01T11:00:00.000Z"
+        });
+        const live = row({
+          visits: 1,
+          expiresAt: "2026-06-01T13:00:00.000Z"
+        });
+        await provider.insert(context, window);
+        await provider.insert(context, live);
+        const missing = await failure(increment(provider, context, window.id, { visits: 1 }, {
+          now
+        }));
+        expect(missing instanceof RepositoryEntityNotFound2).toBe(true);
+        const fresh = {
+          id: window.id,
+          email: window.email,
+          name: "fresh",
+          visits: 1,
+          expiresAt: "2026-06-01T13:00:00.000Z"
+        };
+        const created = await increment(provider, context, window.id, { visits: 1 }, { create: fresh, set: { name: "incremented" }, now });
+        expect(created).toEqual(fresh);
+        const again = await increment(provider, context, window.id, { visits: 1 }, { create: fresh, set: { name: "incremented" }, now });
+        expect([again.visits, again.name]).toEqual([2, "incremented"]);
+        const counted = await increment(provider, context, live.id, { visits: 1 }, { create: { ...live, visits: 100 }, now });
+        expect(counted.visits).toBe(2);
+      });
+    });
+    describe("expiry", () => {
+      const expiring = gated("expiry");
+      const NOW = "2026-06-01T12:00:00.000Z";
+      const seeded = async () => {
+        const provider = await makeProvider();
+        const context = {
+          ...contextOf(),
+          expiry: { key: "expiresAt" }
+        };
+        const [past, edge, never, future] = [
+          row({ n: 1, expiresAt: "2026-05-01T00:00:00.000Z" }),
+          row({ n: 2, expiresAt: NOW }),
+          row({ n: 3 }),
+          row({ n: 4, expiresAt: "2026-07-01T00:00:00.000Z" })
+        ];
+        for (const data of [past, edge, never, future])
+          await provider.insert(context, data);
+        return { provider, context, past, edge, never, future };
+      };
+      expiring("reads leave out rows whose date is at or before now", async () => {
+        const { provider, context, past, edge, never, future } = await seeded();
+        const query = { now: NOW };
+        expect(ids(await provider.findMany(context, query))).toEqual([
+          never.id,
+          future.id
+        ]);
+        expect(await provider.count(context, query)).toBe(2);
+        expect(await provider.findOne(context, {
+          ...query,
+          where: { id: past.id }
+        })).toBe(undefined);
+        expect(await provider.findOne(context, {
+          ...query,
+          where: { id: edge.id }
+        })).toBe(undefined);
+        expect((await provider.findOne(context, {
+          ...query,
+          where: { id: future.id }
+        }))?.id).toBe(future.id);
+        expect(ids(await provider.findMany(context, {
+          ...query,
+          where: { id: { in: [past.id, never.id] } }
+        }))).toEqual([never.id]);
+      });
+      expiring("a row without a date never expires", async () => {
+        const { provider, context, never } = await seeded();
+        const later = { now: "2999-01-01T00:00:00.000Z" };
+        expect(ids(await provider.findMany(context, later))).toEqual([
+          never.id
+        ]);
+        expect(await provider.count(context, later)).toBe(1);
+      });
+      expiring("withExpired gives the expired rows too", async () => {
+        const { provider, context, past, edge, never, future } = await seeded();
+        const query = { now: NOW, withExpired: true };
+        expect(ids(await provider.findMany(context, query))).toEqual([
+          past.id,
+          edge.id,
+          never.id,
+          future.id
+        ]);
+        expect(await provider.count(context, query)).toBe(4);
+        expect((await provider.findOne(context, {
+          ...query,
+          where: { id: past.id }
+        }))?.id).toBe(past.id);
+      });
+      expiring("leaves expired rows out of a read after a position", async () => {
+        const enabled = options.keyset ?? (await makeProvider()).capabilities?.keyset;
+        if (enabled !== true)
+          return;
+        const { provider, context, past, edge, never, future } = await seeded();
+        const orderBy = [{ key: "n" }, { key: "id" }];
+        expect(ids(await provider.findMany(context, {
+          now: NOW,
+          orderBy,
+          after: [0, ""]
+        }))).toEqual([never.id, future.id]);
+        expect(ids(await provider.findMany(context, {
+          now: NOW,
+          orderBy,
+          after: [1, past.id],
+          withExpired: true
+        }))).toEqual([edge.id, never.id, future.id]);
+      });
+      expiring("unique keys still count expired rows", async () => {
+        const { provider, context, past } = await seeded();
+        const error = await failure(provider.insert(context, row({ email: past.email })));
+        expect(error instanceof RepositoryUniqueViolation2).toBe(true);
+        expect(error.details.key).toBe("email");
+        expect(await provider.count(context, { now: NOW, withExpired: true })).toBe(4);
+      });
+      expiring("an entity that does not expire ignores now", async () => {
+        const { provider, context, seed } = await fixture();
+        const data = row({ expiresAt: "2000-01-01T00:00:00.000Z" });
+        await seed(data);
+        expect(ids(await provider.findMany(context, { now: NOW }))).toEqual([
+          data.id
+        ]);
+        expect(await provider.count(context, { now: NOW })).toBe(1);
+      });
+    });
   });
 }
 export {
+  memoryPublisher,
   providerContract
 };

package/dist/testing/memory-publisher.d.ts

@@ -0,0 +1,16 @@
+import type { IEventPublisher, PublishedEvent } from "../core/event-policy/types/event-policy.interface.js";
+/** A publisher that keeps what it is given, for tests. */
+export interface MemoryPublisher extends IEventPublisher {
+    /** Each publish, in order. */
+    readonly published: readonly {
+        readonly topic: string;
+        readonly event: PublishedEvent;
+    }[];
+    /** Forgets what was published. */
+    clear(): void;
+}
+/**
+ * A publisher for `applicationOf({ publishers })` in tests: it keeps each
+ * `{ topic, event }` it is given in `published`.
+ */
+export declare function memoryPublisher(): MemoryPublisher;

package/dist/testing/provider-contract.d.ts

@@ -18,6 +18,20 @@ export interface ProviderContractOptions {
      * to `provider.capabilities?.keyset`.
      */
     readonly keyset?: boolean;
+    /**
+     * Run the cases of declared indexes (`context.indexes`, `query.index`).
+     * Defaults to `provider.capabilities?.indexes`.
+     */
+    readonly indexes?: boolean;
+    /**
+     * Run the cases of an expected `version` on `update`. Defaults to
+     * `provider.capabilities?.versioning`.
+     */
+    readonly versioning?: boolean;
+    /** Run the cases of `increment`. Defaults to `provider.capabilities?.atomic`. */
+    readonly atomic?: boolean;
+    /** Run the cases of expired records. Defaults to `provider.capabilities?.expiry`. */
+    readonly expiry?: boolean;
 }
 /**
  * Registers the behavior every `IRepositoryProvider` v2 must have. Pass the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@afora/core",
-	"version": "0.0.7",
+	"version": "0.0.8",
 	"description": "Domain modeling on TypeBox: entities with invariants, repositories, use cases, sensitive data masking and layered exceptions, usable by any Standard Schema consumer.",
 	"keywords": [
 		"domain-driven-design",
@@ -84,8 +84,9 @@
 		"test:roundtrip": "bun run --cwd packages/codegen test:roundtrip",
 		"test:mcp": "bun test --cwd packages/mcp",
 		"test:hono": "bun test --cwd packages/hono",
+		"test:ws": "bun test --cwd packages/ws",
 		"test:drizzle": "bun test --cwd packages/drizzle",
-		"build:packages": "bun run build && bun run --cwd packages/codegen build && bun run --cwd packages/mcp build && bun run --cwd packages/hono build && bun run --cwd packages/drizzle build"
+		"build:packages": "bun run build && bun run --cwd packages/codegen build && bun run --cwd packages/mcp build && bun run --cwd packages/hono build && bun run --cwd packages/ws build && bun run --cwd packages/drizzle build"
 	},
 	"dependencies": {
 		"slugify": "^1.6.9"