@rikalabs/akter 0.1.0-alpha.0

package/dist/actor/definition.js

@@ -0,0 +1,147 @@
+import { Context, Effect } from "effect";
+import { clientOf } from "../client/make.js";
+import { compile, publish, singleton, } from "./descriptor.js";
+import { createOf, handleOf, intentsOf, runOfId } from "./handles.js";
+import { jobLayer, ordinaryLayer, queryLayer, singletonLayer, } from "./layers.js";
+/**
+ * Validates and compiles a definition, throwing on any invalid declaration
+ * before anything is published, and returns the actor type's handles,
+ * layers, and client.
+ */
+const make = (name, definition) => {
+    const descriptor = compile({ name, declared: definition });
+    class Turn extends Context.Service()(`akter/Turn/${name}`) {
+    }
+    class Executor extends Context.Service()(`akter/Executor/${name}`) {
+    }
+    class Workflow extends Context.Service()(`akter/Workflow/${name}`) {
+    }
+    class Read extends Context.Service()(`akter/Read/${name}`) {
+    }
+    class Connection extends Context.Service()(`akter/Connection/${name}`) {
+    }
+    const phases = { Turn, Read, Connection, Workflow, Executor };
+    /** An ordinary actor's `toLayer`: the builder's failure fails the layer. */
+    const ordinaryToLayer = (build) => ordinaryLayer({ descriptor, phases, build, services: Effect.context() });
+    /** A singleton's `toLayer`: the builder runs, and fails, per activation, not in the layer. */
+    const singletonToLayer = (build) => singletonLayer({ descriptor, phases, build, services: Effect.context() });
+    const toQueryLayer = (build) => queryLayer({
+        descriptor,
+        phases,
+        build,
+        services: Effect.context(),
+    });
+    const toJobLayer = (build) => jobLayer({
+        descriptor,
+        phases,
+        build,
+        services: Effect.context(),
+    });
+    /** Builds a parent-placed actor's full id from its parent's id and its own key. */
+    const idOf = (parentId, local) => descriptor.childId(parentId, local);
+    const actor = {
+        /** The actor type's name: a letter followed by up to 79 letters or digits. */
+        name,
+        /** The schema of the actor's decoded state. */
+        state: descriptor.state.schema,
+        /** The declared public members. */
+        api: (definition.api ?? {}),
+        /** Event classes this actor emits, which subscriptions to it may name. */
+        events: (definition.events ?? []),
+        /** The context of a command turn, read with `yield* X.Turn` in `X.toLayer` handlers. */
+        Turn,
+        /** The read-only context of a query or stream handler, read with `yield* X.Read`. */
+        Read,
+        /** The context of a connection handler, read with `yield* X.Connection`. */
+        Connection,
+        /** The context of one executor attempt, read with `yield* X.Executor`. */
+        Executor,
+        /** The context of a workflow body, read with `yield* X.Workflow`. */
+        Workflow,
+        /**
+         * Reattaches to a workflow execution by id without contacting its owner. An
+         * id of another tenant, actor type, or workflow fails `InvalidExecutionId`.
+         */
+        run: ((member, executionId) => runOfId(descriptor, member, executionId)),
+        /**
+         * Implements every `api` and `internal` command, connection, stream, and
+         * workflow; reducers have no entry. Pass the handlers directly, or an
+         * Effect that builds them from services; each handler's requirements are
+         * inferred. Command handlers read their turn with `yield* X.Turn`, and one
+         * that acquires a handle with `X.get` does not compile.
+         *
+         * The builder runs once when the layer is built, and its failure fails the
+         * layer. On a singleton it runs once per activation instead, in the
+         * activation's scope, so a fiber it forks with `Effect.forkScoped` lives
+         * exactly as long as the one cluster-wide activation; its failure fails
+         * that activation, not the layer.
+         *
+         * @example
+         * const CounterLive = Counter.toLayer({
+         *   Increment: Effect.fn(function* (amount) {
+         *     const turn = yield* Counter.Turn
+         *     yield* turn.state.set({ count: turn.state.count + amount })
+         *     return turn.state.count
+         *   }),
+         * })
+         */
+        toLayer: (descriptor.singleton ? singletonToLayer : ordinaryToLayer),
+        /**
+         * Implements every query in `api`, directly or from an Effect that builds
+         * the handlers. Queries run on the caller's node against committed rows
+         * and read their context with `yield* X.Read`.
+         */
+        toQueryLayer,
+        /**
+         * Implements every bound job's executor, directly or from an Effect that
+         * builds them. Executors run after the turn that enqueued the job commits,
+         * read `yield* X.Executor`, and have no database capability; the return
+         * value is routed to the binding's `onSuccess`.
+         */
+        toJobLayer,
+        /**
+         * A request/reply handle to the actor with `id`, or to the singleton. It
+         * never contacts the actor; a call does. An `id` that fails the key schema
+         * is a defect, and acquiring a handle inside a turn is a defect.
+         */
+        get: (descriptor.singleton
+            ? () => handleOf(descriptor, "singleton", false)
+            : (id) => handleOf(descriptor, id, false)),
+        /**
+         * Mints a new UUIDv7 id and returns its handle. Only an unkeyed actor that
+         * is not parent-placed has `create`; calling it inside a turn is a defect.
+         */
+        create: (() => createOf(descriptor)),
+        /**
+         * Builds a parent-placed actor's full id from its parent's id and its own
+         * key, as `c1.<byte length of parent>.<parent>.<local>`.
+         */
+        idOf: idOf,
+        /**
+         * Durable intents to this actor; only command turns provide `InTurn`. The
+         * id is a plain string so `X.intents(turn.id)` works for every key kind;
+         * an id that fails the key schema is a deterministic defect. The target
+         * shares the sending turn's tenant. A keyless workflow start is keyed by the
+         * turn's command id and its order among the turn's starts, so a retried
+         * turn restages the same executions.
+         *
+         * @example
+         * const later = yield* Counter.intents(turn.id)
+         * yield* later.Increment(1).pipe(Intent.after("1 minute"))
+         */
+        intents: (descriptor.singleton
+            ? () => intentsOf(descriptor, "singleton")
+            : (id) => intentsOf(descriptor, id)),
+        /**
+         * A Promise client of this actor's public members over `Actors.serve`'s
+         * HTTP protocol, for browsers and other code that doesn't run Effect.
+         * Workflows are not served; a parent-placed actor is reached by its full
+         * id and never created by a client.
+         */
+        client: (options) => clientOf(descriptor.served)(options),
+    };
+    publish({ definition: actor, descriptor });
+    return actor;
+};
+/** `Actor.make` and `Actor.singleton`, which the package entry re-exports on `Actor`. */
+export const Definition = { make: make, singleton };

package/dist/actor/descriptor.d.ts

@@ -0,0 +1,172 @@
+import { Effect, Schema } from "effect";
+import type { ActorRef, System } from "../identity/caller.ts";
+import type { Actors } from "../handles/actors.ts";
+import type { InternalActors } from "../runtime/actors.ts";
+import type { Access } from "../policies/access.ts";
+import type { Placement } from "../runtime/storage/codec.ts";
+import type { RegisteredSubscription } from "../runtime/members.ts";
+import type { AnyCommand, AnyMember, MemberRecord, ValueSchema } from "../members/command.ts";
+import type { AnyConnection } from "../members/connection.ts";
+import type { AnyStream } from "../members/stream.ts";
+import type { AnyReducer } from "../members/reducer.ts";
+import { type AnyWorkflow } from "../members/workflow.ts";
+import type { AnySubscription } from "../members/subscription.ts";
+import type { AnyJob, AnyJobBinding } from "../members/job.ts";
+import { type AnyBlob } from "../members/blob.ts";
+import type { EventClass } from "../members/event.ts";
+import { type PayloadDeclaration, type DefinitionPayloads, payloadCodec } from "../members/payload.ts";
+import { type Policy, type TurnPolicy } from "../policies/command.ts";
+import { type JobPolicy } from "../policies/job.ts";
+import { type CronEntry } from "../policies/schedules.ts";
+import { type AnyOwnedTable } from "../tables/owned.ts";
+import { exitCodec } from "../runtime/workflows/steps.ts";
+import { type ActorState } from "../state/migration.ts";
+import { type MemberCodecs, type StateCodec } from "./codecs.ts";
+import { type ServedDefinition } from "./served.ts";
+/** Whether a definition's `key` is `Actor.singleton`. */
+export declare const isSingletonKey: <I>(input: I) => input is I & {
+    readonly _tag: "Singleton";
+};
+/** Marker for a singleton actor's `key`: one instance per tenant, resolved with `X.get()`. */
+export declare const singleton: {
+    readonly _tag: "Singleton";
+};
+/** The type of `Actor.singleton`, the `key` of a singleton actor. */
+export type SingletonKey = typeof singleton;
+export type KeySchema = Schema.Codec<string, string>;
+/** The declaration `Actor.make` compiles, before its type parameters are erased. */
+export interface Declaration {
+    readonly key?: KeySchema | SingletonKey | undefined;
+    readonly placement?: "tenant" | "actor" | {
+        readonly parent: object;
+    } | undefined;
+    readonly state?: ActorState | undefined;
+    readonly events?: ReadonlyArray<EventClass> | undefined;
+    readonly feeds?: ReadonlyArray<EventClass> | undefined;
+    readonly tables?: ReadonlyArray<AnyOwnedTable> | undefined;
+    readonly blobs?: ReadonlyArray<AnyBlob> | undefined;
+    readonly api?: MemberRecord | undefined;
+    readonly internal?: MemberRecord | undefined;
+    readonly createdBy?: AnyCommand | undefined;
+    readonly schedules?: Readonly<Record<string, AnyCommand>> | undefined;
+    readonly jobs?: Readonly<Record<string, AnyJobBinding>> | undefined;
+    readonly policy?: Policy | undefined;
+    readonly access?: Access | undefined;
+    readonly subscriptions?: ReadonlyArray<AnySubscription> | undefined;
+}
+/** One declared job of an actor: its schema, compiled payload codec, and resolved binding. */
+export interface CompiledJob {
+    readonly job: AnyJob;
+    readonly codec: ReturnType<typeof payloadCodec<AnyJob>>;
+    readonly policy: JobPolicy;
+}
+/** A connection member's frame and session codecs. */
+export interface ConnectionCodecs {
+    readonly encodeServer: (value: {
+        readonly value: unknown;
+    }) => Effect.Effect<string, Schema.SchemaError>;
+    readonly decodeClient: (text: string) => Effect.Effect<{
+        readonly value: unknown;
+    }, Schema.SchemaError>;
+    readonly encodeSession: ((value: {
+        readonly value: unknown;
+    }) => Effect.Effect<string, Schema.SchemaError>) | undefined;
+    readonly decodeSession: ((text: string) => Effect.Effect<{
+        readonly value: unknown;
+    }, Schema.SchemaError>) | undefined;
+}
+/** Runtime access to a definition's internal handle, for test harnesses. */
+export interface InternalHandle {
+    /**
+     * A handle to actor `id` of `tenant` that calls as `caller` and reaches
+     * `internal` commands; an `id` that fails the key schema is a defect.
+     */
+    readonly handle: (id: string, tenant: string, caller: typeof System.Type) => Effect.Effect<{
+        readonly ref: ActorRef;
+    }, never, Actors | InternalActors>;
+}
+/**
+ * Everything `Actor.make` derives from one declaration, compiled once and
+ * frozen: validated members and their codecs, resolved policy, identity,
+ * placement, jobs, subscriptions, and the served view. Every phase adapter,
+ * handle, layer, and lookup reads it; it is process metadata, never durable
+ * authority.
+ */
+export interface Descriptor {
+    readonly name: string;
+    readonly access: Access | undefined;
+    readonly singleton: boolean;
+    /** Unkeyed with a creation command, so a turn may mint its ids. */
+    readonly mintable: boolean;
+    /** True for an unkeyed actor that is not parent-placed, whose ids a client mints. */
+    readonly minted: boolean;
+    readonly placement: Placement;
+    /** Levels below the actor-placed root; a root is 0. */
+    readonly depth: number;
+    /** The definition this actor is placed on, when parent-placed. */
+    readonly parent: Descriptor | undefined;
+    readonly idSchema: KeySchema;
+    readonly decodeId: (id: string) => Effect.Effect<string, Schema.SchemaError>;
+    readonly encodeId: (id: string) => Effect.Effect<string, Schema.SchemaError>;
+    readonly isId: (id: string) => boolean;
+    readonly childId: (parentId: string, local: string) => string;
+    readonly api: MemberRecord;
+    readonly internalCommands: MemberRecord;
+    /** `api` then `internal` members, in declaration order. */
+    readonly members: ReadonlyArray<AnyMember>;
+    readonly commands: ReadonlyArray<AnyCommand>;
+    readonly queries: ReadonlyArray<AnyMember>;
+    readonly reducers: ReadonlyArray<AnyReducer>;
+    readonly connections: ReadonlyArray<AnyConnection>;
+    readonly streams: ReadonlyArray<AnyStream>;
+    readonly workflows: ReadonlyArray<AnyWorkflow>;
+    readonly internalMembers: ReadonlySet<AnyMember>;
+    /** Tags of `internal` commands that subscriptions deliver to; intents never reach them. */
+    readonly handlerTags: ReadonlySet<string>;
+    readonly watches: ReadonlySet<string>;
+    readonly codecs: ReadonlyMap<string, MemberCodecs>;
+    readonly connectionCodecs: ReadonlyMap<string, ConnectionCodecs>;
+    readonly workflowExits: ReadonlyMap<string, ReturnType<typeof exitCodec>>;
+    readonly fields: Readonly<Record<string, ValueSchema>>;
+    readonly state: StateCodec;
+    readonly events: ReadonlyMap<string, EventClass>;
+    readonly eventCodecs: ReadonlyMap<string, ReturnType<typeof payloadCodec<EventClass>>>;
+    readonly feeds: ReadonlySet<string>;
+    readonly jobs: ReadonlyMap<string, CompiledJob>;
+    /** Tags of jobs whose executor progress some connection or stream receives. */
+    readonly progressJobs: ReadonlySet<string>;
+    readonly policy: TurnPolicy;
+    readonly cron: ReadonlyArray<CronEntry>;
+    readonly tables: ReadonlyArray<AnyOwnedTable>;
+    readonly blobs: ReadonlyArray<AnyBlob>;
+    readonly subscriptions: ReadonlyArray<AnySubscription>;
+    readonly registeredSubscriptions: ReadonlyArray<RegisteredSubscription>;
+    /** Event and job chains this actor writes (or only reads, with `writes` false). */
+    readonly payloads: (writes: boolean) => ReadonlyArray<PayloadDeclaration>;
+    /** What `durable payloads check` and `clear` read. */
+    readonly definitionPayloads: DefinitionPayloads;
+    readonly served: ServedDefinition;
+    /** The handle that reaches `internal` commands too, for test harnesses. */
+    readonly internal: InternalHandle;
+}
+/** The descriptor of an `Actor.make` definition, or undefined for any other value. */
+export declare const descriptorOf: (definition: WeakKey) => Descriptor | undefined;
+/**
+ * Validates a declaration and compiles its descriptor, throwing on the first
+ * invalid part. It publishes nothing: `publish` records the descriptor and
+ * its table ownership only after the whole definition has compiled, so a
+ * rejected definition leaves every registry as it was.
+ */
+export declare const compile: ({ name, declared, }: {
+    readonly name: string;
+    readonly declared: Declaration;
+}) => Descriptor;
+/**
+ * Records `descriptor` for `definition` and gives its tables to the actor
+ * type. `compile` has already validated every table, so this cannot fail
+ * part-way.
+ */
+export declare const publish: ({ definition, descriptor, }: {
+    readonly definition: WeakKey;
+    readonly descriptor: Descriptor;
+}) => void;