effect-machine 0.3.0 → 0.3.2

package/src/schema.ts

@@ -1,362 +0,0 @@
-/**
- * Schema-first State/Event definitions for effect-machine.
- *
- * MachineSchema provides a single source of truth that combines:
- * - Schema for validation/serialization
- * - Variant constructors (like Data.taggedEnum)
- * - $is and $match helpers for pattern matching
- * - Brand integration for compile-time safety
- *
- * @example
- * ```ts
- * import { State, Event, Machine } from "effect-machine"
- *
- * // Define schema-first state
- * const OrderState = State({
- *   Pending: { orderId: Schema.String },
- *   Shipped: { trackingId: Schema.String },
- * })
- *
- * // Infer type from schema
- * type OrderState = typeof OrderState.Type
- *
- * // Use constructors
- * const pending = OrderState.Pending({ orderId: "123" })
- *
- * // Pattern match
- * OrderState.$match(state, {
- *   Pending: (s) => `Order ${s.orderId} pending`,
- *   Shipped: (s) => `Shipped: ${s.trackingId}`,
- * })
- *
- * // Use as Schema for persistence/cluster
- * machine.pipe(Machine.persist({ stateSchema: OrderState, ... }))
- * ```
- *
- * @module
- */
-import { Schema } from "effect";
-import type { FullStateBrand, FullEventBrand } from "./internal/brands.js";
-import { InvalidSchemaError, MissingMatchHandlerError } from "./errors.js";
-
-// ============================================================================
-// Type Helpers
-// ============================================================================
-
-/**
- * Extract the TypeScript type from a TaggedStruct schema
- */
-type TaggedStructType<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Schema.Type<
-  Schema.TaggedStruct<Tag, Fields>
->;
-
-/**
- * Build variant schemas type from definition
- */
-type VariantSchemas<D extends Record<string, Schema.Struct.Fields>> = {
-  readonly [K in keyof D & string]: Schema.TaggedStruct<K, D[K]>;
-};
-
-/**
- * Build union type from variant schemas.
- * Used for constraining fluent method type params.
- */
-export type VariantsUnion<D extends Record<string, Schema.Struct.Fields>> = {
-  [K in keyof D & string]: TaggedStructType<K, D[K]>;
-}[keyof D & string];
-
-/**
- * Check if fields are empty (no required properties)
- */
-type IsEmptyFields<Fields extends Schema.Struct.Fields> = keyof Fields extends never ? true : false;
-
-/**
- * Constructor functions for each variant.
- * Empty structs: plain values with `_tag`: `State.Idle`
- * Non-empty structs require args: `State.Loading({ url })`
- *
- * Each variant also has a `derive` method for constructing from a source object.
- */
-/**
- * Constructor functions for each variant.
- * Empty structs: plain values with `_tag`: `State.Idle`
- * Non-empty structs require args: `State.Loading({ url })`
- *
- * Each variant also has a `derive` method for constructing from a source object.
- * The source type uses `object` to accept branded state types without index signature issues.
- */
-type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = {
-  readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true
-    ? TaggedStructType<K, D[K]> &
-        Brand & {
-          readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
-        }
-    : ((args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand) & {
-        readonly derive: (
-          source: object,
-          partial?: Partial<Schema.Struct.Constructor<D[K]>>,
-        ) => TaggedStructType<K, D[K]> & Brand;
-        readonly _tag: K;
-      };
-};
-
-/**
- * Pattern matching cases type
- */
-type MatchCases<D extends Record<string, Schema.Struct.Fields>, R> = {
-  readonly [K in keyof D & string]: (value: TaggedStructType<K, D[K]>) => R;
-};
-
-/**
- * Base schema interface with pattern matching helpers
- */
-interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Brand> {
-  /**
-   * Raw definition record for introspection
-   */
-  readonly _definition: D;
-
-  /**
-   * Per-variant schemas for fine-grained operations
-   */
-  readonly variants: VariantSchemas<D>;
-
-  /**
-   * Type guard: `OrderState.$is("Pending")(value)`
-   */
-  readonly $is: <Tag extends keyof D & string>(
-    tag: Tag,
-  ) => (u: unknown) => u is TaggedStructType<Tag, D[Tag]> & Brand;
-
-  /**
-   * Pattern matching (curried and uncurried)
-   */
-  readonly $match: {
-    // Curried: $match(cases)(value)
-    <R>(cases: MatchCases<D, R>): (value: VariantsUnion<D> & Brand) => R;
-    // Uncurried: $match(value, cases)
-    <R>(value: VariantsUnion<D> & Brand, cases: MatchCases<D, R>): R;
-  };
-}
-
-// ============================================================================
-// MachineStateSchema Type
-// ============================================================================
-
-/**
- * Schema-first state definition that provides:
- * - Schema for encode/decode/validate
- * - Variant constructors: `OrderState.Pending({ orderId: "x" })`
- * - Pattern matching: `$is`, `$match`
- * - Type inference: `typeof OrderState.Type`
- *
- * The D type parameter captures the definition, creating a unique brand
- * per distinct schema definition shape.
- */
-export type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<
-  VariantsUnion<D> & FullStateBrand<D>,
-  VariantsUnion<D>,
-  never
-> &
-  MachineSchemaBase<D, FullStateBrand<D>> &
-  VariantConstructors<D, FullStateBrand<D>>;
-
-/**
- * Schema-first event definition (same structure as state, different brand)
- *
- * The D type parameter captures the definition, creating a unique brand
- * per distinct schema definition shape.
- */
-export type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<
-  VariantsUnion<D> & FullEventBrand<D>,
-  VariantsUnion<D>,
-  never
-> &
-  MachineSchemaBase<D, FullEventBrand<D>> &
-  VariantConstructors<D, FullEventBrand<D>>;
-
-// ============================================================================
-// Implementation
-// ============================================================================
-
-/**
- * Build a schema-first definition from a record of tag -> fields
- */
-const buildMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(
-  definition: D,
-): {
-  schema: Schema.Schema<VariantsUnion<D>, VariantsUnion<D>, never>;
-  variants: VariantSchemas<D>;
-  constructors: Record<string, (args: Record<string, unknown>) => Record<string, unknown>>;
-  _definition: D;
-  $is: <Tag extends string>(tag: Tag) => (u: unknown) => boolean;
-  $match: (valueOrCases: unknown, maybeCases?: unknown) => unknown;
-} => {
-  // Build variant schemas
-  const variants = {} as Record<string, Schema.TaggedStruct<string, Schema.Struct.Fields>>;
-  const constructors = {} as Record<
-    string,
-    (args: Record<string, unknown>) => Record<string, unknown>
-  >;
-
-  for (const tag of Object.keys(definition)) {
-    const fields = definition[tag];
-    if (fields === undefined) continue;
-
-    const variantSchema = Schema.TaggedStruct(tag, fields);
-    variants[tag] = variantSchema;
-
-    // Create constructor that builds tagged struct directly
-    // Like Data.taggedEnum, this doesn't validate at construction time
-    // Use Schema.decode for validation when needed
-    const fieldNames = new Set(Object.keys(fields));
-    const hasFields = fieldNames.size > 0;
-
-    if (hasFields) {
-      // Non-empty: constructor function requiring args
-      const constructor = (args: Record<string, unknown>) => ({ ...args, _tag: tag });
-      constructor._tag = tag;
-      constructor.derive = (source: Record<string, unknown>, partial?: Record<string, unknown>) => {
-        const result: Record<string, unknown> = { _tag: tag };
-        for (const key of fieldNames) {
-          if (key in source) result[key] = source[key];
-        }
-        if (partial !== undefined) {
-          for (const [key, value] of Object.entries(partial)) {
-            result[key] = value;
-          }
-        }
-        return result;
-      };
-      constructors[tag] = constructor;
-    } else {
-      // Empty: plain value, not callable
-      constructors[tag] = { _tag: tag, derive: () => ({ _tag: tag }) } as never;
-    }
-  }
-
-  // Build union schema from all variants
-  const variantArray = Object.values(variants);
-  if (variantArray.length === 0) {
-    throw new InvalidSchemaError();
-  }
-
-  // Schema.Union requires at least 2 members, handle single variant case
-  const unionSchema =
-    variantArray.length === 1
-      ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- checked length above
-        variantArray[0]!
-      : // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic schema union
-        Schema.Union(...(variantArray as [any, any, ...any[]]));
-
-  // Type guard
-  const $is =
-    <Tag extends string>(tag: Tag) =>
-    (u: unknown): boolean =>
-      typeof u === "object" && u !== null && "_tag" in u && (u as { _tag: string })._tag === tag;
-
-  // Pattern matching
-  const $match = (valueOrCases: unknown, maybeCases?: unknown): unknown => {
-    if (maybeCases !== undefined) {
-      // Uncurried: $match(value, cases)
-      const value = valueOrCases as { _tag: string };
-      const cases = maybeCases as Record<string, (v: unknown) => unknown>;
-      const handler = cases[value._tag];
-      if (handler === undefined) {
-        throw new MissingMatchHandlerError({ tag: value._tag });
-      }
-      return handler(value);
-    }
-    // Curried: $match(cases) -> (value) => result
-    const cases = valueOrCases as Record<string, (v: unknown) => unknown>;
-    return (value: { _tag: string }): unknown => {
-      const handler = cases[value._tag];
-      if (handler === undefined) {
-        throw new MissingMatchHandlerError({ tag: value._tag });
-      }
-      return handler(value);
-    };
-  };
-
-  return {
-    schema: unionSchema as unknown as Schema.Schema<VariantsUnion<D>, VariantsUnion<D>, never>,
-    variants: variants as unknown as VariantSchemas<D>,
-    constructors,
-    _definition: definition,
-    $is,
-    $match,
-  };
-};
-
-/**
- * Internal helper to create a machine schema (shared by State and Event).
- * Builds the schema object with variants, constructors, $is, and $match.
- */
-const createMachineSchema = <D extends Record<string, Schema.Struct.Fields>>(definition: D) => {
-  const { schema, variants, constructors, _definition, $is, $match } =
-    buildMachineSchema(definition);
-  return Object.assign(Object.create(schema), {
-    variants,
-    _definition,
-    $is,
-    $match,
-    ...constructors,
-  });
-};
-
-/**
- * Create a schema-first State definition.
- *
- * The schema's definition type D creates a unique brand, preventing
- * accidental use of constructors from different state schemas
- * (unless they have identical definitions).
- *
- * @example
- * ```ts
- * const OrderState = MachineSchema.State({
- *   Pending: { orderId: Schema.String },
- *   Shipped: { trackingId: Schema.String },
- * })
- *
- * type OrderState = typeof OrderState.Type
- *
- * // Construct
- * const s = OrderState.Pending({ orderId: "123" })
- *
- * // Pattern match
- * OrderState.$match(s, {
- *   Pending: (v) => v.orderId,
- *   Shipped: (v) => v.trackingId,
- * })
- *
- * // Validate
- * Schema.decodeUnknownSync(OrderState)(rawJson)
- * ```
- */
-export const State = <const D extends Record<string, Schema.Struct.Fields>>(
-  definition: D,
-): MachineStateSchema<D> => createMachineSchema(definition) as MachineStateSchema<D>;
-
-/**
- * Create a schema-first Event definition.
- *
- * The schema's definition type D creates a unique brand, preventing
- * accidental use of constructors from different event schemas
- * (unless they have identical definitions).
- *
- * @example
- * ```ts
- * const OrderEvent = MachineSchema.Event({
- *   Ship: { trackingId: Schema.String },
- *   Cancel: {},
- * })
- *
- * type OrderEvent = typeof OrderEvent.Type
- *
- * // Construct
- * const e = OrderEvent.Ship({ trackingId: "abc" })
- * ```
- */
-export const Event = <const D extends Record<string, Schema.Struct.Fields>>(
-  definition: D,
-): MachineEventSchema<D> => createMachineSchema(definition) as MachineEventSchema<D>;

package/src/slot.ts

@@ -1,281 +0,0 @@
-/**
- * Slot module - schema-based, parameterized guards and effects.
- *
- * Guards and Effects are defined with schemas for their parameters,
- * and provided implementations receive typed parameters plus machine context.
- *
- * @example
- * ```ts
- * import { Slot } from "effect-machine"
- * import { Schema } from "effect"
- *
- * const MyGuards = Slot.Guards({
- *   canRetry: { max: Schema.Number },
- *   isValid: {},  // no params
- * })
- *
- * const MyEffects = Slot.Effects({
- *   fetchData: { url: Schema.String },
- *   notify: { message: Schema.String },
- * })
- *
- * // Used in handlers:
- * .on(State.X, Event.Y, ({ guards, effects }) =>
- *   Effect.gen(function* () {
- *     if (yield* guards.canRetry({ max: 3 })) {
- *       yield* effects.fetchData({ url: "/api" })
- *       return State.Next
- *     }
- *     return state
- *   })
- * )
- * ```
- *
- * @module
- */
-import { Context } from "effect";
-import type { Effect, Schema } from "effect";
-
-// ============================================================================
-// Type-level utilities
-// ============================================================================
-
-/** Schema fields definition (like Schema.Struct.Fields) */
-type Fields = Record<string, Schema.Schema.All>;
-
-/** Extract the encoded type from schema fields (used for parameters) */
-type FieldsToParams<F extends Fields> = keyof F extends never
-  ? void
-  : Schema.Schema.Type<Schema.Struct<F>>;
-
-// ============================================================================
-// Slot Types
-// ============================================================================
-
-/**
- * A guard slot - callable function that returns Effect<boolean>.
- */
-export interface GuardSlot<Name extends string, Params> {
-  readonly _tag: "GuardSlot";
-  readonly name: Name;
-  (params: Params): Effect.Effect<boolean>;
-}
-
-/**
- * An effect slot - callable function that returns Effect<void>.
- */
-export interface EffectSlot<Name extends string, Params> {
-  readonly _tag: "EffectSlot";
-  readonly name: Name;
-  (params: Params): Effect.Effect<void>;
-}
-
-/**
- * Guard definition - name to schema fields mapping
- */
-export type GuardsDef = Record<string, Fields>;
-
-/**
- * Effect definition - name to schema fields mapping
- */
-export type EffectsDef = Record<string, Fields>;
-
-/**
- * Convert guard definitions to callable guard slots
- */
-export type GuardSlots<D extends GuardsDef> = {
-  readonly [K in keyof D & string]: GuardSlot<K, FieldsToParams<D[K]>>;
-};
-
-/**
- * Convert effect definitions to callable effect slots
- */
-export type EffectSlots<D extends EffectsDef> = {
-  readonly [K in keyof D & string]: EffectSlot<K, FieldsToParams<D[K]>>;
-};
-
-// ============================================================================
-// Machine Context Tag
-// ============================================================================
-
-/**
- * Type for machine context - state, event, and self reference.
- * Shared across all machines via MachineContextTag.
- */
-export interface MachineContext<State, Event, Self> {
-  readonly state: State;
-  readonly event: Event;
-  readonly self: Self;
-}
-
-/**
- * Shared Context tag for all machines.
- * Single module-level tag instead of per-machine allocation.
- * @internal
- */
-/* eslint-disable @typescript-eslint/no-explicit-any -- generic context tag */
-export const MachineContextTag =
-  Context.GenericTag<MachineContext<any, any, any>>("@effect-machine/Context");
-/* eslint-enable @typescript-eslint/no-explicit-any */
-
-// ============================================================================
-// Handler Types (for provide)
-// ============================================================================
-
-/**
- * Guard handler implementation.
- * Receives params and context, returns Effect<boolean>.
- */
-export type GuardHandler<Params, Ctx, R = never> = (
-  params: Params,
-  ctx: Ctx,
-) => boolean | Effect.Effect<boolean, never, R>;
-
-/**
- * Effect handler implementation.
- * Receives params and context, returns Effect<void>.
- */
-export type EffectHandler<Params, Ctx, R = never> = (
-  params: Params,
-  ctx: Ctx,
-) => Effect.Effect<void, never, R>;
-
-/**
- * Handler types for all guards in a definition
- */
-export type GuardHandlers<D extends GuardsDef, MachineCtx, R = never> = {
-  readonly [K in keyof D & string]: GuardHandler<FieldsToParams<D[K]>, MachineCtx, R>;
-};
-
-/**
- * Handler types for all effects in a definition
- */
-export type EffectHandlers<D extends EffectsDef, MachineCtx, R = never> = {
-  readonly [K in keyof D & string]: EffectHandler<FieldsToParams<D[K]>, MachineCtx, R>;
-};
-
-// ============================================================================
-// Schema Types (for Machine.make)
-// ============================================================================
-
-/**
- * Guards schema - returned by Slot.Guards()
- */
-export interface GuardsSchema<D extends GuardsDef> {
-  readonly _tag: "GuardsSchema";
-  readonly definitions: D;
-  /** Create callable guard slots (used by Machine internally) */
-  readonly _createSlots: (
-    resolve: <N extends keyof D & string>(
-      name: N,
-      params: FieldsToParams<D[N]>,
-    ) => Effect.Effect<boolean>,
-  ) => GuardSlots<D>;
-}
-
-/**
- * Effects schema - returned by Slot.Effects()
- */
-export interface EffectsSchema<D extends EffectsDef> {
-  readonly _tag: "EffectsSchema";
-  readonly definitions: D;
-  /** Create callable effect slots (used by Machine internally) */
-  readonly _createSlots: (
-    resolve: <N extends keyof D & string>(
-      name: N,
-      params: FieldsToParams<D[N]>,
-    ) => Effect.Effect<void>,
-  ) => EffectSlots<D>;
-}
-
-// ============================================================================
-// Slot Factories
-// ============================================================================
-
-/**
- * Generic slot schema factory. Used internally by Guards() and Effects().
- * @internal
- */
-const createSlotSchema = <
-  Tag extends "GuardsSchema" | "EffectsSchema",
-  D extends Record<string, Fields>,
->(
-  tag: Tag,
-  slotTag: "GuardSlot" | "EffectSlot",
-  definitions: D,
-): {
-  readonly _tag: Tag;
-  readonly definitions: D;
-  readonly _createSlots: (
-    resolve: <N extends keyof D & string>(
-      name: N,
-      params: FieldsToParams<D[N]>,
-    ) => Effect.Effect<unknown>,
-  ) => Record<string, unknown>;
-} => ({
-  _tag: tag,
-  definitions,
-  _createSlots: (resolve) => {
-    const slots: Record<string, unknown> = {};
-    for (const name of Object.keys(definitions)) {
-      const slot = (params: unknown) => resolve(name, params as FieldsToParams<D[typeof name]>);
-      Object.defineProperty(slot, "_tag", { value: slotTag, enumerable: true });
-      Object.defineProperty(slot, "name", { value: name, enumerable: true });
-      slots[name] = slot;
-    }
-    return slots;
-  },
-});
-
-/**
- * Create a guards schema with parameterized guard definitions.
- *
- * @example
- * ```ts
- * const MyGuards = Slot.Guards({
- *   canRetry: { max: Schema.Number },
- *   isValid: {},
- * })
- * ```
- */
-export const Guards = <D extends GuardsDef>(definitions: D): GuardsSchema<D> =>
-  createSlotSchema("GuardsSchema", "GuardSlot", definitions) as GuardsSchema<D>;
-
-/**
- * Create an effects schema with parameterized effect definitions.
- *
- * @example
- * ```ts
- * const MyEffects = Slot.Effects({
- *   fetchData: { url: Schema.String },
- *   notify: { message: Schema.String },
- * })
- * ```
- */
-export const Effects = <D extends EffectsDef>(definitions: D): EffectsSchema<D> =>
-  createSlotSchema("EffectsSchema", "EffectSlot", definitions) as EffectsSchema<D>;
-
-// ============================================================================
-// Type extraction helpers
-// ============================================================================
-
-/** Extract guard definition type from GuardsSchema */
-export type GuardsDefOf<G> = G extends GuardsSchema<infer D> ? D : never;
-
-/** Extract effect definition type from EffectsSchema */
-export type EffectsDefOf<E> = E extends EffectsSchema<infer D> ? D : never;
-
-/** Extract guard slots type from GuardsSchema */
-export type GuardSlotsOf<G> = G extends GuardsSchema<infer D> ? GuardSlots<D> : never;
-
-/** Extract effect slots type from EffectsSchema */
-export type EffectSlotsOf<E> = E extends EffectsSchema<infer D> ? EffectSlots<D> : never;
-
-// ============================================================================
-// Slot namespace export
-// ============================================================================
-
-export const Slot = {
-  Guards,
-  Effects,
-} as const;