@afora/core 0.0.3 → 0.0.4

package/dist/core/application/start.d.ts

@@ -1,6 +1,8 @@
 import { type AnyEnvironment, type EnvironmentDependencies, type MergedEnvironment } from "../environment/environment.js";
+import type { LogSettings } from "../logger/logger.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
 import { Kind } from "../symbols/kind.js";
+import type { ApplicationContext } from "./types/application.interface.js";
 /**
  * A provider an application creates when it starts, from the variables of
  * its environments: what `providerFrom` makes.
@@ -10,6 +12,8 @@ export interface ProviderFactory<Environment extends EnvironmentDependencies = E
     /** The environments whose variables `create` gets, as a list. */
     readonly environments: readonly AnyEnvironment[];
     readonly create: (env: MergedEnvironment<Environment>) => IRepositoryProvider | Promise<IRepositoryProvider>;
+    /** Whether `create` takes the context of the application instead of variables. */
+    readonly withContext: boolean;
 }
 /**
  * A provider made on `app.start()`: `create` gets the variables of
@@ -18,6 +22,26 @@ export interface ProviderFactory<Environment extends EnvironmentDependencies = E
  * `providerFrom(Database, (env) => drizzleProvider({ db: connect(env.DATABASE_URL), tables }))`.
  */
 export declare function providerFrom<const Environment extends EnvironmentDependencies>(environmentDependencies: Environment, create: (env: MergedEnvironment<Environment>) => IRepositoryProvider | Promise<IRepositoryProvider>): ProviderFactory<Environment>;
+/**
+ * A provider made on `app.start()` from the context of the application:
+ * `ctx.env(Database)` gives the variables of a registered environment and
+ * `ctx.logger` its logger, e.g.
+ * `providerFrom((ctx) => drizzleProvider({ db: connect(ctx.env(Database).DATABASE_URL), tables }))`.
+ */
+export declare function providerFrom(create: (context: ApplicationContext) => IRepositoryProvider | Promise<IRepositoryProvider>): ProviderFactory<readonly []>;
+/** A `log` an application makes on `app.start()`: what `logFrom` makes. */
+export interface LogFactory {
+    readonly [Kind]: "log-factory";
+    readonly create: (context: ApplicationContext) => LogSettings | Promise<LogSettings>;
+}
+/**
+ * A `log` made on `app.start()` from the context of the application, before
+ * its provider, e.g. `logFrom((ctx) => ({ level: ctx.env(Logging).LOG_LEVEL,
+ * providers: [jsonLogProvider()] }))`. Until then the application logs nothing.
+ */
+export declare function logFrom(create: (context: ApplicationContext) => LogSettings | Promise<LogSettings>): LogFactory;
+/** Whether `value` was made by `logFrom`. */
+export declare function isLogFactory(value: unknown): value is LogFactory;
 /** Whether `value` was made by `providerFrom`. */
 export declare function isProviderFactory(value: unknown): value is ProviderFactory;
 /**
@@ -36,7 +60,7 @@ export declare function deferredEnvironments(provider: unknown): readonly AnyEnv
  * environments (already validated by the caller); later calls give the same.
  * @internal
  */
-export declare function startDeferred(provider: IRepositoryProvider): Promise<IRepositoryProvider> | undefined;
+export declare function startDeferred(provider: IRepositoryProvider, context: ApplicationContext): Promise<IRepositoryProvider> | undefined;
 /**
  * Closes the provider made on start and forgets it, so that calls throw
  * `ApplicationNotStarted` again; a provider that is not deferred is closed.

package/dist/core/application/types/application.interface.d.ts

@@ -1,6 +1,7 @@
 import type { AnyCommand } from "../../command/types/command.interface.js";
 import type { AnyEnvironment, EnvironmentValue } from "../../environment/environment.js";
 import type { ExceptionLayers } from "../../exception/enums/exception-layers.js";
+import type { ILogger, LogLevel, LogSettings } from "../../logger/logger.js";
 import type { AnyOutput, StageDescription } from "../../output/types/output.interface.js";
 import type { RecordPluginDescriptor } from "../../record/types/plugin.interface.js";
 import type { ProviderDescription } from "../../repository/types/query.interface.js";
@@ -8,7 +9,7 @@ import type { AnyRepository, IRepositoryProvider } from "../../repository/types/
 import type { Kind } from "../../symbols/kind.js";
 import type { UseCaseStepDescription } from "../../use-case/steps/types/steps.interface.js";
 import type { AnyExceptionClass, AnyUseCaseClass } from "../../use-case/use-case.js";
-import type { ProviderFactory } from "../start.js";
+import type { LogFactory, ProviderFactory } from "../start.js";
 type Named<Value> = Readonly<Record<string, Value>>;
 /** The declarations of an application, by name, one collection for each kind. */
 export interface ApplicationCollections {
@@ -55,6 +56,28 @@ export interface ApplicationSettings<Name extends string, Extended extends reado
      * environments, and calls before that throw `ApplicationNotStarted`.
      */
     readonly provider?: IRepositoryProvider | ProviderFactory;
+    /**
+     * How it logs: the providers its lines go to and the lowest level kept.
+     * Use cases, commands and repository calls of the application are logged
+     * through it, and a use case gets it as its `Logger` dependency. Without
+     * it, the one of the last extended application that has one; none by default.
+     */
+    readonly log?: LogSettings | LogFactory;
+}
+/**
+ * What an application gives the factories it runs on start (`providerFrom`,
+ * `logFrom`) and your code (`app.context`).
+ */
+export interface ApplicationContext {
+    /** The name of the application. */
+    readonly name: string;
+    /**
+     * The variables of an environment registered in the application, typed by
+     * its blueprint; one that is not registered throws `UnregisteredApplicationReference`.
+     */
+    env<Environment extends AnyEnvironment>(environment: Environment): EnvironmentValue<Environment>;
+    /** Its logger; a `log` of `logFrom` writes nothing before `start()`. */
+    readonly logger: ILogger;
 }
 type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
 /**
@@ -72,6 +95,10 @@ export interface IApplication<Name extends string, Collections extends Applicati
     readonly extends: readonly AnyApplication[];
     /** The default provider of its repositories, if any. */
     readonly provider: IRepositoryProvider | undefined;
+    /** Logs through the providers of its `log`; writes nothing without one. */
+    readonly logger: ILogger;
+    /** Its context: its name, the variables of its environments and its logger. */
+    readonly context: ApplicationContext;
     readonly properties: Collections["properties"];
     readonly blueprints: Collections["blueprints"];
     readonly records: Collections["records"];
@@ -223,7 +250,8 @@ export interface RecordDescription {
 }
 /** What a use case depends on, by the name it has in the application. */
 export interface UseCaseDependencyDescription {
-    readonly kind: "use-case" | "repository" | "environment";
+    /** `logger` is the core's `Logger`, whose `ref` is always `"Logger"`. */
+    readonly kind: "use-case" | "repository" | "environment" | "logger";
     readonly ref: string;
 }
 /** A use case: its metadata, fields and what it depends on. */
@@ -306,6 +334,17 @@ export interface ExceptionDescription {
     readonly layer: ExceptionLayers;
     readonly message?: string;
 }
+/** How `describe` gives the `log` of an application. */
+export interface LogDescription {
+    readonly level: LogLevel;
+    /** The name of each provider made by `logProviderOf` with one; `opaque` otherwise (and for a `logFrom` before start). */
+    readonly providers: readonly ({
+        readonly kind: "log-provider";
+        readonly name: string;
+    } | {
+        readonly kind: "opaque";
+    })[];
+}
 /** The graph `describe` gives: every declaration by name, with its origin in `from`. */
 export interface ApplicationDescription {
     readonly name: string;
@@ -313,6 +352,10 @@ export interface ApplicationDescription {
     readonly extends: readonly string[];
     /** The provider of the application (or of the last extended one), present only when configured. */
     readonly provider?: ProviderDescription;
+    /** Its `log` (or the one of the last extended application), present only when configured. */
+    readonly log?: LogDescription | {
+        readonly kind: "opaque";
+    };
     readonly properties: Readonly<Record<string, PropertyDescription & {
         readonly from: string;
     }>>;

package/dist/core/command/types/command.interface.d.ts

@@ -1,6 +1,7 @@
 import type { BlueprintInput, IBlueprint, IBlueprintCollection } from "../../blueprint/types/blueprint.interface.js";
 import type { EntityEvent } from "../../entity/event.js";
 import type { AnyEnvironment, EnvironmentDependencies, MergedEnvironment } from "../../environment/environment.js";
+import type { ILogger } from "../../logger/logger.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { AnyUseCaseClass, UseCaseInput, UseCaseOptions, UseCaseResponse } from "../../use-case/use-case.js";
 /** The use cases of a command, by operation name. */
@@ -13,6 +14,11 @@ export interface CommandEventInfo {
     readonly context: unknown;
     /** The variables of the command's environments, with the `env` of the call over them. */
     readonly env: Readonly<Record<string, unknown>>;
+    /**
+     * The logger of the application that bound the command, else the started
+     * application's; a logger that writes nothing without either.
+     */
+    readonly logger: ILogger;
 }
 /** Handles all the events of a call, once it succeeded. */
 export type CommandEventHandler = (events: readonly EntityEvent[], info: CommandEventInfo) => void | Promise<void>;

package/dist/core/entity/event.d.ts

@@ -1,3 +1,4 @@
+import { type ILogger } from "../logger/logger.js";
 /** A class made by `entityOf`, including subclasses. */
 export declare const EntityClassBrand: unique symbol;
 export type AnyEntityClass = (abstract new (value: never) => object) & {
@@ -9,11 +10,20 @@ export interface EventDefinition {
     readonly name: string;
     readonly [EventBrand]: true;
 }
+/** What the handler of an event gets next to the entity. */
+export interface EventHandlerContext {
+    /**
+     * The logger of the application whose command raised the event; else the
+     * started application's; a logger that writes nothing without either.
+     */
+    readonly logger: ILogger;
+}
 /** One queued occurrence, referencing the original entity rather than a snapshot. */
 export interface EntityEvent<Entity = object> {
     readonly name: string;
     readonly entity: Entity;
-    handle(): Promise<void>;
+    /** Runs the handler; `logger` replaces the one it would get. */
+    handle(context?: Partial<EventHandlerContext>): Promise<void>;
 }
 export type EntityEventReference = EventDefinition | readonly EventDefinition[] | (() => EventDefinition | readonly EventDefinition[]);
 export interface EntityEvents {
@@ -23,7 +33,7 @@ export interface EntityEvents {
 }
 export declare const EntityEventSettings: unique symbol;
 /** Defines an event without executing its handler. */
-export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler: (entity: InstanceType<Class>) => Promise<void>): EventDefinition;
+export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler: (entity: InstanceType<Class>, context: EventHandlerContext) => Promise<void>): EventDefinition;
 export declare function enqueueEvent(entity: object, event: EventDefinition): void;
 export declare function pullEntityEvents<Entity extends object>(entity: Entity): EntityEvent<Entity>[];
 export declare function enqueueLifecycle(entity: object, cycle: keyof EntityEvents): void;

package/dist/core/logger/exceptions.d.ts

@@ -0,0 +1,4 @@
+/** `logProviderOf`, `logFrom` or the `log` of an application got something it cannot use. */
+export declare const InvalidLogDeclaration: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

package/dist/core/logger/logger.d.ts

@@ -0,0 +1,106 @@
+import { Kind } from "../symbols/kind.js";
+/** What a log line carries besides its event. */
+export type LogFields = Readonly<Record<string, unknown>>;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare const LogLevels: readonly LogLevel[];
+/** What logs: an application, a use case through its `Logger` dependency, your code. */
+export interface ILogger {
+    debug(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    error(event: string, fields?: LogFields): void;
+}
+/** One line, as a log provider gets it. */
+export interface LogEntry {
+    /** ISO 8601. */
+    readonly at: string;
+    readonly level: LogLevel;
+    readonly event: string;
+    readonly fields: LogFields;
+    /** The name of the application that logged it. */
+    readonly application: string;
+}
+/**
+ * Where lines go: the console, JSON on stdout, a log service, memory. An
+ * application writes each line to every provider of its `log`.
+ */
+export interface ILogProvider {
+    write(entry: LogEntry): void | Promise<void>;
+    /** Called on `app.stop()`, to send what is still buffered. */
+    flush?(): Promise<void>;
+}
+/** The `log` of an application. */
+export interface LogSettings {
+    /** Lines below it are dropped. `"info"` by default. */
+    readonly level?: LogLevel;
+    readonly providers: readonly ILogProvider[];
+}
+/** What `logProviderOf` takes. */
+export interface LogProviderSettings<Provider extends ILogProvider> {
+    /** Shown by `app.describe()`; anonymous providers are opaque. */
+    readonly name?: string;
+    readonly write: Provider["write"];
+    readonly flush?: Provider["flush"];
+}
+/** A log provider, checked, and named for `describe()` when `name` is given. */
+export declare function logProviderOf(settings: LogProviderSettings<ILogProvider>): ILogProvider;
+/** The name `logProviderOf` gave a provider, if any. */
+export declare function logProviderNameOf(provider: ILogProvider): string | undefined;
+/** A readable line on the console, by level: for local development. */
+export declare function consoleLogProvider(): ILogProvider;
+/** One JSON object per line on stdout: for Lambda, containers, CloudWatch. */
+export declare function jsonLogProvider(): ILogProvider;
+/** A provider that keeps the lines, for tests. */
+export interface MemoryLogProvider extends ILogProvider {
+    readonly entries: readonly LogEntry[];
+    clear(): void;
+}
+/** Keeps every line in `entries`, for tests. */
+export declare function memoryLogProvider(): MemoryLogProvider;
+/** Throws unless `settings` is a usable `log`; gives it with the default level. */
+export declare function checkLogSettings(settings: unknown): Required<LogSettings>;
+/** A logger that writes nothing. */
+export declare const silentLogger: ILogger;
+/**
+ * The logger of an application: drops what is below `level`, writes the rest
+ * to every provider, and never lets a provider break the call or the others.
+ * `settings` can be set later (a `log` made on start) and unset on stop.
+ */
+export declare function applicationLogger(application: string): {
+    logger: ILogger;
+    readonly settings: Required<LogSettings> | undefined;
+    set(settings: Required<LogSettings> | undefined): void;
+    flush(): Promise<void>;
+};
+/**
+ * The `Logger` dependency of a use case: `dependencies: { logger: Logger }`
+ * gives an `ILogger`, the one of the application it runs in.
+ */
+export interface LoggerDeclaration {
+    readonly [Kind]: "logger";
+}
+export declare const Logger: LoggerDeclaration;
+export declare function isLoggerDeclaration(value: unknown): value is LoggerDeclaration;
+/** Whether `value` can stand for a logger (an override in `execute`). */
+export declare function isLogger(value: unknown): value is ILogger;
+/**
+ * Carries the logger of an application, when it has a `log`: on the
+ * application and on the use case classes it binds.
+ */
+export declare const ApplicationLoggerKey: unique symbol;
+/**
+ * The logger a call writes to: the one its scope carries, else the one of
+ * the application its class was bound by, else the started application's.
+ */
+export declare function resolveLogger(scoped: ILogger | undefined, owner: unknown): ILogger | undefined;
+/** Milliseconds, for timing; `Date.now` where there is no `performance`. */
+export declare function clock(): number;
+export declare function elapsed(since: number): number;
+/**
+ * Logs a failure once: the same exception passes through every use case and
+ * command up the call, each wrapping it. `warn` for a declared exception,
+ * `error` for an unexpected one, with its trace.
+ */
+export declare function logFailure(logger: ILogger | undefined, event: string, fields: LogFields, error: unknown): void;
+/** Writes one line; a logger that throws never breaks the call it logs. */
+export declare function writeLog(logger: ILogger | undefined, level: LogLevel, event: string, fields: LogFields): void;

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

@@ -1,3 +1,4 @@
+import type { ILogger } from "../logger/logger.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
 /**
  * What a call carries to its repositories, internal: the providers that
@@ -11,6 +12,8 @@ export interface ExecutionScope {
      * loads, by environment: a use case that declares it gets these.
      */
     readonly environments?: ReadonlyMap<object, Readonly<Record<string, unknown>>>;
+    /** The logger of the application running the call, given by its command. */
+    readonly logger?: ILogger;
 }
 /**
  * Key of the constructor options (and of the repository view) that carries

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

@@ -2,6 +2,7 @@ import type { AnyBlueprint, BlueprintInput, BlueprintValue, IBlueprint, IBluepri
 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";
@@ -26,9 +27,9 @@ export interface AnyUseCaseClass {
 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;
@@ -55,9 +56,9 @@ export type UseCaseOptions<Context extends IBlueprintCollection | undefined = un
 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]>;
 };