@afora/core 0.0.8 → 0.0.9

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

@@ -1,10 +1,13 @@
+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 { 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 {
@@ -44,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> {
     /**
@@ -258,12 +295,34 @@ export type RegisterMaker = <Repository extends AnyRepository, const Options ext
 /** `login`: for an authenticatable entity, with `findByEmail`. */
 export type LoginMaker = <Repository extends AnyRepository, const Options extends StdUseCaseOptions & {
     readonly as?: string;
+    /** 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.
@@ -283,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,3 +1,5 @@
+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";