@kestack/kabuki 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kishore Polamarasetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# @kestack/kabuki
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An app as one tree of Actors outside React: each Actor a small state machine driven by Messages, one immutable Snapshot for the whole app, Effect running the work, and React only drawing it.
+
+## Big picture
+
+Kabuki is the Elm architecture, as [Foldkit](https://github.com/foldkit/foldkit)
+builds it on Effect, organized as a tree of Actors and drawn by React. Each
+Actor is a state machine and an actor at once: Messages are the only way it
+changes, and its State decides which Children it Invokes, which Capabilities
+it Provides to them and which Workers run. Leaving a State stops all of it.
+Any fact in the Model can own a Worker too: an upload runs for as long as its
+row says Uploading.
+Keyed Children follow the Model: a list of items can be a list of Actors.
+It is declarative, as React is: a parent says what should be, never what to
+do. It controls its Children only by whether they exist and by their Props,
+and what it must control it owns, as React lifts state up.
+
+The whole app is one immutable Snapshot, and handling a Message is a pure
+function from one Snapshot to the next. There is one mailbox, and a Message is
+handled before `send` returns. Around that pure core, everything that touches
+the outside world is Effect: each Instance's work lives in nested Scopes, and
+only the work where a Message landed is stopped or started. An Actor's own
+code reaches only the Capabilities it Requires. What its Children need bubbles
+up until an ancestor Provides it, and the app does not compile until its Layer
+covers the rest.
+
+The Runtime runs a History. It starts the root Instance at the History's
+Head, hands it every Message through one Mailbox, and writes each one into
+the History; every Instance runs the rest of its own life, starting and
+stopping its States, Children, Workers and Commands. The History is a tree
+of Messages, like git commits, that replays itself to the Snapshot right
+after any one of them, on any Branch, while the live app keeps running. Stop,
+move its Head, and start again, and new Messages grow a new Branch. A History
+is also what an app is saved as and drawn from before it runs: on a server,
+at build time, and across a hot reload.
+
+Read the language in [CONTEXT.md](./CONTEXT.md), the decisions in
+[docs/adr/](./docs/adr/), and how the History works in
+[docs/history.md](./docs/history.md). A live demo, Opening an app, is at `/demos/opening-an-app` in the docs app: every concept in one story, drawn as the tree.
+
+## Install
+
+```sh
+pnpm add @kestack/kabuki effect react
+```
+
+- `effect`: Schemas describe Inputs, Models, States and Messages, and every
+  one is checked against its Schema as it is made; Workers, Commands and
+  Capabilities are Effect values and Layers.
+- `react`: `@kestack/kabuki/react` draws the tree with React components.
+
+## Exports
+
+### `@kestack/kabuki`
+
+| Export             | What it does                                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `Actor.make`       | Defines an Actor from its Requires and Schemas. `.build` adds how it behaves, at the top and in one block per State. |
+| `Actor.many`       | Declares a keyed Child slot: one Instance of an Actor per key the parent Invokes.                                    |
+| `Command.make`     | Defines a Command from its name, the Schema of its args and the Effect it runs; an Update calls it with the args.    |
+| `Runtime.start`    | Runs an Actor, or carries a History on, inside a Scope, with the app's Layer; gives back `send`, `start` and `stop`. |
+| `History.make`     | A new, empty History for an Actor, with the root's Input.                                                            |
+| `History.load`     | A History carrying on from one saved before, read with the Actor's code as it is now.                                |
+| `History.restored` | The lightest History an app can be saved as: one Restore of a Snapshot at a Time, right after init.                  |
+| `Replay.make`      | Plays Branches of one app from init, remembering Snapshots so playing again starts from the nearest one.             |
+| `Replay.fold`      | The Snapshot right after a Branch, played now from init with the root's Input, with no yielding.                     |
+| `restore`          | The Restore Message: given to the root, it replaces the whole Snapshot with a saved one, checked against the Actors. |
+| `isRestore`        | Tells a Restore from any other Message.                                                                              |
+| `RESTORE`          | The Restore Message's tag.                                                                                           |
+| `init`             | The Snapshot right after init: the root and every Child its State Invokes.                                           |
+| `handle`           | Applies one Envelope to a Snapshot and gives the next one, purely.                                                   |
+| `outcomeOf`        | Works out what came of one Envelope on a Snapshot: handled, ignored or dropped. The History never keeps it.          |
+| `instanceAt`       | Finds the Instance with an ID in a Snapshot.                                                                         |
+| `isMany`           | Tells a keyed Child slot from a fixed one in an Instance's Children.                                                 |
+
+### `@kestack/kabuki/react`
+
+| Export        | What it does                                                                                                                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `View.make`   | Defines how one Actor is drawn, one function for every State, as a React component that takes the Instance, and a `ref` and `style`, from its parent.                                                                                                                      |
+| `toReact`     | Turns a root Actor, its View and a Layer into one React component that runs the whole app, one Runtime for every mount; `useRuntime` reads its History, shows any Step, and stops and starts it. Drawn before it runs, on a server too, from a saved History if given one. |
+| `useChild`    | Reads one fixed Child's Model, State and Props from its parent's View, to draw, or only what an optional selector picks; an escape hatch that can never Send.                                                                                                              |
+| `useChildren` | Reads a slot of keyed Children the same way, in order; only the component that calls it re-renders, as they change or as what the selector picks does.                                                                                                                     |
+
+## Usage
+
+### A gate whose States decide what exists
+
+This root signs a user in. While `Anonymous` it Provides `SignIn` and Invokes
+`login`; while `Authenticated` it Provides `Session` and Invokes `todos`.
+
+```ts
+export const Auth = Actor.make('Auth', {
+  requires: [Server],
+  state: Schema.TaggedUnion({
+    Checking: {},
+    Anonymous: {},
+    Authenticated: { user: Schema.String },
+  }),
+  message: Schema.TaggedUnion({
+    CheckedSession: { user: Schema.optional(Schema.String) },
+    LoggedIn: { user: Schema.String },
+    LoggedOut: {},
+  }),
+}).build({
+  init: () => ({ state: { _tag: 'Checking' } }),
+  state: {
+    Checking: {
+      workers: {
+        check: {
+          run: (self) =>
+            Effect.gen(function* () {
+              const user = yield* (yield* Server).checkSession;
+              yield* self.send({ _tag: 'CheckedSession', user });
+            }),
+        },
+      },
+      on: {
+        CheckedSession: ({ user }) => ({
+          state: user ? { _tag: 'Authenticated', user } : { _tag: 'Anonymous' },
+        }),
+      },
+    },
+    Anonymous: {
+      children: { login: Login },
+      provides: (self) =>
+        Layer.succeed(SignIn, {
+          complete: (user) => self.send({ _tag: 'LoggedIn', user }),
+        }),
+      on: {
+        LoggedIn: ({ user }) => ({ state: { _tag: 'Authenticated', user } }),
+      },
+    },
+    Authenticated: {
+      children: { todos: Todos },
+      provides: (self) =>
+        Layer.succeed(Session, {
+          user: self.get.pipe(Effect.map(({ state }) => state.user)),
+          logOut: self.send({ _tag: 'LoggedOut' }),
+        }),
+      on: { LoggedOut: () => ({ state: { _tag: 'Anonymous' } }) },
+    },
+  },
+});
+```
+
+- `make` takes only the Requires and the Schemas, which fix every type. `build` is checked against them: an Update that returns a State the Schema does not have, or a `state.user` read where there is none, does not compile.
+- `build` has two Levels. What is written at the top holds for as long as the Instance lives; what is written in a State's block holds while that State lasts. Each Level can hold `provides`, `children`, `invoke`, `on` and `workers`.
+- An Update that returns a different `_tag` is a Transition: the old State's Children, Workers and Capabilities stop, the new State's start. A Child written at the top lasts through it.
+- A Worker is a named, scoped Effect given `self`: `send` to its own Instance, `get` and `changes` for its current data, and `now` for the app's Time. Written in the `Checking` block, `check` runs while that State lasts.
+- Provides is one Layer per Level, built each time its Level starts. A Capability that reads the Model reads it through `self`, so it never goes stale. It cancels out what the Children below it need; a need nothing cancels bubbles up to the app's Layer.
+- Requires caps the Actor's own code: a Worker, Command or Provide that reaches for anything else does not compile. Update and init never see Capabilities.
+
+### A list of Actors, a Command, and a Worker per key
+
+```ts
+const save = Command.make('save', {
+  args: Schema.Struct({ id: Schema.String }),
+  run: () =>
+    Effect.sleep('1 second').pipe(Effect.as({ _tag: 'Saved' as const })),
+});
+
+const List = Actor.make('List', {
+  model: Schema.Struct({
+    ids: Schema.Array(Schema.String),
+    uploading: Schema.Array(Schema.String),
+    next: Schema.Number,
+  }),
+  message: Schema.TaggedUnion({
+    Added: {},
+    Removed: { id: Schema.String },
+    Saved: {},
+    Uploaded: { id: Schema.String },
+  }),
+}).build({
+  init: () => ({ model: { ids: [], uploading: [], next: 0 } }),
+  children: { rows: Actor.many(Row) },
+  invoke: ({ model }) => ({
+    rows: model.ids.map((id) => ({
+      key: id,
+      input: { text: `#${id}` },
+      props: { uploading: model.uploading.includes(id) },
+    })),
+  }),
+  on: {
+    Added: (_, { model }) => {
+      const id = `${model.next}`;
+      return {
+        model: {
+          ids: [...model.ids, id],
+          uploading: [...model.uploading, id],
+          next: model.next + 1,
+        },
+        command: save({ id }),
+      };
+    },
+    Removed: ({ id }, { model }) => ({
+      model: {
+        ...model,
+        ids: model.ids.filter((kept) => kept !== id),
+        uploading: model.uploading.filter((kept) => kept !== id),
+      },
+    }),
+    Saved: () => ({}),
+    Uploaded: ({ id }, { model }) => ({
+      model: { ...model, uploading: model.uploading.filter((k) => k !== id) },
+    }),
+  },
+  workers: {
+    upload: {
+      each: ({ model }) => model.uploading,
+      run: (self, id) =>
+        Effect.sleep('3 seconds').pipe(
+          Effect.andThen(self.send({ _tag: 'Uploaded', id })),
+        ),
+    },
+  },
+});
+```
+
+- `invoke` sits beside the `children` it feeds, and says which keys exist, the Input each new Child starts from, and the Props each is handed. After every Update, a new key Invokes a Row, a key gone stops it, and a key kept keeps its Instance. From then on the Row owns its data.
+- Props are what the parent says now, worked out again after each of its Updates: the Row declares them with `props` beside `input`, and its Update, its Workers' Conditions and its View read them. It never writes them, and a change runs none of its rules. Props equal to the last ones keep the Instance; new ones are not in the History, since Replay works them out again from the parent.
+- Instance IDs are deterministic: `List/rows[0]#1` is the first `rows` keyed `0`. A key Invoked again gets `#2`, so a Message meant for the old Instance is dropped.
+- A Command is an errand, made once with `Command.make`: a name, the Schema of its args and the Effect it runs from them, ending with at most one Message. The Update asks for it with its args, `save({ id })`, which is plain data a test can compare; the args are checked when it runs. Nothing stops it but its Instance stopping, and there is no cancel. An Update may return a list of Commands; they run concurrently.
+- A Worker runs for exactly as long as its Condition holds, read from the Model, State and Props whenever they change: where it is written, at the top or in a State, and within that always, `while` a test is true, or `each` key a function names, one Worker per key. Removing an id from `uploading` interrupts that upload and runs its finalizers; a finished upload Sends `Uploaded`, whose Update takes its key away. Stopping work is changing the Model.
+- The Worker does the work and the Model keeps the story: every step the user could notice is a Message. A Worker must be able to start from the Model alone, because a resume or a start from an earlier History entry starts every Worker whose condition holds. A Worker that waits until a Time in the Model sleeps for `that - now`, so it waits only what is left. A finalizer never Sends.
+
+### Drawing it with React
+
+```tsx
+export const AuthView = View.make(Auth, ({ _tag, state, children }) => {
+  switch (_tag) {
+    case 'Checking':
+      return <Spinner />;
+    case 'Anonymous':
+      return <LoginView instance={children.login} />;
+    case 'Authenticated':
+      return (
+        <>
+          <p>Signed in as {state.user}</p>
+          <TodosView instance={children.todos} />
+        </>
+      );
+  }
+});
+
+const RowView = View.make(Row, ({ model, props, root }) => (
+  <li {...root} data-uploading={props.uploading}>
+    {model.text}
+  </li>
+));
+const MotionRow = motion.create(RowView);
+
+const DemoApp = toReact(Auth, AuthView, ServerLive);
+```
+
+- One function draws every State. It gets `_tag`, `model`, `state`, `props`, `children` (Handles; arrays for keyed Children, each with its `key`), `send` and `root`; a `switch` on `_tag` narrows `state` and `children`. The DOM stays across a Transition. It never sees Capabilities, so it draws a Replay exactly like the live app.
+- A Child is placed with `<RowView instance={handle} />`. A parent View hands it only where to draw; data from the parent is the Row's Props, which the parent Actor hands it, so its Update and Workers see the same.
+- Spreading `root` on the View's own element hands it the parent's `ref` and `style`, so `motion.create(RowView)` animates it, with no wrapper element, and it stays memoized. A View whose Instance has stopped keeps drawing its last data, so `AnimatePresence` can play its exit.
+- A View re-renders only when its own Instance's Model, State, Props or set of Children changes, or its `ref` or `style` does. Many Messages handled in a row make one render.
+- `DemoApp.useRuntime()` returns `{ history, branch, head, running, shown, show, start, stop, clear, workers, failure }` from anywhere on the page. Each `branch` entry is only its Envelope: `destination`, `message`, `at`, and `source`, the Instance that Sent it and what in it did; `history.outcome(id)` works out whether it was handled, ignored or dropped, and `history.snapshotAt(id)` takes the app apart there. `show(id)` draws the app right after that entry, on any Branch, while the live app runs on; `stop()` closes every Worker, Command and Capability; `start(id)` moves the Head to that entry and goes live there, growing a new Branch, and `start()` carries on from the Head, at its Time. `workers(id)` says what an Instance's Workers are doing live: running, finished, or failed. A start, stop or clear that fails, like the Runtime's first start or `start(id)` with no such entry, is logged with `console.error` and kept as `failure`, an Effect `Cause`, until one succeeds.
+- Work that must survive a stop belongs in a Worker: Commands running at a stop are lost. The outside world is not rewound.
+- What changes over time arrives as Messages: a Worker Sends a `Tick` or its progress, and the View draws the Model. motion can smooth what it draws from one Message to the next.
+- `toReact` does not compile until the Layer covers every Capability the tree still needs.
+
+### Drawing it before it runs
+
+```tsx
+const DemoApp = toReact(Auth, AuthView, ServerLive, { saved });
+```
+
+- The app is drawn before any Runtime exists: with no History, right after init; with a saved one, at its Head, replayed through Suspense. A server or a static build gets the same HTML the client hydrates, and `useRuntime` reads the saved History from the start, so a Timeline is drawn there too. Until the Runtime starts, a Send is dropped.
+- `saved` is what `history.save()` gives: its entries and its Head, each Message, and each Instance of a Restore's Snapshot, written through its Actor's Schemas and read back through them on load. So the encoded side of every Schema must be JSON-safe, and then it is plain JSON: a `Date` as `Schema.DateFromString`, an `Option` as `Schema.OptionFromNullOr`. A saved History never changes, and one whose Head is not one of its entries fails to load. The Runtime carries on live at the Head, with Time going on from the Head's. `History.restored(Auth, snapshot, at).save()` makes the lightest one, a History of one Restore right after init, for an app that saves only its Snapshot; init stays the first Step. Where the History is kept is the app's business.
+- When the last mount closes, the History is left under the app's name, the root Actor's by default, and the next mount of an app with that name carries on from it: the same component mounted again, or a new one after a hot reload, whose code replays the old Messages. A Message the new code handles differently warns and goes on. Give `name` when two apps share a root Actor and must not share a History; two apps of one name mounted at once is a console error.

package/dist/core/actor/actor.d.ts

@@ -0,0 +1,42 @@
+import type { Actor as ActorOf, AnyActor, Behavior, KidsByState, Many, OpenOfBehavior, Requires, Single, Tagged } from './types.ts';
+import { Schema } from 'effect';
+/** An Actor's Schemas, waiting for the behavior that runs it. */
+export interface Defined<Name extends string, Input, Props, Model, State extends Tagged, Msg extends Tagged, R extends Requires> {
+    readonly build: <const B extends Behavior<Input, Props, Model, State, Msg, R, B>>(behavior: B) => ActorOf<Name, Input, Props, Model, State, Msg, KidsByState<State, B>, OpenOfBehavior<R, B>>;
+}
+/** A Schema Kabuki can read and write without Capabilities and at once. */
+type Codec<T> = Schema.Codec<T, unknown, never, never>;
+/**
+ * What `make` takes: every type the behavior is checked against, as codecs,
+ * and the Capabilities the Actor's own code may use. Every value is checked
+ * against them too, as it is made: each Input and Props, each Model and
+ * State from init or an Update, and each Message as it is Sent. A saved
+ * History holds the encoded side of the Props, Model, State and Message
+ * Schemas, so that side must be JSON-safe.
+ */
+export interface Shape<Input, Props, Model, State, Msg, R extends Requires> {
+    /** The Capabilities its own Workers, Commands and Provides use. Nothing else is in reach. */
+    readonly requires?: R;
+    /** What a parent hands this Actor when it Invokes it, which init starts from. */
+    readonly input?: Codec<Input>;
+    /** What a parent hands this Actor for as long as it lives, worked out again after each of the parent's Updates. */
+    readonly props?: Codec<Props>;
+    readonly model?: Codec<Model>;
+    readonly message?: Codec<Msg>;
+    readonly state?: Codec<State>;
+}
+declare function make<const Name extends string, State extends Tagged = Single, Model = {}, Msg extends Tagged = never, const R extends Requires = readonly [], Input = void, Props = void>(name: Name, shape: Shape<Input, Props, Model, State, Msg, R>): Defined<Name, Input, Props, Model, State, Msg, R>;
+/** A keyed Child slot: the parent Invokes one Instance of `actor` per key. */
+declare const many: <A extends AnyActor>(actor: A) => Many<A>;
+/**
+ * An Actor, in two steps. `make` takes its Schemas and Requires, which fixes
+ * every type. `build` takes how it behaves, at the top for as long as the
+ * Instance lives and in one block per State for as long as that State lasts:
+ * its Provides, Children, Invocation, Updates under `on`, and Workers.
+ */
+export declare const Actor: {
+    make: typeof make;
+    many: typeof many;
+};
+export {};
+//# sourceMappingURL=actor.d.ts.map

package/dist/core/actor/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/core/actor/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,IAAI,OAAO,EAChB,QAAQ,EACR,QAAQ,EAKR,WAAW,EACX,IAAI,EACJ,cAAc,EACd,QAAQ,EACR,MAAM,EAGN,MAAM,EAEP,MAAM,YAAY,CAAC;AACpB,OAAO,EAAU,MAAM,EAAa,MAAM,QAAQ,CAAC;AAEnD,iEAAiE;AACjE,MAAM,WAAW,OAAO,CACtB,IAAI,SAAS,MAAM,EACnB,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,SAAS,MAAM,EACpB,GAAG,SAAS,MAAM,EAClB,CAAC,SAAS,QAAQ;IAElB,QAAQ,CAAC,KAAK,EAAE,CACd,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAE/D,QAAQ,EAAE,CAAC,KACR,OAAO,CACV,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,GAAG,EACH,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,EACrB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CACrB,CAAC;CACH;AAED,2EAA2E;AAC3E,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,QAAQ;IACxE,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,mHAAmH;IACnH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;CAC/B;AAED,iBAAS,IAAI,CACX,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,GAAG,EAAE,EACV,GAAG,SAAS,MAAM,GAAG,KAAK,EAC1B,KAAK,CAAC,CAAC,SAAS,QAAQ,GAAG,SAAS,EAAE,EACtC,KAAK,GAAG,IAAI,EACZ,KAAK,GAAG,IAAI,EAEZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAmNrD,8EAA8E;AAC9E,QAAA,MAAM,IAAI,GAAI,CAAC,SAAS,QAAQ,SAAS,CAAC,KAAG,IAAI,CAAC,CAAC,CAGjD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;CAAiB,CAAC"}

package/dist/core/actor/actor.js

@@ -0,0 +1,168 @@
+import { Effect, Schema, SchemaAST } from 'effect';
+function make(name, shape) {
+    return {
+        build: (behavior) => ({
+            name,
+            definition: definitionOf(name, shape, behavior),
+        }),
+    };
+}
+/** The plain definition the engine works from, out of the Schemas and the levels. */
+const definitionOf = (name, shape, behavior) => {
+    const blocks = behavior.state ?? {};
+    const states = statesOf(shape.state, blocks);
+    const top = slots(behavior.children);
+    const lasting = Object.keys(top);
+    const children = {};
+    const invoke = {};
+    const update = {};
+    const stateProvides = {};
+    const workers = {};
+    const addWorkers = (from, state) => {
+        for (const [worker, written] of Object.entries(from.workers ?? {})) {
+            if (workers[worker])
+                throw new Error(`[@kestack/kabuki] ${name}: Worker "${worker}" is written twice`);
+            workers[worker] = workerOf(written, state);
+        }
+    };
+    if (behavior.on)
+        update['*'] = behavior.on;
+    addWorkers(behavior, undefined);
+    for (const tag of states) {
+        const block = blocks[tag] ?? {};
+        const own = slots(block.children);
+        for (const slot of Object.keys(own))
+            if (slot in top)
+                throw new Error(`[@kestack/kabuki] ${name}: Child "${slot}" is written at the top and in ${tag}`);
+        children[tag] = { ...top, ...own };
+        invoke[tag] = merged(behavior.invoke, block.invoke);
+        if (block.on)
+            update[tag] = block.on;
+        stateProvides[tag] = block.provides;
+        addWorkers(block, tag);
+    }
+    // TypeScript cannot see this: a rule that destructures its Message hides
+    // its whole `on` from inference. So it is checked once here, and warned.
+    for (const tag of tagsOf(shape.message))
+        if (!Object.values(update).some((rules) => tag in rules))
+            Effect.runSync(Effect.logWarning(`[@kestack/kabuki] ${name}: Message "${tag}" has no rule at the top or in any State, so it is always ignored`));
+    return {
+        name,
+        states,
+        requires: shape.requires ?? [],
+        check: {
+            input: checkerOf(name)(shape.input),
+            props: checkerOf(name)(shape.props),
+            model: checkerOf(name)(shape.model),
+            state: checkerOf(name)(shape.state),
+            message: checkerOf(name)(shape.message),
+        },
+        encoding: {
+            props: encodingOf(shape.props),
+            model: encodingOf(shape.model),
+            state: encodingOf(shape.state),
+            message: encodingOf(shape.message),
+        },
+        init: behavior.init ?? (() => ({})),
+        update,
+        workers,
+        provides: behavior.provides,
+        stateProvides,
+        children,
+        lasting,
+        invoke,
+    };
+};
+const slots = (children) => Object.fromEntries(Object.entries(children ?? {}).map(([slot, child]) => [
+    slot,
+    isMany(child)
+        ? { definition: child.actor.definition, many: true }
+        : { definition: child.definition, many: false },
+]));
+/** The top-level Invocation and a State's own, as one. */
+const merged = (top, own) => !top ? own : !own ? top : (data) => ({ ...top(data), ...own(data) });
+/**
+ * The State tags: a tagged union's cases, else every State a block is
+ * written for. An Actor without States has the one, `Single`.
+ */
+const statesOf = (schema, blocks) => {
+    if (!schema)
+        return ['Single'];
+    const cases = schema.cases;
+    return Object.keys(cases ?? blocks);
+};
+/** Throws, naming the Actor and what the value is, unless `schema` describes it. */
+const checkerOf = (name) => (schema) => {
+    if (!schema)
+        return () => { };
+    const decode = Schema.decodeUnknownSync(Schema.toType(schema));
+    return (value, what) => {
+        try {
+            decode(value);
+        }
+        catch (error) {
+            throw new TypeError(`[@kestack/kabuki] ${name}: ${what} does not match its Schema\n${error.message}`);
+        }
+    };
+};
+const AS_IS = { encode: (value) => value, decode: (value) => value };
+/** A value to its Schema's encoded side and back, for a saved History. */
+const encodingOf = (schema) => schema
+    ? {
+        encode: Schema.encodeUnknownSync(schema),
+        decode: Schema.decodeUnknownSync(schema),
+    }
+    : AS_IS;
+/** The tags a Message Schema names: one per tagged struct in its union. */
+const tagsOf = (schema) => {
+    if (!schema)
+        return [];
+    const { ast } = schema;
+    return (SchemaAST.isUnion(ast) ? ast.types : [ast]).flatMap((member) => SchemaAST.isObjects(member)
+        ? member.propertySignatures.flatMap(({ name, type }) => name === '_tag' && SchemaAST.isLiteral(type)
+            ? [String(type.literal)]
+            : [])
+        : []);
+};
+const ONE = [''];
+const NONE = [];
+/**
+ * A Worker's Condition as the keys it names: one, `''`, for every kind but
+ * `each`. Written in a State's block, it names none outside that State.
+ */
+const workerOf = (worker, state) => {
+    const { run } = worker;
+    const own = 'each' in worker
+        ? worker.each
+        : 'while' in worker
+            ? (data) => (worker.while(data) ? ONE : NONE)
+            : () => ONE;
+    const kind = 'each' in worker
+        ? 'each'
+        : 'while' in worker
+            ? 'while'
+            : state === undefined
+                ? 'instance'
+                : 'state';
+    if (state === undefined)
+        return { kind, keys: own, run };
+    return {
+        kind,
+        state,
+        keys: (data) => (data.state._tag === state ? own(data) : NONE),
+        run,
+    };
+};
+const isMany = (slot) => '_tag' in slot && slot._tag === 'Many';
+/** A keyed Child slot: the parent Invokes one Instance of `actor` per key. */
+const many = (actor) => ({
+    _tag: 'Many',
+    actor,
+});
+/**
+ * An Actor, in two steps. `make` takes its Schemas and Requires, which fixes
+ * every type. `build` takes how it behaves, at the top for as long as the
+ * Instance lives and in one block per State for as long as that State lasts:
+ * its Provides, Children, Invocation, Updates under `on`, and Workers.
+ */
+export const Actor = { make, many };

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

@@ -0,0 +1,24 @@
+import { Effect, Schema } from 'effect';
+import type { Command as Made } from './types.ts';
+/** A Schema Kabuki can read without Capabilities and at once. */
+type Codec<T> = Schema.Codec<T, unknown, never, never>;
+/**
+ * An errand an Update asks for. `make` takes its name, the Schema of its args
+ * and the Effect it runs from them, and gives what an Update calls with the
+ * args: `{ command: Search({ query }) }`.
+ */
+export declare const Command: {
+    make: {
+        <Args, Out, Ids = never>(name: string, options: {
+            readonly args: Codec<Args>;
+            readonly run: (args: Args) => Effect.Effect<Out, never, Ids>;
+        }): (args: Args) => Made<Out, Ids>;
+        <Out, Ids = never>(name: string, options: {
+            readonly args?: never;
+            readonly run: () => Effect.Effect<Out, never, Ids>;
+        }): () => Made<Out, Ids>;
+    };
+};
+export type Command<Out, Ids = never> = Made<Out, Ids>;
+export {};
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/core/actor/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,YAAY,CAAC;AAclD,iEAAiE;AACjE,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAiDvD;;;;GAIG;AACH,eAAO,MAAM,OAAO;;SApCjB,IAAI,EAAE,GAAG,EAAE,GAAG,gBACP,MAAM,WACH;YACP,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;SAC9D,GACA,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;SAChC,GAAG,EAAE,GAAG,gBACD,MAAM,WACH;YACP,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;YACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;SACpD,GACA,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;;CAuBM,CAAC;AAChC,MAAM,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC"}

package/dist/core/actor/command.js

@@ -0,0 +1,31 @@
+import { Effect, Schema } from 'effect';
+import { RUN } from './types.js';
+/** Throws, naming the Command, unless `schema` describes its args. */
+const checkerOf = (name, schema) => {
+    if (!schema)
+        return () => { };
+    const decode = Schema.decodeUnknownSync(Schema.toType(schema));
+    return (args) => {
+        try {
+            decode(args);
+        }
+        catch (error) {
+            throw new TypeError(`[@kestack/kabuki] Command ${name}: its args do not match their Schema\n${error.message}`);
+        }
+    };
+};
+const make = (name, options) => {
+    const check = checkerOf(name, options.args);
+    return (args) => Object.defineProperty({ name, args }, RUN, {
+        value: Effect.suspend(() => {
+            check(args);
+            return options.run(args);
+        }),
+    });
+};
+/**
+ * An errand an Update asks for. `make` takes its name, the Schema of its args
+ * and the Effect it runs from them, and gives what an Update calls with the
+ * args: `{ command: Search({ query }) }`.
+ */
+export const Command = { make };

package/dist/core/actor/index.d.ts

@@ -0,0 +1,6 @@
+export { Actor } from './actor.ts';
+export { Command } from './command.ts';
+export { RUN } from './types.ts';
+export type { Defined } from './actor.ts';
+export type { ActorOf, AnyActor, Data, ActorDefinition, Encoding, Many, Only, Self, SlotDefinition, Tagged, Types, Worker, WorkerDefinition, Workers, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/actor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/actor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,cAAc,EACd,MAAM,EACN,KAAK,EACL,MAAM,EACN,gBAAgB,EAChB,OAAO,GACR,MAAM,YAAY,CAAC"}

package/dist/core/actor/index.js

@@ -0,0 +1,3 @@
+export { Actor } from './actor.js';
+export { Command } from './command.js';
+export { RUN } from './types.js';