@afora/core 0.0.2 → 0.0.4

package/dist/core/use-case/use-case.d.ts

@@ -1,8 +1,11 @@
 import type { AnyBlueprint, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
 import type { EntityEvent } from "../entity/event.js";
 import { type AnyEnvironment, type EnvironmentValue } from "../environment/environment.js";
+import { type DeclaredExceptionClass } from "../exception/exception.js";
+import { type ILogger, type LoggerDeclaration } from "../logger/logger.js";
 import type { AnyRepository } from "../repository/types/repository.interface.js";
 import { Kind } from "../symbols/kind.js";
+import type { UseCaseStep } from "./steps/types/steps.interface.js";
 /** A concrete UseCase declaration, usable as a dependency. */
 export interface AnyUseCaseClass {
     readonly [Kind]: "use-case";
@@ -10,16 +13,23 @@ export interface AnyUseCaseClass {
     readonly blueprint: AnyBlueprint;
     readonly response: AnyBlueprint;
     readonly dependencies: UseCaseCollection;
-    new (input: any): {
+    readonly context: AnyBlueprint | undefined;
+    readonly description: string | undefined;
+    readonly tags: readonly string[];
+    readonly deprecated: boolean;
+    readonly errors: readonly AnyExceptionClass[];
+    new (input: any, ...options: any[]): {
         execute(): Promise<unknown>;
         pullEvents(): EntityEvent[];
     };
 }
+/** Any class made by `exceptionOf`. */
+export type AnyExceptionClass = DeclaredExceptionClass<any>;
 /**
  * What a use case can depend on: another use case, a repository made by
- * `repositoryOf`, or an environment made by `environmentOf`.
+ * `repositoryOf`, an environment made by `environmentOf`, or `Logger`.
  */
-export type UseCaseDependency = AnyUseCaseClass | AnyRepository | AnyEnvironment;
+export type UseCaseDependency = AnyUseCaseClass | AnyRepository | AnyEnvironment | LoggerDeclaration;
 export type UseCaseCollection = Readonly<Record<string, UseCaseDependency>>;
 type Declaration = {
     readonly blueprint: AnyBlueprint;
@@ -29,11 +39,26 @@ type Declaration = {
 export type UseCaseInput<Class extends Declaration> = BlueprintInput<Class["blueprint"]["properties"]>;
 export type UseCaseResponse<Class extends Declaration> = BlueprintValue<Class["response"]["properties"]>;
 export type UseCaseDependencies<Class extends Declaration> = DependencyFunctions<Class["dependencies"]>;
+/** The context of a use case class, as `this.context` gives it; `undefined` without one. */
+export type UseCaseContext<Class extends {
+    readonly context: unknown;
+}> = Class["context"] extends IBlueprint<infer Properties> ? Readonly<BlueprintValue<Properties>> : undefined;
+/**
+ * The second argument of the constructor of a use case: `{ context }`,
+ * required when the use case declares a context, not accepted otherwise.
+ */
+export type UseCaseOptions<Context extends IBlueprintCollection | undefined = undefined> = Context extends IBlueprintCollection ? {
+    readonly context: BlueprintInput<Context>;
+} : {
+    readonly context?: undefined;
+};
+/** @internal */
+type OptionsArgs<Context extends IBlueprintCollection | undefined> = Context extends IBlueprintCollection ? [options: UseCaseOptions<Context>] : [];
 /**
  * What a use case gets for a dependency: a function for a use case, the
- * repository itself, or the variables of an environment.
+ * repository itself, the variables of an environment, or an `ILogger`.
  */
-export type DependencyOf<Dependency> = Dependency extends AnyUseCaseClass ? (input: UseCaseInput<Dependency>) => Promise<UseCaseResponse<Dependency>> : Dependency extends AnyEnvironment ? EnvironmentValue<Dependency> : Dependency;
+export type DependencyOf<Dependency> = Dependency extends AnyUseCaseClass ? (input: UseCaseInput<Dependency>) => Promise<UseCaseResponse<Dependency>> : Dependency extends AnyEnvironment ? EnvironmentValue<Dependency> : Dependency extends LoggerDeclaration ? ILogger : Dependency;
 export type DependencyFunctions<Dependencies extends UseCaseCollection> = {
     readonly [Key in keyof Dependencies]: DependencyOf<Dependencies[Key]>;
 };
@@ -44,36 +69,77 @@ export type DependencyFunctions<Dependencies extends UseCaseCollection> = {
 export type DependencyOverrides<Dependencies extends UseCaseCollection> = {
     readonly [Key in keyof Dependencies]?: Dependencies[Key] extends AnyRepository ? Partial<Dependencies[Key]> : DependencyOf<Dependencies[Key]>;
 };
-export interface UseCaseSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection> {
+export interface UseCaseSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> {
     readonly name: string;
     readonly blueprint: IBlueprint<Input>;
     readonly response: IBlueprint<Output>;
     readonly dependencies?: Dependencies;
+    /** What the caller supplies with each call, e.g. the user and the request; validated by this blueprint. */
+    readonly context?: IBlueprint<Exclude<Context, undefined>>;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    /** The exceptions (made by `exceptionOf`) a caller should expect; documentation only. */
+    readonly errors?: readonly AnyExceptionClass[];
 }
-export declare const InvalidUseCaseDeclaration: import("../../index.js").DeclaredExceptionClass<{
+/** `UseCaseSettings` with the `steps` that are its `execute`. */
+export interface UseCaseStepsSettings<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> extends UseCaseSettings<Input, Output, Dependencies, Context> {
+    /**
+     * What the use case does, as data (see `UseCaseStep`): validated here,
+     * interpreted by its `execute`, and described by `describe()`.
+     */
+    readonly steps: readonly UseCaseStep<NoInfer<Dependencies>>[];
+}
+export declare const InvalidUseCaseDeclaration: DeclaredExceptionClass<{
     reason: string;
 }>;
-export declare const UseCaseAlreadyExecuted: import("../../index.js").DeclaredExceptionClass<undefined>;
-export declare const InvalidUseCaseDependencies: import("../../index.js").DeclaredExceptionClass<undefined>;
+export declare const UseCaseAlreadyExecuted: DeclaredExceptionClass<undefined>;
+export declare const InvalidUseCaseDependencies: DeclaredExceptionClass<undefined>;
 /** An operation with validated input, dependency functions and a drainable event queue. */
 export declare abstract class AbstractUseCase<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection> {
     readonly input: Readonly<BlueprintValue<Input>>;
-    constructor(input: BlueprintInput<Input>);
+    constructor(input: BlueprintInput<Input>, ...args: unknown[]);
     /** Default parameter for implementations: `execute(deps = this.dependencies)`. */
     get dependencies(): DependencyFunctions<Dependencies>;
     abstract execute(dependencies?: DependencyOverrides<Dependencies>): Promise<BlueprintValue<Output>>;
     /** Immediately drains collected events; never executes their handlers. */
     pullEvents(): EntityEvent[];
 }
-export type UseCaseConstructor<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection> = (abstract new (input: BlueprintInput<Input>) => AbstractUseCase<Input, Output, Dependencies>) & {
+/** What every use case class carries, abstract or not. */
+type UseCaseStatics<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined> = {
     readonly [Kind]: "use-case";
     readonly useCaseName: string;
     readonly blueprint: IBlueprint<Input>;
     readonly response: IBlueprint<Output>;
     readonly dependencies: Dependencies;
+    /** The blueprint of the context of each call, or `undefined`. */
+    readonly context: Context extends IBlueprintCollection ? IBlueprint<Context> : undefined;
+    readonly description: string | undefined;
+    readonly tags: readonly string[];
+    readonly deprecated: boolean;
+    /** The exceptions a caller should expect. */
+    readonly errors: readonly AnyExceptionClass[];
+};
+/** What a use case instance carries beyond `AbstractUseCase`. */
+type UseCaseInstanceContext<Context extends IBlueprintCollection | undefined> = {
+    /** What the caller supplied with the call, parsed and frozen; `undefined` without a declared context. */
+    readonly context: Context extends IBlueprintCollection ? Readonly<BlueprintValue<Context>> : undefined;
 };
-/** Declares an abstract operation. Extend it and implement an async execute method. */
-export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>>(settings: UseCaseSettings<Input, Output, Dependencies>): UseCaseConstructor<Input, Output, Dependencies>;
+export type UseCaseConstructor<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> = (abstract new (input: BlueprintInput<Input>, ...options: OptionsArgs<Context>) => AbstractUseCase<Input, Output, Dependencies> & UseCaseInstanceContext<Context>) & UseCaseStatics<Input, Output, Dependencies, Context>;
+/**
+ * What `useCaseOf` gives with `steps`: concrete, its `execute` interprets the
+ * steps. A subclass may still override `execute`.
+ */
+export type StepsUseCaseConstructor<Input extends IBlueprintCollection, Output extends IBlueprintCollection, Dependencies extends UseCaseCollection, Context extends IBlueprintCollection | undefined = undefined> = (new (input: BlueprintInput<Input>, ...options: OptionsArgs<Context>) => Omit<AbstractUseCase<Input, Output, Dependencies>, "execute"> & UseCaseInstanceContext<Context> & {
+    execute(dependencies?: DependencyOverrides<Dependencies>): Promise<BlueprintValue<Output>>;
+}) & UseCaseStatics<Input, Output, Dependencies, Context>;
+/**
+ * Declares an operation. With `steps` the class is concrete: its `execute`
+ * interprets them. Without, it is abstract: extend it and implement an async
+ * execute method.
+ */
+export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseStepsSettings<Input, Output, Dependencies, Context>): StepsUseCaseConstructor<Input, Output, Dependencies, Context>;
+export declare function useCaseOf<Input extends IBlueprintCollection, Output extends IBlueprintCollection, const Dependencies extends UseCaseCollection = Record<never, never>, Context extends IBlueprintCollection | undefined = undefined>(settings: UseCaseSettings<Input, Output, Dependencies, Context>): UseCaseConstructor<Input, Output, Dependencies, Context>;
 export declare function isUseCaseClass(value: unknown): value is AnyUseCaseClass;
 export declare function isUseCase(value: unknown): value is AbstractUseCase<IBlueprintCollection, IBlueprintCollection, UseCaseCollection>;
 export {};

package/dist/experimental.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@afora/core/experimental`: features that may change in any release. Not
+ * covered by the compatibility policy in `VERSIONING.md`.
+ */
+export { sliceOf, sliceValue } from "./core/blueprint/slice.js";
+export type { SlicedBlueprint, SlicedValue, SliceMask, ValueMask, } from "./core/blueprint/types/slice.interface.js";

package/dist/experimental.js

@@ -0,0 +1,123 @@
+import {
+  isBlueprint2,
+  isRecordClass2,
+  recordFieldOf2,
+  listOf2,
+  isBlueprintList2,
+  AbstractRecord2,
+  declareRecord,
+  UndeclaredBlueprintProperty2,
+  optionalOf2,
+  blueprintFromProperties
+} from "./index-hn82hm31.js";
+
+// src/core/blueprint/slice.ts
+function propertiesOfField(field) {
+  if (field === undefined)
+    return;
+  if (isBlueprintList2(field))
+    return propertiesOfField(field.item);
+  const record = recordFieldOf2(field);
+  if (record)
+    return record.record.blueprint.properties;
+  return isBlueprint2(field) ? field.properties : undefined;
+}
+function maskOf(selector, against) {
+  if (isRecordClass2(selector))
+    return maskOf(selector.blueprint, against);
+  if (isBlueprint2(selector)) {
+    return Object.fromEntries(Object.entries(selector.properties).map(([key, field]) => [key, fieldMaskOf(field, against?.[key])]));
+  }
+  return selector;
+}
+function fieldMaskOf(field, other) {
+  if (isBlueprintList2(field)) {
+    return fieldMaskOf(field.item, isBlueprintList2(other) ? other.item : other);
+  }
+  const record = recordFieldOf2(field);
+  if (record) {
+    if (record.record === recordFieldOf2(other)?.record)
+      return true;
+    return maskOf(record.record, propertiesOfField(other));
+  }
+  if (isBlueprint2(field)) {
+    return field === other ? true : maskOf(field, propertiesOfField(other));
+  }
+  return true;
+}
+function sliceCollection(properties, mask, path) {
+  const sliced = {};
+  for (const [key, selected] of Object.entries(mask)) {
+    if (!selected)
+      continue;
+    if (!Object.hasOwn(properties, key)) {
+      throw new UndeclaredBlueprintProperty2({
+        source: "blueprint",
+        details: { key: path + key }
+      });
+    }
+    sliced[key] = sliceField(properties[key], selected, path + key);
+  }
+  return sliced;
+}
+function slicedRecordOf(Original, mask, path) {
+  const source = Original.blueprint;
+  const blueprint = blueprintFromProperties(source.plugins, sliceCollection(source.properties, mask, `${path}.`));
+  const kept = (keys) => keys.filter((key) => Object.hasOwn(blueprint.properties, key));
+  const { sensitive, unique, change } = Original.options;
+  const Sliced = declareRecord(AbstractRecord2, blueprint, {
+    sensitive: kept(sensitive),
+    unique: kept(unique),
+    change: kept(change)
+  }, Original.name);
+  Object.defineProperty(Sliced, Symbol.hasInstance, {
+    value(value) {
+      return Function.prototype[Symbol.hasInstance].call(this, value) || value instanceof Original;
+    }
+  });
+  return Sliced;
+}
+function sliceField(field, selected, path) {
+  if (selected === true)
+    return field;
+  if (isBlueprintList2(field)) {
+    const list = listOf2(sliceField(field.item, selected, path), {
+      minItems: field.minItems,
+      maxItems: field.maxItems
+    });
+    return field.optional ? optionalOf2(list) : list;
+  }
+  const record = recordFieldOf2(field);
+  if (record) {
+    const sliced = slicedRecordOf(record.record, selected, path);
+    return record.optional ? optionalOf2(sliced) : sliced;
+  }
+  if (isBlueprint2(field)) {
+    const sliced = blueprintFromProperties(field.plugins, sliceCollection(field.properties, selected, `${path}.`));
+    return field.optional ? optionalOf2(sliced) : sliced;
+  }
+  throw new UndeclaredBlueprintProperty2({
+    source: "blueprint",
+    details: { key: `${path}.${Object.keys(selected)[0] ?? ""}` }
+  });
+}
+var sliceOf = (blueprint, selector) => blueprintFromProperties(blueprint.plugins, sliceCollection(blueprint.properties, maskOf(selector, blueprint.properties), ""));
+var sliceValue = (value, selector) => pick(value, maskOf(selector));
+function pick(value, mask) {
+  if (Array.isArray(value))
+    return value.map((item) => pick(item, mask));
+  if (typeof value !== "object" || value === null)
+    return value;
+  const source = isRecordClass2(value.constructor) ? value.toJSON() : value;
+  const picked = {};
+  for (const [key, selected] of Object.entries(mask)) {
+    if (!selected || !Object.hasOwn(source, key))
+      continue;
+    picked[key] = selected === true ? source[key] : pick(source[key], selected);
+  }
+  return picked;
+}
+export {
+  sliceOf,
+  sliceValue
+};