@afora/core 0.0.5 → 0.0.7

package/README.md

@@ -11,6 +11,7 @@ afora is not a general-purpose validator. It is for code that models a domain, a
 - **Exceptions that know their layer.** Each error carries a layer (`Property`, `Record`, `UseCase`, `Output`...) and a `trace` that grows as it goes up.
 - **Standard Schema V1 on every field.** Properties, blueprints, lists and record classes work as is in Hono, tRPC and TanStack Form, and `safeParse` never throws for an invalid value.
 - **Commands and outputs.** `commandOf` groups use cases behind one execution boundary (context, transactions, event policies); `outputOf` turns commands into operations and pipes them to a sink: an HTTP API with `@afora/hono`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
+- **Standard use cases.** `commandOf({ useCases: (ctx) => ({ create: ctx.create(Posts), publish: ctx.publish(Posts) }) })` picks ready-made use cases that follow the repository and its entity: the actions it declares, its record plugins and the properties of its keys ([docs](docs/std-use-cases.md)).
 - **The whole application in JSON.** An `afora.json` generates the code (`@afora/codegen`), use cases included, as data (steps), and `extractSpec(app)` gives back the `afora.json` of an application written by hand.
 - **Repositories on any store.** A provider contract with typed queries, soft deletion and transactions, a runner-agnostic kit to test one (`@afora/core/testing`), in memory by default and on Drizzle ORM with `@afora/drizzle`.
 
@@ -304,7 +305,7 @@ Every field (a property, blueprint, list or record class) implements Standard Sc
 
 ## Example
 
-`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, use cases written as steps, a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`), a password hashing function and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
+`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, every use case a [standard one](docs/std-use-cases.md), a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`, and named `database` in the `providers` of the spec) and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
 
 ## Performance
 
@@ -335,6 +336,8 @@ Where the others win: Zod and Valibot are faster, have far larger ecosystems and
 
 ## Contributing
 
+Issues open from a template: bug report, feature request, or feedback from building on afora. Questions go to [Discussions](https://github.com/afora-framework/core/discussions). Pull requests follow [the PR template](.github/PULL_REQUEST_TEMPLATE.md).
+
 Commits follow [Conventional Commits](https://www.conventionalcommits.org) (`feat(repository): …`, `fix: …`), checked by commitlint in a Husky `commit-msg` hook; the `pre-commit` hook runs Biome and Knip. CI runs lint, Knip, type checks, unit and interop tests, the build and the Node smoke test on every push and pull request. Pushing a `v*` tag that matches `package.json` publishes to npm with provenance.
 
 Scripts:

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

@@ -1,3 +1,4 @@
+import type { AnyBlueprint, BlueprintInput, IBlueprint } from "../../blueprint/types/blueprint.interface.js";
 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";
@@ -8,10 +9,32 @@ import type { ProviderDescription } from "../../repository/types/query.interface
 import type { AnyRepository, IRepositoryProvider } from "../../repository/types/repository.interface.js";
 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 { AnyExceptionClass, AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case/use-case.js";
 import type { ProviderSlot, ProviderStorage } from "../providers.js";
 import type { LogFactory, ProviderFactory } from "../start.js";
 type Named<Value> = Readonly<Record<string, Value>>;
+/**
+ * The options of `app.run`: the `context` of the use case, required when it
+ * declares one, and `dependencies`, what its `execute` takes to replace them.
+ */
+export type ApplicationRunOptions<UseCase extends AnyUseCaseClass> = (UseCase["context"] extends IBlueprint<infer Properties> ? {
+    readonly context: BlueprintInput<Properties>;
+} : {
+    readonly context?: undefined;
+}) & {
+    readonly dependencies?: Parameters<InstanceType<UseCase>["execute"]>[0];
+};
+/**
+ * What `app.run` takes after the use case: its input, optional when no key
+ * of it is required, and the options, required when it declares a context.
+ */
+export type ApplicationRunArgs<UseCase extends AnyUseCaseClass> = UseCase["context"] extends AnyBlueprint ? [input: UseCaseInput<UseCase>, options: ApplicationRunOptions<UseCase>] : {} extends UseCaseInput<UseCase> ? [
+    input?: UseCaseInput<UseCase>,
+    options?: ApplicationRunOptions<UseCase>
+] : [
+    input: UseCaseInput<UseCase>,
+    options?: ApplicationRunOptions<UseCase>
+];
 /** The declarations of an application, by name, one collection for each kind. */
 export interface ApplicationCollections {
     readonly properties: Named<unknown>;
@@ -115,25 +138,29 @@ export interface IApplication<Name extends string, Collections extends Applicati
     readonly entities: Collections["entities"];
     readonly environments: Collections["environments"];
     /**
-     * Its repositories, inherited ones included. With a `provider` they are
-     * bound to it: they share the declaration of the original but read and
-     * write through that provider (unless they declared their own).
+     * Its repositories, inherited ones included. With a `provider` (or
+     * `providers`) they are bound to it: they share the declaration of the
+     * original but read and write through that provider (unless they declared
+     * their own).
      */
     readonly repositories: Collections["repositories"];
     /**
-     * Its use cases. With a `provider` they are subclasses whose repositories
-     * are the bound ones, through child use cases too; the same subclass every
-     * time. Without one they are the declared classes.
+     * Its use cases. With a `provider`, `providers` or `log` they are
+     * subclasses whose repositories are the bound ones, through child use
+     * cases too; the same subclass every time. Without any of them they are
+     * the declared classes.
      */
     readonly useCases: Collections["useCases"];
     /**
-     * Its commands. With a `provider` they are rebuilt over the bound use
-     * cases (same settings), memoized; without one, the declared commands.
+     * Its commands. With a `provider`, `providers` or `log` they are rebuilt
+     * over the bound use cases (same settings), memoized; without any of them,
+     * the declared commands.
      */
     readonly commands: Collections["commands"];
     /**
-     * Its outputs. With a `provider` they are rebuilt over the bound commands
-     * (same name, statuses and stages), memoized; without one, the declared outputs.
+     * Its outputs. With a `provider`, `providers` or `log` they are rebuilt
+     * over the bound commands (same name, statuses and stages), memoized;
+     * without any of them, the declared outputs.
      */
     readonly outputs: Collections["outputs"];
     /** Its exceptions. */
@@ -142,6 +169,13 @@ export interface IApplication<Name extends string, Collections extends Applicati
     repository<Repository extends AnyRepository>(repository: Repository): Repository;
     /** The bound version of a use case registered in the application. */
     useCase<UseCase extends AnyUseCaseClass>(useCase: UseCase): UseCase;
+    /**
+     * Runs a use case registered in the application over its bound
+     * repositories: `new (app.useCase(UseCase))(input, { context }).execute(dependencies)`.
+     * It rejects with what the constructor or `execute` throw. The events the
+     * use case collected are not handled; a command is what dispatches them.
+     */
+    run<UseCase extends AnyUseCaseClass>(useCase: UseCase, ...args: ApplicationRunArgs<UseCase>): Promise<UseCaseResponse<UseCase>>;
     /** The bound version of a command registered in the application. */
     command<Command extends AnyCommand>(command: Command): Command;
     /** The bound version of an output registered in the application. */
@@ -306,6 +340,17 @@ export interface UseCaseDescription {
     } | {
         readonly kind: "opaque";
     };
+    /**
+     * The use case plugin that made it, the registered repository it was made
+     * for and the options given, with classes by name as in the steps; absent
+     * for a use case declared by hand.
+     */
+    readonly generic?: {
+        readonly name: string;
+        readonly version: string;
+        readonly repository: string;
+        readonly options: Readonly<Record<string, unknown>>;
+    };
 }
 /** A command: its metadata, context, operations and policies. */
 export interface CommandDescription {

package/dist/core/blueprint/types/slice.interface.d.ts

@@ -1,4 +1,4 @@
-import type { RecordUniqueKeys } from "../../record/types/plugin.interface.js";
+import type { RecordSensitiveKeys, RecordUniqueKeys } from "../../record/types/plugin.interface.js";
 import type { RecordConstructor } from "../../record/types/record.interface.js";
 import type { Meta } from "../../symbols/meta.js";
 import type { AnyBlueprint, AnyBlueprintList, AnyOptionalRecord, AnyRecordClass, BlueprintData, BlueprintField, IBlueprint, IBlueprintCollection, IBlueprintList, OptionalRecord } from "./blueprint.interface.js";
@@ -37,13 +37,16 @@ type SlicedRecord<Original extends AnyRecordClass, Mask> = SlicedProperties<Orig
     readonly [Meta]: {
         readonly blueprint: Original["blueprint"];
     };
-}> : never;
+}, KeptSensitive<Original, keyof Properties>> : never;
 type KeptChange<Instance, Keys> = Instance extends {
     readonly change: infer Change;
 } ? Extract<keyof Change, Keys & string> : never;
 type KeptUnique<Original, Keys> = Original extends {
     readonly [RecordUniqueKeys]?: infer Unique;
 } ? Extract<Unique, Keys & string> : never;
+type KeptSensitive<Original, Keys> = Original extends {
+    readonly [RecordSensitiveKeys]?: infer Sensitive;
+} ? Extract<Sensitive, Keys & string> : never;
 /** The properties of `Blueprint`, read lazily so generic uses stay shallow. */
 export type PropertiesOf<Blueprint> = Blueprint extends IBlueprint<infer Properties, boolean> ? Properties : never;
 /** The blueprint of `Properties` that keeps only the keys of `Mask`. */

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

@@ -1,7 +1,6 @@
-import type { IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
-import { type EnvironmentDependencies } from "../environment/environment.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
-import type { AnyCommand, CommandOf, CommandSettings, CommandUseCases } from "./types/command.interface.js";
+import type { IUseCaseCatalog, UseCasePluginContext } from "../use-case/types/plugin.interface.js";
+import type { AnyCommand, CommandBuilder } from "./types/command.interface.js";
 /**
  * Checks now that the repositories of `command` share a provider that has
  * `transaction`, as its first call would; an application calls it when it
@@ -15,11 +14,19 @@ export declare function verifyCommand(command: object): void;
  * @internal
  */
 export declare function commandTransactionProvider(command: object): IRepositoryProvider | undefined;
+/**
+ * A `commandOf` whose `useCases` may be a function of the use case plugins
+ * of `catalogs`, by name, a later catalog winning a name:
+ * `useCases: (ctx) => ({ create: ctx.create(Posts), custom: MyUseCase })`.
+ * Throws `InvalidCommandDeclaration` for what is not a catalog made by
+ * `useCaseCatalogOf`.
+ */
+export declare function commandBuilderOf<const Catalogs extends readonly IUseCaseCatalog[] = []>(...catalogs: Catalogs): CommandBuilder<UseCasePluginContext<Catalogs>>;
 /**
  * Groups use cases under operation names and is the boundary of a call: the
  * context is validated once, a transaction can wrap the use case, and the
  * events it raised are handled by a policy once it succeeded.
  */
-export declare function commandOf<const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandSettings<UseCases, Context, Environment>): CommandOf<UseCases, Context, Environment>;
+export declare const commandOf: CommandBuilder<Record<never, never>>;
 /** Whether `value` is a command made by `commandOf`. */
 export declare function isCommand(value: unknown): value is AnyCommand;

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

@@ -48,6 +48,25 @@ export interface CommandSettings<UseCases extends CommandUseCases, Context exten
     readonly events?: CommandEvents;
     readonly onEventError?: CommandEventErrorHandler;
 }
+/**
+ * The `useCases` of a command made by a builder: the object, or a function
+ * of the use case plugins of its catalogs that gives it.
+ */
+export type CommandUseCasesOption<UseCases extends CommandUseCases, Generics> = UseCases | ((ctx: Generics) => UseCases);
+/** `CommandSettings` with `useCases` as a builder takes it. */
+export interface CommandBuilderSettings<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined, Environment extends EnvironmentDependencies | undefined, Generics> extends Omit<CommandSettings<UseCases, Context, Environment>, "useCases"> {
+    /**
+     * The use cases, by operation name; or a function that gets the use
+     * case plugins of the builder's catalogs, each called with a repository,
+     * and gives them: `(ctx) => ({ create: ctx.create(Posts) })`.
+     */
+    readonly useCases: CommandUseCasesOption<UseCases, Generics>;
+}
+/**
+ * What `commandBuilderOf` gives: `commandOf`, with the use case plugins
+ * `Generics` to pick from.
+ */
+export type CommandBuilder<Generics> = <const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandBuilderSettings<UseCases, Context, Environment, Generics>) => CommandOf<UseCases, Context, Environment>;
 /** The names of the operations of a command. */
 export type CommandOperation<Command extends {
     readonly useCases: object;

package/dist/core/entity/abstract-entity.d.ts

@@ -17,7 +17,7 @@ export declare const EntityUniqueKeys: unique symbol;
  * and never changed after, an `updatedAt` set by each change, and a
  * `deletedAt` set by `destroy`, after which it no longer changes.
  */
-export declare abstract class AbstractEntity<Properties extends IBlueprintCollection> extends AbstractRecord<Properties> {
+export declare abstract class AbstractEntity<Properties extends IBlueprintCollection, Sensitive extends string = never> extends AbstractRecord<Properties, Sensitive> {
     constructor(value: BlueprintInput<Properties>);
     /** Queues an event for this entity without running its handler. */
     protected emit(event: EventDefinition): void;

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

@@ -1,6 +1,6 @@
 import type { BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection, JoinedProperties } from "../../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "../../parse/types/parse.interface.js";
-import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginUniqueKey, WithPluginProperties } from "../../record/types/plugin.interface.js";
+import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginSensitiveKey, PluginUniqueKey, WithPluginProperties } from "../../record/types/plugin.interface.js";
 import type { MarkedUniqueKey, RecordChanges, RecordKey, RecordOptions, RecordSettings } from "../../record/types/record.interface.js";
 import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
@@ -45,32 +45,38 @@ export type EntityProperties<Identity extends IEntityIdentity, Properties extend
  */
 export type EntityInput<Identity extends IEntityIdentity, Properties extends IBlueprintCollection> = BlueprintInput<Properties> & Partial<BlueprintInput<Identity>>;
 /** What `entityOf` takes, after the blueprint, to describe its keys. */
-export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown> = RecordOptions<Properties, Change, Unique, Plugins, Context> & EntityEvents;
+export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[]> = RecordOptions<Properties, Change, Unique, Plugins, Context, Sensitive> & EntityEvents;
 /**
  * The unique keys of an entity: `id`, those listed in `options.unique`, and
  * those holding a property declared `unique`, as `Slug`.
  */
 export type EntityUniqueKey<Identity extends IEntityIdentity, Properties extends IBlueprintCollection, Unique extends readonly string[]> = "id" | Unique[number] | MarkedUniqueKey<EntityProperties<Identity, Properties>>;
 /** The entities of the class `entityOf` returns, with what its plugins add, `Members`. */
-export type DeclaredEntityInstance<Identity extends IEntityIdentity, Properties extends IBlueprintCollection, Change extends readonly string[], Members = unknown> = AbstractEntity<EntityProperties<Identity, Properties>> & Readonly<BlueprintValue<EntityProperties<Identity, Properties>>> & RecordChanges<Properties, Change> & Members;
+export type DeclaredEntityInstance<Identity extends IEntityIdentity, Properties extends IBlueprintCollection, Change extends readonly string[], Members = unknown, Sensitive extends string = never> = AbstractEntity<EntityProperties<Identity, Properties>, Sensitive> & Readonly<BlueprintValue<EntityProperties<Identity, Properties>>> & RecordChanges<Properties, Change> & Members;
 /** What `entityOf` returns: a record class with identity. */
-export type EntityConstructor<Identity extends IEntityIdentity, Properties extends IBlueprintCollection, Change extends readonly string[], Unique extends readonly string[] = [], Members = unknown> = {
+export type EntityConstructor<Identity extends IEntityIdentity, Properties extends IBlueprintCollection, Change extends readonly string[], Unique extends readonly string[] = [], Members = unknown, Sensitive extends string = never> = {
     readonly [EntityClassBrand]: true;
     /** The keys no two entities may share, as `options.unique` lists them. */
     readonly [EntityUniqueKeys]: readonly EntityUniqueKey<Identity, Properties, Unique>[];
-    new (value: EntityInput<Identity, Properties>): DeclaredEntityInstance<Identity, Properties, Change, Members>;
+    new (value: EntityInput<Identity, Properties>): DeclaredEntityInstance<Identity, Properties, Change, Members, Sensitive>;
     /**
      * The Standard Schema of the class: `validate` gives an instance of it, or
      * the issues that reject the value. Typed with the instance of the class
      * `entityOf` returns, not of a subclass.
      */
-    readonly "~standard": StandardSchemaV1.Props<EntityInput<Identity, Properties>, DeclaredEntityInstance<Identity, Properties, Change, Members>>;
+    readonly "~standard": StandardSchemaV1.Props<EntityInput<Identity, Properties>, DeclaredEntityInstance<Identity, Properties, Change, Members, Sensitive>>;
     /**
      * An instance of the class (a subclass included) for `value`, or every
      * issue that rejects it; never throws for an invalid value.
      */
     safeParse<Self extends new (value: never) => object>(this: Self, value: unknown): ParseResult<InstanceType<Self>>;
     readonly [Kind]: "record";
+    /**
+     * The name of the class as declared: the `name` option, which a bundler
+     * does not rename, or the name of the class without one. A subclass may
+     * give its own with `static override readonly recordName = "..."`.
+     */
+    readonly recordName: string;
     readonly blueprint: IBlueprint<EntityProperties<Identity, Properties>>;
     readonly options: RecordSettings<EntityProperties<Identity, Properties>>;
     /** Its plugins, those they require included, each once. */
@@ -80,4 +86,4 @@ export type EntityConstructor<Identity extends IEntityIdentity, Properties exten
  * What `entityBuilderOf` returns: `entityOf`, declaring entities with the
  * identity it was given, whose `options.plugins` picks from `Context`.
  */
-export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context>) => EntityConstructor<Identity, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>>;
+export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive>) => EntityConstructor<Identity, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>, Sensitive[number] | PluginSensitiveKey<Plugins>>;

package/dist/core/exception/exception.d.ts

@@ -31,8 +31,17 @@ export declare class Exception<Details = unknown> extends Error {
     /**
      * Passes the exception to an upper layer: a new exception in `scope`, with
      * this one as its cause, keeping its name and message unless given others.
+     * With the same name and no new `details`, an exception of a class declared
+     * with `exceptionOf` (or of a subclass of one) stays an instance of that
+     * class and keeps its `details`, so `instanceof` holds across layers; the
+     * constructor of the class does not run again.
      */
-    propagate<Next = undefined>({ layer, source, name, message, details, }: ExceptionPropagation<Next>): Exception<Next>;
+    propagate(scope: ExceptionScope & {
+        readonly name?: undefined;
+        readonly message?: string;
+        readonly details?: undefined;
+    }): Exception<Details>;
+    propagate<Next = undefined>(scope: ExceptionPropagation<Next>): Exception<Next>;
     toJSON(): ExceptionFrame<Details> & {
         trace: readonly ExceptionFrame[];
     };

package/dist/core/output/status.d.ts

@@ -2,15 +2,16 @@ import { Exception } from "../exception/exception.js";
 import type { OperationDescriptor, OutputStatuses } from "./types/output.interface.js";
 /**
  * The exception that raised `error` under its name: a use case or a command
- * passes an exception up as a copy with the same name, no details and the
- * original as its cause, so the original is the deepest one with that name.
+ * passes an exception up as a copy with the same name and the original as
+ * its cause, so the original is the deepest one with that name.
  */
 export declare function raisedOf(error: Exception): Exception;
 /**
  * The HTTP-style status of an error, in this order: `statuses` by exception
  * name; 400 for invalid input or context (and any exception whose
  * `details.issues` is a list, except `InvalidCommandEnvironment`, a 500); 404 for a missing entity or operation; 409 for
- * a unique violation; 422 for a class in `operation.errors`; 500 for the
+ * a unique violation or an entity that already exists; 401 for
+ * `UseCaseInvalidCredentials`; 422 for a class in `operation.errors`; 500 for the
  * rest, errors that are not exceptions included. Exceptions match by name,
  * or by class for `operation.errors`.
  */

package/dist/core/property/input.d.ts

@@ -0,0 +1,20 @@
+import type { AnyPropertyConstructor } from "./types/property-collection.type.js";
+/**
+ * The static of a property class whose callers give another form of its
+ * value than the one it stores: a password is given plain and stored as a
+ * hash. Classes extending or refining the property keep it.
+ */
+export declare const PropertyInput: unique symbol;
+/** What a property class holds under `PropertyInput`. */
+export interface IPropertyInput<Value = unknown> {
+    /** The property that validates what a caller gives, of the same value type. */
+    readonly accepts: AnyPropertyConstructor;
+    /** Turns what a caller gave into the value the property stores. */
+    convert(value: Value): Value | Promise<Value>;
+}
+/**
+ * What `field` declares under `PropertyInput`; `undefined` for a property
+ * that takes its value as it stores it, and for a field that is not a
+ * property.
+ */
+export declare function propertyInputOf(field: unknown): IPropertyInput | undefined;

package/dist/core/property/property.d.ts

@@ -6,20 +6,20 @@ import { AbstractDefineProperty } from "./define-property.js";
 import type { AnyPropertyConstructor } from "./types/property-collection.type.js";
 import type { PropertyValue } from "./types/property-constructor.type.js";
 import type { PropertyOptions } from "./types/property-options.interface.js";
-import type { IPropertyType, UniqueMark } from "./types/property-type.interface.js";
+import type { IPropertyType, SensitiveMark, UniqueMark } from "./types/property-type.interface.js";
 type SchemaValueType<SchemaType extends TSchema, Optional extends boolean = false> = Optional extends true ? TOptional<SchemaType> : SchemaType;
 /**
  * What `propertyOf` takes. `SchemaType` is inferred from `schema` alone: the
  * value is `NoInfer`, since inferring through `Static` makes TypeScript
  * measure `Static` itself, which costs about a second on every check.
  */
-type PropertyOfArgs<SchemaType extends TSchema, Optional extends boolean = false, Unique extends boolean = false, Value = Static<SchemaType>> = {
+type PropertyOfArgs<SchemaType extends TSchema, Optional extends boolean = false, Unique extends boolean = false, Sensitive extends boolean = false, Value = Static<SchemaType>> = {
     name: string;
     schema: SchemaType;
     default?: NoInfer<Value>;
     optional?: Optional;
     /** A record masks its value in `toJSON`, at any depth, as `Password`. */
-    sensitive?: boolean;
+    sensitive?: Sensitive;
     /**
      * A record lists a key holding it in `options.unique`, as `Slug`; records
      * do not check it, repositories (or the database) enforce it.
@@ -53,5 +53,5 @@ export interface PropertyClass<SchemaType extends TSchema, Value = Static<Schema
     with<Self extends AnyPropertyConstructor>(this: Self, options: PropertyOptions<SchemaType, Value>): Self;
     demo<Self extends AbstractProperty<any>>(this: new (value: never) => Self): Self;
 }
-export declare function propertyOf<SchemaType extends TSchema, Optional extends boolean = false, const Unique extends boolean = false>({ name, schema, optional, sensitive, unique, default: _default, preHandle: onPreHandle, afterHandle: onAfterHandle, }: PropertyOfArgs<SchemaType, Optional, Unique>): PropertyClass<SchemaValueType<SchemaType, Optional>, Static<SchemaType>> & UniqueMark<Unique>;
+export declare function propertyOf<SchemaType extends TSchema, Optional extends boolean = false, const Unique extends boolean = false, const Sensitive extends boolean = false>({ name, schema, optional, sensitive, unique, default: _default, preHandle: onPreHandle, afterHandle: onAfterHandle, }: PropertyOfArgs<SchemaType, Optional, Unique, Sensitive>): PropertyClass<SchemaValueType<SchemaType, Optional>, Static<SchemaType>> & UniqueMark<Unique> & SensitiveMark<Sensitive>;
 export {};

package/dist/core/property/types/optional-property.type.d.ts

@@ -5,7 +5,7 @@ import type { AbstractProperty } from "../abstract-property.js";
 import type { AnyPropertyConstructor } from "./property-collection.type.js";
 import type { PropertyValue } from "./property-constructor.type.js";
 import type { CallableKey, StoredField } from "./property-options.interface.js";
-import type { IPropertyType, UniqueTypeOf } from "./property-type.interface.js";
+import type { IPropertyType, SensitiveTypeOf, UniqueTypeOf } from "./property-type.interface.js";
 /**
  * `Property` accepting `undefined`: its schema becomes `TOptional`, while its
  * own methods and statics (e.g. `Password#verify`, `Id.generate`) are kept.
@@ -14,7 +14,7 @@ export type OptionalProperty<Property extends AnyPropertyConstructor> = Property
     readonly type: IPropertyType<infer SchemaType, infer Value>;
 } ? SchemaType extends TOptional<TSchema> ? StoredField<Property> : Omit<Property, "type" | "prototype" | "safeParse" | "~standard" | CallableKey> & {
     new (value: PropertyValue<TOptional<SchemaType>, Value>): AbstractProperty<TOptional<SchemaType>, Value> & Omit<InstanceType<Property>, keyof AbstractProperty<TSchema>>;
-    readonly type: IPropertyType<TOptional<SchemaType>, Value> & UniqueTypeOf<Property>;
+    readonly type: IPropertyType<TOptional<SchemaType>, Value> & UniqueTypeOf<Property> & SensitiveTypeOf<Property>;
     safeParse(value: unknown): ParseResult<PropertyValue<TOptional<SchemaType>, Value>>;
     readonly "~standard": StandardSchemaV1.Props<PropertyValue<TOptional<SchemaType>, Value>, PropertyValue<TOptional<SchemaType>, Value>>;
 } : never;

package/dist/core/property/types/property-type.interface.d.ts

@@ -25,6 +25,23 @@ export type UniqueMark<Unique extends boolean> = Unique extends true ? {
         readonly unique: true;
     };
 } : unknown;
+/**
+ * The type of a property declared `sensitive`, as `Password`, so that the
+ * type of `toJSON` masks the keys holding it.
+ */
+export type SensitiveMark<Sensitive extends boolean> = Sensitive extends true ? {
+    readonly type: {
+        readonly sensitive: true;
+    };
+} : unknown;
+/** `{ sensitive: true }` when `Property` is declared `sensitive`, for its optional version. */
+export type SensitiveTypeOf<Property> = Property extends {
+    readonly type: {
+        readonly sensitive: true;
+    };
+} ? {
+    readonly sensitive: true;
+} : unknown;
 /** `{ unique: true }` when `Property` is declared `unique`, for its optional version. */
 export type UniqueTypeOf<Property> = Property extends {
     readonly type: {

package/dist/core/record/abstract-record.d.ts

@@ -1,8 +1,8 @@
-import type { BlueprintData, BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
+import type { BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "../parse/types/parse.interface.js";
 import type { StandardSchemaV1 } from "../standard/standard-schema.js";
 import { Meta } from "../symbols/meta.js";
-import type { IRecord, RecordChange, RecordEffects, RecordSettings } from "./types/record.interface.js";
+import type { IRecord, RecordChange, RecordEffects, RecordJson, RecordSettings } from "./types/record.interface.js";
 /** The statics of a class made by `recordOf`, that its records read. */
 interface RecordDeclaration<Properties extends IBlueprintCollection> {
     readonly blueprint: IBlueprint<Properties>;
@@ -54,7 +54,7 @@ export declare const RecordPluginHooks: unique symbol;
  * having `key`, then those of the record, for a stored change.
  */
 export declare function runRecordEffects<Self extends object>(record: Self, key: PropertyKey, next: unknown, previous: unknown): Self;
-export declare abstract class AbstractRecord<Properties extends IBlueprintCollection> implements IRecord<Properties> {
+export declare abstract class AbstractRecord<Properties extends IBlueprintCollection, Sensitive extends string = never> implements IRecord<Properties, Sensitive> {
     get [Meta](): RecordDeclaration<Properties>;
     constructor(value: BlueprintInput<Properties>);
     /**
@@ -72,7 +72,7 @@ export declare abstract class AbstractRecord<Properties extends IBlueprintCollec
      * The value with the sensitive keys, and every property declared
      * `sensitive` (as `Password`), masked.
      */
-    toJSON(): Readonly<Partial<BlueprintData<Properties>>>;
+    toJSON(): RecordJson<Properties, Sensitive>;
     /**
      * Validates `value`, stores it under `key`, then runs `onSetAll` and the
      * effect of `key` in `onSet`.

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

@@ -9,6 +9,8 @@ export declare const InvalidRecordValue: import("../../index.js").DeclaredExcept
     readonly errors: readonly string[];
     readonly issues: readonly Issue[];
 }>;
+/** `recordOf` or `entityOf` got an option it cannot use, as a `name` that is not an identifier. */
+export declare const InvalidRecordDeclaration: import("../../index.js").DeclaredExceptionClass<string>;
 /**
  * A record is given a key its blueprint does not declare, in its value or by
  * `set`; `key` is its path, e.g. `address.extra`, and `source` the record name.

package/dist/core/record/name.d.ts

@@ -0,0 +1,16 @@
+/** Whether `name` can be the `name` option of `recordOf` or `entityOf`. */
+export declare function isRecordName(name: unknown): name is string;
+/**
+ * The name of a record or entity class: the `name` option it, or the class it
+ * extends, was declared with, which bundlers and minifiers do not change;
+ * without one, the name of the class.
+ */
+export declare function recordNameOf(Class: object): string;
+/** Keeps the `name` option `Class` was declared with. */
+export declare function declareRecordName(Class: object, name: string): void;
+/**
+ * The name `Class` declares: the `name` option of it or of a class it
+ * extends, or a `static recordName` of its own; `undefined` when the name of
+ * the record is only the name of its class.
+ */
+export declare function declaredRecordNameOf(Class: object): string | undefined;

package/dist/core/record/plugin.d.ts

@@ -9,8 +9,12 @@ export declare const RecordPlugins: unique symbol;
 export declare const IdentifiedRecord: unique symbol;
 /** Whether `version` is a semantic version. */
 export declare function isVersion(version: unknown): version is string;
-/** The major, minor and patch of a semantic version. */
-export declare function versionParts(version: string): readonly [number, number, number];
+/**
+ * Whether a plugin of version `available` satisfies a reference to
+ * `requested`: the same major version (the same minor below `1.0.0`), and
+ * not older.
+ */
+export declare function satisfies(available: string, requested: string): boolean;
 /** The `onSet` and `onSetAll` a plugin runs, for changes to its `keys`. */
 interface RecordPluginHook {
     readonly plugin: AnyRecordPlugin;

package/dist/core/record/record.d.ts

@@ -1,12 +1,12 @@
 import type { AnyBlueprint, IBlueprint, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
 import { AbstractRecord } from "./abstract-record.js";
-import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginUniqueKey, RecordPluginContext, WithPluginProperties } from "./types/plugin.interface.js";
+import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginSensitiveKey, PluginUniqueKey, RecordPluginContext, WithPluginProperties } from "./types/plugin.interface.js";
 import type { RecordConstructor, RecordKey, RecordOptions } from "./types/record.interface.js";
 /**
  * What `recordBuilderOf` returns: `recordOf`, whose `options.plugins` can
  * pick plugins from `Context`, the plugins of its catalogs by name.
  */
-export type RecordBuilder<Context> = <Properties extends IBlueprintCollection, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: RecordOptions<NoInfer<Properties>, Change, Unique, Plugins, Context>) => RecordConstructor<WithPluginProperties<Properties, Plugins>, Change, Unique[number] | PluginUniqueKey<Plugins>, PluginMembers<Plugins>>;
+export type RecordBuilder<Context> = <Properties extends IBlueprintCollection, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: RecordOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive>) => RecordConstructor<WithPluginProperties<Properties, Plugins>, Change, Unique[number] | PluginUniqueKey<Plugins>, PluginMembers<Plugins>, never, Sensitive[number] | PluginSensitiveKey<Plugins>>;
 /**
  * A `recordOf` whose `options.plugins` can pick plugins from `catalogs`,
  * e.g. `recordBuilderOf(StdRecordPlugins)`, as `(ctx) => [ctx.publishable]`;
@@ -27,6 +27,7 @@ export declare function pluginContextOf(catalogs: readonly IRecordPluginCatalog[
 export declare const recordOf: RecordBuilder<Record<never, never>>;
 /** The options `declareRecord` takes, untyped. */
 interface RecordOptionsInput {
+    readonly name?: string;
     readonly sensitive?: readonly string[];
     readonly unique?: readonly string[];
     readonly change?: readonly string[];
@@ -37,5 +38,5 @@ interface RecordOptionsInput {
  * and named `name`; `reserved` are more names no key can take, the members
  * `Base` adds, and `context` the plugins `options.plugins` can pick from.
  */
-export declare function declareRecord(Base: abstract new (value: never) => AbstractRecord<IBlueprintCollection>, declared: AnyBlueprint, { plugins, ...declaredOptions }: RecordOptionsInput, name: string, reserved?: readonly string[], context?: Readonly<Record<string, AnyRecordPlugin>>): abstract new (value: never) => AbstractRecord<IBlueprintCollection>;
+export declare function declareRecord(Base: abstract new (value: never) => AbstractRecord<IBlueprintCollection>, declared: AnyBlueprint, { plugins, name: declaredName, ...declaredOptions }: RecordOptionsInput, fallback: string, reserved?: readonly string[], context?: Readonly<Record<string, AnyRecordPlugin>>): abstract new (value: never) => AbstractRecord<IBlueprintCollection>;
 export {};

package/dist/core/record/types/plugin.interface.d.ts

@@ -7,6 +7,11 @@ import type { RecordSettings } from "./record.interface.js";
  * class holds a value under it.
  */
 export declare const RecordUniqueKeys: unique symbol;
+/**
+ * Where the type of the keys a record class lists in `options.sensitive` is
+ * kept, for the type of `toJSON` of what its plugin is applied to. Type only.
+ */
+export declare const RecordSensitiveKeys: unique symbol;
 /** What `recordPluginOf` takes, after the record class. */
 export interface RecordPluginOptions {
     /** A semantic version, e.g. `1.2.0`; `1.0.0` when left out. */
@@ -139,4 +144,10 @@ export type PluginUniqueKey<Plugins extends readonly AnyRecordPlugin[]> = Plugin
         readonly [RecordUniqueKeys]?: infer Key;
     };
 } ? Extract<Key, string> : never : never;
+/** The keys the record classes of the plugins list in `options.sensitive`. */
+export type PluginSensitiveKey<Plugins extends readonly AnyRecordPlugin[]> = Plugins[number] extends infer Plugin ? Plugin extends {
+    readonly record: {
+        readonly [RecordSensitiveKeys]?: infer Key;
+    };
+} ? Extract<Key, string> : never : never;
 export {};