@afora/core 0.0.7 → 0.0.9

package/dist/std/resource.d.ts

@@ -0,0 +1,31 @@
+import type { AnyRepository } from "../core/repository/types/repository.interface.js";
+import type { ResourceAction, ResourceOptions, ResourceUseCases, StdUseCaseContext } from "./use-cases/types.js";
+/**
+ * The use cases of a CRUD resource over `repository`, for the `useCases` of
+ * `commandOf`: the standard `create`, `get`, `list`, `update` and `delete`,
+ * each with the route of a REST resource at `path`.
+ *
+ * ```ts
+ * const Blog = commandOf({
+ * 	name: "Blog",
+ * 	useCases: resourceOf(Posts, { path: "/posts" }),
+ * });
+ * // POST /posts (201), GET /posts, GET /posts/{id}, PATCH /posts/{id}, DELETE /posts/{id}
+ * ```
+ *
+ * It is only a shortcut for
+ * `(ctx) => ({ create: ctx.create(Posts, { route }), ... })`: the command it
+ * goes into is an ordinary one, and `describe()` shows the same standard use
+ * cases. `actions` picks some of the operations, and `access` says who may
+ * call them. A repository that lacks the action of an operation throws
+ * `UseCaseUnavailable` when the command is declared. For anything else an
+ * operation needs (`omit`, `owner`, hooks), write that one with `ctx` and
+ * spread the rest: `(ctx) => ({ ...resourceOf(Posts, options)(ctx), create: ctx.create(Posts, { ... }) })`.
+ */
+export declare function resourceOf<Repository extends AnyRepository, const Actions extends readonly ResourceAction[] = readonly [
+    "create",
+    "get",
+    "list",
+    "update",
+    "delete"
+]>(repository: Repository, options: ResourceOptions<Actions>): (ctx: StdUseCaseContext) => Pick<ResourceUseCases<Repository>, Actions[number]>;

package/dist/std/runtime.d.ts

@@ -78,6 +78,12 @@ export declare function configure(services: RuntimeServices): void;
 export declare function resetRuntime(): void;
 /** The hasher in use; the default is chosen on first call, not at import. */
 export declare function currentHasher(): PasswordHasher;
+/**
+ * Whether the generator in use is the default one, whose ids `Id` accepts as
+ * they are; one that `configure` put in its place is checked as any value.
+ * @internal
+ */
+export declare function makesDefaultIds(): boolean;
 /** Makes an id with the generator in use. */
 export declare function generateId(): string;
 /** `verifySync` of the hasher in use, or throws `SyncVerifyUnsupported`. */

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

@@ -1,5 +1,9 @@
-import type { LoginMaker, RegisterMaker } from "./types.js";
+import type { LoginMaker, LogoutMaker, RefreshMaker, RegisterMaker } from "./types.js";
 /** Stores an authenticatable entity, unless its email is taken. */
 export declare const register: import("../../index.js").IUseCasePlugin<"register", RegisterMaker>;
 /** Gives the authenticatable entity of an email, when the password matches. */
 export declare const login: import("../../index.js").IUseCasePlugin<"login", LoginMaker>;
+/** Exchanges a refresh token for new tokens. */
+export declare const refresh: import("../../index.js").IUseCasePlugin<"refresh", RefreshMaker>;
+/** Gives empty tokens, for a route that keeps them in cookies to remove them. */
+export declare const logout: import("../../index.js").IUseCasePlugin<"logout", LogoutMaker>;

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

@@ -3,11 +3,13 @@ import type { AnyExceptionClass } from "../../core/use-case/use-case.js";
 import { type Options, type Step } from "./shared.js";
 import type { CreateMaker, DeleteMaker, GetMaker, ListMaker, RestoreMaker, UpdateMaker } from "./types.js";
 /**
- * The declaration of `create` and of `register`, which adds `before` and
- * its errors: an input of the keys of the entity, the entity built from it
- * and stored.
+ * The declaration of `create` and of `register`, which adds `checks` and
+ * their errors: an input of the keys of the entity, the entity built from
+ * it and stored. The option `before` runs first, and the steps after it read
+ * the input it gives; `checks` read it under `$input` all the same, rooted
+ * by the function given.
  */
-export declare function createCompilation(target: UseCaseTargetInfo, options: Options, verb: string, before?: readonly Step[], errors?: readonly AnyExceptionClass[]): UseCaseCompilation;
+export declare function createCompilation(target: UseCaseTargetInfo, options: Options, verb: string, checks?: (input: string) => readonly Step[], errors?: readonly AnyExceptionClass[]): UseCaseCompilation;
 /** Builds an entity from the input and stores it. */
 export declare const create: import("../../index.js").IUseCasePlugin<"create", CreateMaker>;
 /** Gives the entity of an id. */

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

@@ -6,6 +6,6 @@ import type { StdUseCasePlugins } from "./types.js";
  * `list`, `update`, `delete` and `restore` for any entity; `publish`,
  * `unpublish`, `archive`, `unarchive`, `tag` and `untag` for the entities
  * with those record plugins; `register` and `login` for the
- * authenticatable ones. `StdUseCases.context` is that `ctx`.
+ * authenticatable ones, and `refresh` and `logout` for the tokens of `login`. `StdUseCases.context` is that `ctx`.
  */
 export declare const StdUseCases: IUseCaseCatalog<StdUseCasePlugins>;

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

@@ -1,6 +1,6 @@
 import type { BlueprintField } from "../../core/blueprint/types/blueprint.interface.js";
 import type { UseCaseCompilation, UseCaseFieldPlan, UseCaseTargetInfo } from "../../core/use-case/types/plugin.interface.js";
-import type { AnyExceptionClass } from "../../core/use-case/use-case.js";
+import type { AnyExceptionClass, UseCaseDependency } from "../../core/use-case/use-case.js";
 /** A blueprint of the fields given, with no context of properties. */
 export declare const fields: import("../../index.js").BlueprintBuilder<readonly []>;
 export type Options = Readonly<Record<string, unknown>>;
@@ -10,8 +10,10 @@ export declare const capitalize: (key: string) => string;
 export declare function literal(value: unknown): unknown;
 /** The option `key`, checked to be one of the `allowed` options of the use case. */
 export declare function checkOptions(target: UseCaseTargetInfo, options: Options, allowed: readonly string[]): void;
-/** The name, description, tags and `deprecated` of the use case. */
-export declare function metaOf(target: UseCaseTargetInfo, options: Options, verb: string): Pick<UseCaseCompilation, "name" | "description" | "tags" | "deprecated">;
+/** The options of the use cases that write: `before`, `after`, `dependencies`, `throws`. */
+export declare const HOOKS: readonly ["before", "after", "dependencies", "throws"];
+/** The name, description, tags, `deprecated`, route and access of the use case. */
+export declare function metaOf(target: UseCaseTargetInfo, options: Options, verb: string): Pick<UseCaseCompilation, "name" | "description" | "tags" | "deprecated" | "route" | "access">;
 /** The key of the response that holds the entity: the option `as`, `item` by default. */
 export declare function asOf(target: UseCaseTargetInfo, options: Options): string;
 /** The error of `kind` the options give, else `fallback`. */
@@ -43,18 +45,44 @@ export declare function contextOf(owner: Owner | undefined): Pick<UseCaseCompila
  * when there is none, and when it is not the caller's.
  */
 export declare function loadSteps(owner: Owner | undefined, notFound: AnyExceptionClass): Step[];
+/** What the options `before`, `after`, `dependencies` and `throws` add to a use case. */
+export interface Hooks {
+    /** The root of the input the steps read: `$input`, or `$prepared` after `before`. */
+    readonly input: string;
+    /** The dependencies the options give, joined to those the use case makes. */
+    readonly dependencies: Readonly<Record<string, UseCaseDependency>>;
+    readonly throws: readonly AnyExceptionClass[];
+    /** The step of `before`, if any: it binds `prepared`, the input it gives back or the one it got. */
+    before(entity?: string): Step[];
+    /** The step of `after`, if any, over the entity written. */
+    after(entity: string): Step[];
+}
+/**
+ * The options `before`, `after`, `dependencies` and `throws`, checked: each
+ * hook becomes a `run` step, whose function gets `{ input, entity?,
+ * dependencies, context }` (the bound dependencies of the call, overrides
+ * included).
+ */
+export declare function hooksOf(target: UseCaseTargetInfo, options: Options): Hooks;
+/**
+ * The dependencies a use case makes, joined to those of the option
+ * `dependencies`; a name taken by both is unavailable.
+ */
+export declare function joinDependencies(target: UseCaseTargetInfo, made: Readonly<Record<string, UseCaseDependency>>, hooks: Hooks): Readonly<Record<string, UseCaseDependency>>;
 /** The id field of the entity of `target`. */
 export declare const idOf: (target: UseCaseTargetInfo) => BlueprintField;
 /** The classes of `errors`, each once. */
 export declare const distinct: (...errors: readonly AnyExceptionClass[]) => AnyExceptionClass[];
 /**
  * A use case over one entity found by id: `{ id }` in, `{ [as]: entity }`
- * out; loads it, checks the owner, runs `steps` (which leave the entity to
- * give under `result`) and gives it.
+ * out; loads it, checks the owner, runs `before` (with `hooks`), `steps`
+ * (which leave the entity to give under `result`) and `after`, and gives it.
+ * `steps` read the input under `input`: `$input`, or what `before` gave.
  */
 export declare function entityUseCase(target: UseCaseTargetInfo, options: Options, verb: string, allowed: readonly string[], steps: (context: {
     readonly owner: Owner | undefined;
+    readonly input: string;
 }) => {
     readonly steps: readonly Step[];
     readonly result: string;
-}): UseCaseCompilation;
+}, hooks?: boolean): UseCaseCompilation;

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

@@ -1,10 +1,14 @@
-import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, IBlueprint, IBlueprintCollection, IBlueprintList, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "../../core/blueprint/types/blueprint.interface.js";
+import type { DescribedJwtOptions } from "../../core/auth/types/jwt.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 { AccessDeclaration } from "../../core/use-case/types/access.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 { RouteSettings } from "../../core/use-case/types/route.interface.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;
@@ -43,7 +47,41 @@ export interface StdUseCaseOptions {
     readonly tags?: readonly string[];
     readonly deprecated?: boolean;
     readonly errors?: StdUseCaseErrors;
+    /** Where the use case is served over HTTP: the `route` of `useCaseOf`. */
+    readonly route?: RouteSettings;
+    /** Who may call it: the `access` of `useCaseOf`. */
+    readonly access?: AccessDeclaration;
 }
+/**
+ * The tokens `login` and `refresh` issue: the options of `jwtOf`, plus what
+ * a token says of the entity. JSON, so it lives in an `afora.json`: the
+ * secret is named by its environment variable (`{ env: "JWT_SECRET" }`).
+ * Experimental: it may change in any release.
+ */
+export interface StdTokenOptions extends DescribedJwtOptions {
+    /** Also issues a refresh token, which `refresh` exchanges; `expiresIn` is its life in seconds. */
+    readonly refresh?: {
+        readonly expiresIn: number;
+    };
+    /** Scopes every token gets. */
+    readonly scopes?: readonly string[];
+    /** A key of the entity that holds a list of scopes, added to `scopes`. */
+    readonly scopesFrom?: string;
+    /** Claims of the token, each from a key of the entity: `{ tenant: "tenantId" }`. */
+    readonly claims?: {
+        readonly [claim: string]: string;
+    };
+}
+/** The response keys the `token` option adds. */
+type TokenResponse<Options> = Options extends {
+    readonly token: infer Token;
+} ? {
+    readonly token: typeof StringProperty;
+} & (Token extends {
+    readonly refresh: object;
+} ? {
+    readonly refreshToken: typeof StringProperty;
+} : unknown) : unknown;
 /** Who owns the entities: the caller, whose id the context gives. */
 export interface StdOwnerOption<Repository> {
     /**
@@ -88,6 +126,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 +222,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 +237,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,46 +260,69 @@ 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<{
+    /** Issues a token for the entity (and a refresh token, with `refresh`), in the response. */
+    readonly token?: StdTokenOptions;
+} & 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>, {
+}, EntityResponse<Repository, Options> & TokenResponse<Options>, {
     readonly repository: Repository;
 }>;
+/** `refresh`: exchanges a refresh token of `login` for new tokens; needs `findById`. */
+export type RefreshMaker = <Repository extends AnyRepository>(repository: Repository & UseCaseTarget<Repository, "findById">, options: StdUseCaseOptions & {
+    readonly token: StdTokenOptions & {
+        readonly refresh: {
+            readonly expiresIn: number;
+        };
+    };
+} & StdNoHookOptions) => StepsUseCaseConstructor<{
+    readonly refreshToken: typeof StringProperty;
+}, {
+    readonly token: typeof StringProperty;
+    readonly refreshToken: typeof StringProperty;
+}, {
+    readonly repository: Repository;
+}>;
+/** `logout`: gives empty tokens, which a route with `setCookie` turns into removed cookies. */
+export type LogoutMaker = <Repository extends AnyRepository>(repository: Repository, options?: StdUseCaseOptions & StdNoHookOptions) => StepsUseCaseConstructor<Record<never, never>, {
+    readonly token: typeof StringProperty;
+    readonly refreshToken: typeof StringProperty;
+}, Record<never, never>>;
 /**
  * The standard use cases, by name: what the `useCases` of `commandOf` gets
  * to pick from, each called with a repository and its options.
@@ -204,9 +342,46 @@ export interface StdUseCaseContext {
     readonly untag: TagMaker;
     readonly register: RegisterMaker;
     readonly login: LoginMaker;
+    readonly refresh: RefreshMaker;
+    readonly logout: LogoutMaker;
 }
 /** The plugins of `StdUseCases`, by name. */
 export type StdUseCasePlugins = {
     readonly [Name in keyof StdUseCaseContext]: IUseCasePlugin<Name, StdUseCaseContext[Name]>;
 };
+/** The operations `resourceOf` can give. */
+export type ResourceAction = "create" | "get" | "list" | "update" | "delete";
+/** The use cases of `resourceOf`, by operation: the standard ones, with no option but their route and access. */
+export interface ResourceUseCases<Repository extends AnyRepository> {
+    readonly create: EntityUseCase<Repository, None, CreateInput<Repository, None>>;
+    readonly get: EntityUseCase<Repository, None, ById<Repository>>;
+    readonly list: StepsUseCaseConstructor<{
+        readonly limit: OptionalProperty<typeof Integer>;
+        readonly offset: OptionalProperty<typeof Integer>;
+    }, {
+        readonly items: IBlueprintList<EntityOf<Repository>>;
+        readonly total: typeof Integer;
+        readonly limit: typeof Integer;
+        readonly offset: typeof Integer;
+    }, {
+        readonly repository: Repository;
+    }>;
+    readonly update: EntityUseCase<Repository, None, UpdateInput<Repository>>;
+    readonly delete: EntityUseCase<Repository, None, ById<Repository>>;
+}
+/** The options of `resourceOf`. */
+export interface ResourceOptions<Actions extends readonly ResourceAction[] = readonly ResourceAction[]> {
+    /** The path of the collection, e.g. `"/posts"`; one entity is at `{path}/{id}`. */
+    readonly path: string;
+    /** The operations to give; all five by default. Each needs its repository action. */
+    readonly actions?: Actions;
+    /**
+     * Who may call: one declaration for every operation, or one per operation
+     * (`{ create: { scopes: ["posts:write"] }, get: { public: true } }`; an
+     * operation left out declares none).
+     */
+    readonly access?: AccessDeclaration | {
+        readonly [Action in ResourceAction]?: AccessDeclaration;
+    };
+}
 export {};

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

@@ -0,0 +1,32 @@
+import type { Authenticator, HttpOptions, SinkStage } from "../adapters.js";
+import type { ContractRunner } from "./provider-contract.js";
+/** What the kit needs of a sink that serves HTTP. */
+export interface HttpProviderContractSettings<Server> {
+    /** The sink under test, made with these options and this authenticator. */
+    sink(options: HttpOptions, hooks: {
+        readonly authenticator?: Authenticator;
+    }): SinkStage<Server, HttpOptions>;
+    /** Sends a request to the server the sink built, and gives its response. */
+    fetch(server: Server, request: Request): Response | Promise<Response>;
+    /** Releases the server (a listening socket), after each case. */
+    close?(server: Server): void | Promise<void>;
+}
+/**
+ * The cases every sink that serves HTTP must pass, whatever its server: the
+ * routes use cases declare, where each input key is read from, the context,
+ * access, statuses, problems, cookies, the request id and the document. A
+ * sink built on `compileRoutes` passes when it routes each method and path
+ * to `handle` and sends the result as is.
+ *
+ * ```ts
+ * import { describe, expect, it } from "bun:test";
+ * import { httpProviderContract } from "@afora/core/testing";
+ *
+ * httpProviderContract(
+ * 	"hono",
+ * 	{ sink: (options, hooks) => hono(options, hooks), fetch: (app, request) => app.fetch(request) },
+ * 	{ describe, it, expect },
+ * );
+ * ```
+ */
+export declare function httpProviderContract<Server>(name: string, settings: HttpProviderContractSettings<Server>, runner: ContractRunner): void;

package/dist/testing/index.d.ts

@@ -1,2 +1,6 @@
+export type { HttpProviderContractSettings } from "./http-provider-contract.js";
+export { httpProviderContract } from "./http-provider-contract.js";
+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";