import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import type * as Schedule from "effect/Schedule";
import type * as Aggregate from "./Aggregate.ts";
import type * as Event from "./Event.ts";
import type * as Key from "./Key.ts";
import type * as View from "./View.ts";
/** One source, or several. */
export type From = View.Source | ReadonlyArray<View.Source>;
/** The sources of a `from`. */
export type SourcesOf<F> = F extends ReadonlyArray<infer S> ? S : F;
/**
* What a policy receives for each event it subscribes to.
*/
export interface Trigger<F, E, Key extends Key.Any = View.SourceKey<SourcesOf<F>>> {
/** The key the event was routed to: the source instance, unless the policy declares `key`. */
readonly key: Key.RefOf<Key>;
/** The route named in `keyOf` that brought it here, if any. */
readonly route: string | undefined;
/** The aggregate or view instance the event came from (a view key's value for a Schema-keyed view). */
readonly source: Key.RefOf<View.SourceKey<SourcesOf<F>>>;
/** The event. */
readonly event: E;
/** The event's envelope. */
readonly envelope: Aggregate.Envelope<Key.IdOf<View.SourceKey<SourcesOf<F>>>>;
/** For a view source: the view's state after the event. */
readonly state: View.SourceState<SourcesOf<F>>;
}
/**
* How a policy's Layer tunes it. These are variants: they change how it runs,
* never what it means.
*/
export interface Options {
/** Retry a failed run on this schedule before leaving it to the platform's redelivery. */
readonly retry?: Schedule.Schedule<unknown, unknown>;
}
/**
* A policy's handler. It runs after the triggering event commits, at least
* once, in order per source instance. Every failure must be handled: send a
* command or ignore it. It requires nothing: resolve aggregate clients, Ports
* and views while building it, in `toLayer`.
*/
export type Handler<T> = (trigger: T) => Effect.Effect<void>;
/**
* Structural constraint satisfied by every policy class.
*/
export interface Any extends Context.Key<unknown, unknown> {
readonly kind: "Policy";
readonly policyName: string;
readonly definition: {
readonly from: From;
readonly key?: Key.Any;
readonly keyOf?: { readonly [key: string]: unknown };
readonly on: ReadonlyArray<Event.Any>;
};
}
/** The declared `key` (an optional field), or the source's key when there is none. */
type KeyOfDefinition<D> = D extends { readonly key?: infer K }
? Exclude<K, undefined> extends infer Declared extends Key.Any
? [Declared] extends [never]
? SourceKeyOfDefinition<D>
: Declared
: SourceKeyOfDefinition<D>
: SourceKeyOfDefinition<D>;
type SourceKeyOfDefinition<D> = D extends { readonly from: infer F }
? View.SourceKey<SourcesOf<F>>
: never;
/** The trigger type of a policy class. */
export type TriggerOf<P extends Any> = Trigger<
P["definition"]["from"],
Aggregate.InstanceOf<P["definition"]["on"][number]>,
KeyOfDefinition<P["definition"]>
>;
type AsList<F> = F extends ReadonlyArray<View.Source> ? F : readonly [F];
/**
* The pure definition of a policy: its invariants.
*/
export interface Definition<
F extends From,
On extends ReadonlyArray<Event.Any>,
Key extends Key.Any | undefined,
> {
/** The aggregate or view, or several, whose events it reacts to. */
readonly from: F;
/**
* What partitions it: an aggregate, whose refs are its keys, or a string
* Schema, whose values are. Triggers for one key run in order, one at a
* time. Defaults to the source instance.
*/
readonly key?: Key;
/** Which key each trigger goes to, by event tag or source name (like a view's `keyOf`). */
readonly keyOf?: Key extends Key.Any
? {
readonly [K in View.HandlerKey<AsList<F>>]?: View.Routed<
View.KeyFn<Key, View.InputFor<AsList<F>, K>>
>;
}
: never;
/** The events it reacts to. */
readonly on: On;
}
/** The requirement identifier of a policy class. */
export type Identifier<P extends Any> = P extends Context.Key<infer I, unknown> ? I : never;
/**
* Type-level identity of a policy in an Effect's requirements.
*/
export interface PolicyKey<Name extends string> {
readonly "~alchemy/Domain/Policy": Name;
}
/**
* "Whenever this happens, do that": one of the business's standing rules. On
* an event from an aggregate or a view, it decides what to do next and acts by
* sending commands and calling external systems. Policies run shortly after the
* event, never in the same step, so use them only for eventually consistent
* work. Delivery is at least once; the commands a policy sends get ids
* derived from the event, so a second run sends the same commands.
*
* ### Reacting to an aggregate
* **Example:** Open an account for every new customer
* ```typescript
* import * as Domain from "@alchemy.run/domain";
* import * as Effect from "effect/Effect";
* import { Account, AccountId, OpenAccount } from "./Account.ts";
* import { Customer, CustomerRegistered } from "./Customer.ts";
*
* export class MainAccountProvisioning extends Domain.Policy("MainAccountProvisioning", {
* from: Customer,
* on: [CustomerRegistered],
* }) {}
*
* export const MainAccountProvisioningLive = MainAccountProvisioning.toLayer(
* Effect.gen(function* () {
* const accounts = yield* Account;
* return Effect.fn(function* ({ source }) {
* yield* accounts
* .send(AccountId.make(`${source.id}-main`), new OpenAccount({ owner: source.id }))
* .pipe(Effect.catchTag("AlreadyOpen", () => Effect.void));
* });
* }),
* );
* ```
*
* ### Calling an external system
* **Example:** Score risky withdrawals
* ```typescript
* import * as Domain from "@alchemy.run/domain";
* import * as Effect from "effect/Effect";
* import { Account, MoneyWithdrawn } from "./Account.ts";
* import { FraudCheck } from "./FraudCheck.ts";
*
* export class FraudReview extends Domain.Policy("FraudReview", {
* from: Account,
* on: [MoneyWithdrawn],
* }) {}
*
* export const FraudReviewLive = FraudReview.toLayer(
* Effect.gen(function* () {
* const fraud = yield* FraudCheck;
* return Effect.fn(function* ({ source, event }) {
* const { risk } = yield* fraud.score({ accountId: source.id, amount: event.amount });
* yield* Effect.log(`risk ${risk} for ${source.id}`);
* });
* }),
* );
* ```
*
* @primitive
*/
export const make = <
const Name extends string,
const F extends From,
const On extends ReadonlyArray<Event.Any>,
Key extends Key.Any | undefined = undefined,
>(
name: Name,
definition: Definition<F, On, Key>,
): PolicyClass<Name, F, On, Key extends Key.Any ? Key : View.SourceKey<SourcesOf<F>>> => {
const Tag = Context.Service<PolicyKey<Name>, Handler<unknown>>()(`alchemy/Domain/Policy/${name}`);
return class extends Tag {
static readonly kind = "Policy" as const;
static readonly policyName: Name = name;
static readonly definition = definition;
static toLayer<Self extends Any, E, R>(
this: Self,
build: Effect.Effect<Handler<TriggerOf<Self>>, E, R>,
options: Options = {},
): Layer.Layer<Identifier<Self>, E, R> {
const retry = options.retry;
return Layer.effect(
this as unknown as Context.Key<Identifier<Self>, Handler<TriggerOf<Self>>>,
retry
? Effect.map(
build,
(handle): Handler<TriggerOf<Self>> =>
(trigger) =>
handle(trigger).pipe(
Effect.catchDefect((defect) => Effect.fail(defect)),
Effect.retry(retry),
Effect.orDie,
),
)
: build,
);
}
} as unknown as PolicyClass<
Name,
F,
On,
Key extends Key.Any ? Key : View.SourceKey<SourcesOf<F>>
>;
};
/**
* The class type returned by {@link make}.
*/
export interface PolicyClass<
Name extends string,
F extends From,
On extends ReadonlyArray<Event.Any>,
Key extends Key.Any,
> extends Context.ServiceClass<
PolicyKey<Name>,
string,
Handler<Trigger<F, Aggregate.InstanceOf<On[number]>, Key>>
> {
readonly kind: "Policy";
readonly policyName: Name;
readonly definition: {
readonly from: F;
readonly key?: Key;
readonly keyOf?: { readonly [key: string]: unknown };
readonly on: On;
};
/**
* Implement the policy. The construction Effect runs once, resolving every
* service the handler uses (aggregate clients, views, Ports); the handler
* itself requires nothing. `options` tune how it runs, such as retries.
*/
toLayer<Self extends Any, E, R>(
this: Self,
build: Effect.Effect<Handler<TriggerOf<Self>>, E, R>,
options?: Options,
): Layer.Layer<Identifier<Self>, E, R>;
}