@typeonce/effect-machine 0.8.0 → 0.10.0

package/src/internal/machine/protocol.ts

@@ -9,12 +9,13 @@ import * as Effect from "effect/Effect"
 import { hasProperty } from "effect/Predicate"
 import * as Result from "effect/Result"
 import * as Schema from "effect/Schema"
+import * as SchemaAST from "effect/SchemaAST"
 import type { Machine } from "../../Machine.js"
 import { MachineSchemaDecodeError } from "./errors.js"
 import { getStateNodeSchema, isStateInput } from "./topology.js"
 
 export interface DecodeBoundaryOptions {
-  readonly boundary: "input" | "event" | "emit" | "state" | "output" | "history" | "configuration"
+  readonly boundary: "input" | "event" | "emission" | "state" | "output" | "history" | "configuration"
   readonly state?: string
   readonly event?: string
 }
@@ -24,8 +25,33 @@ interface MachineProtocolSchemas {
   readonly emit: Schema.Top
   readonly eventConstructors: ReadonlySet<object>
   readonly trustedEvents: WeakSet<object>
+  readonly emissionConstructors: ReadonlySet<object>
+  readonly trustedEmissions: WeakSet<object>
 }
 
+interface EventProtocolDefinition {
+  readonly kind: Machine.EventProtocolKind
+  readonly schemas: ReadonlyArray<Machine.TaggedSchema>
+}
+
+const eventProtocolDefinitions = new WeakMap<object, EventProtocolDefinition>()
+
+export const EventConstructionTypeId: unique symbol = Symbol("effect/Machine/EventConstruction")
+
+interface EventConstruction {
+  readonly [EventConstructionTypeId]: typeof EventConstructionTypeId
+  readonly _tag: PropertyKey
+}
+
+interface EventConstructionDefinition {
+  readonly kind: Machine.EventProtocolKind
+  readonly schema: Machine.TaggedSchema
+  readonly input: unknown
+  readonly inputError?: unknown
+}
+
+const eventConstructionDefinitions = new WeakMap<object, EventConstructionDefinition>()
+
 type BoundaryDecoder = (value: unknown) => Effect.Effect<unknown, Schema.SchemaError, unknown>
 
 type BoundaryResultDecoder = (value: unknown) => Result.Result<unknown, Schema.SchemaError>
@@ -95,13 +121,59 @@ const collectEventConstructors = (
   return constructors
 }
 
+const getEventProtocolDefinition = (
+  protocol: Machine.EventProtocol.Any,
+  expectedKind?: Machine.EventProtocolKind
+): EventProtocolDefinition => {
+  const definition = eventProtocolDefinitions.get(protocol as object)
+  if (definition === undefined) {
+    throw new Error(
+      "Machine expected an event protocol created with Machine.events, Machine.internalEvents, or Machine.emittedEvents"
+    )
+  }
+  if (expectedKind !== undefined && definition.kind !== expectedKind) {
+    throw new Error(`Machine expected a ${expectedKind} event protocol`)
+  }
+  return definition
+}
+
+export const isEventProtocol = <Kind extends Machine.EventProtocolKind>(
+  value: unknown,
+  kind: Kind
+): value is Machine.EventProtocol.Any<Kind> =>
+  typeof value === "object" && value !== null && eventProtocolDefinitions.get(value)?.kind === kind
+
+export const eventProtocolSchemas = <Schemas extends ReadonlyArray<Machine.TaggedSchema>>(
+  protocol: Machine.EventProtocol<Machine.EventProtocolKind, Schemas>
+): Schemas => getEventProtocolDefinition(protocol).schemas as Schemas
+
+export const inputEventSchemas = (machine: Machine.Any): ReadonlyArray<Machine.TaggedSchema> =>
+  getEventProtocolDefinition(machine.events, "public").schemas
+
+export const internalEventSchemas = (machine: Machine.Any): ReadonlyArray<Machine.TaggedSchema> =>
+  getEventProtocolDefinition(machine.internalEvents, "internal").schemas
+
+export const emittedEventSchemas = (machine: Machine.Any): ReadonlyArray<Machine.TaggedSchema> =>
+  getEventProtocolDefinition(machine.emittedEvents, "emitted").schemas
+
 export const setProtocol = (machine: Machine.Any): void => {
-  const events = [...machine.events, ...machine.internalEvents]
+  const inputEvents = inputEventSchemas(machine)
+  const localEvents = internalEventSchemas(machine)
+  const emittedEvents = emittedEventSchemas(machine)
+  const publicTags = new Set(Reflect.ownKeys(machine.events))
+  for (const tag of Reflect.ownKeys(machine.internalEvents)) {
+    if (publicTags.has(tag)) {
+      throw new Error(`Public and internal machine event tags must be disjoint: ${String(tag)}`)
+    }
+  }
+  const events = [...inputEvents, ...localEvents]
   setProtocolSchemas(machine, {
     event: Schema.Union(events),
-    emit: Schema.Union(machine.emits),
+    emit: Schema.Union(emittedEvents),
     eventConstructors: collectEventConstructors(events),
-    trustedEvents: new WeakSet()
+    trustedEvents: new WeakSet(),
+    emissionConstructors: collectEventConstructors(emittedEvents),
+    trustedEmissions: new WeakSet()
   })
 }
 
@@ -111,6 +183,116 @@ export const copyProtocol = (source: Machine.Any, target: Machine.Any): void =>
 export const getEventName = (event: unknown): string | undefined =>
   hasProperty(event, "_tag") ? String(event._tag) : undefined
 
+const makeEventConstruction = (
+  kind: Machine.EventProtocolKind,
+  schema: Machine.TaggedSchema,
+  tag: PropertyKey,
+  input: unknown
+): EventConstruction => {
+  let ownedInput = input
+  let inputError: unknown
+  if (typeof input === "object" && input !== null) {
+    try {
+      ownedInput = { ...input }
+    } catch (cause) {
+      ownedInput = undefined
+      inputError = cause
+    }
+  }
+  const construction: EventConstruction = {
+    [EventConstructionTypeId]: EventConstructionTypeId,
+    _tag: tag
+  }
+  eventConstructionDefinitions.set(construction, {
+    kind,
+    schema,
+    input: ownedInput,
+    ...(inputError === undefined ? {} : { inputError })
+  })
+  return Object.freeze(construction)
+}
+
+const isEventConstruction = (value: unknown): value is EventConstruction =>
+  typeof value === "object" && value !== null && eventConstructionDefinitions.has(value)
+
+const eventConstructors = (
+  kind: Machine.EventProtocolKind,
+  schemas: ReadonlyArray<Machine.TaggedSchema>
+): Readonly<Record<PropertyKey, (...args: ReadonlyArray<unknown>) => EventConstruction>> => {
+  const leaves: Array<Machine.TaggedSchema> = []
+  const collect = (schema: Machine.TaggedSchema): void => {
+    if (hasProperty(schema, "cases") && typeof schema.cases === "object" && schema.cases !== null) {
+      for (const candidate of Reflect.ownKeys(schema.cases)) {
+        collect(Reflect.get(schema.cases, candidate) as Machine.TaggedSchema)
+      }
+      return
+    }
+    if (hasProperty(schema, "members") && Array.isArray(schema.members)) {
+      for (const member of schema.members) collect(member as Machine.TaggedSchema)
+      return
+    }
+    leaves.push(schema)
+  }
+  for (const schema of schemas) collect(schema)
+  const constructors = Object.create(null) as Record<
+    PropertyKey,
+    (...args: ReadonlyArray<unknown>) => EventConstruction
+  >
+  const tags = (ast: SchemaAST.AST): ReadonlyArray<PropertyKey> => {
+    if (SchemaAST.isLiteral(ast)) {
+      return typeof ast.literal === "string" || typeof ast.literal === "number" ? [ast.literal] : []
+    }
+    if (SchemaAST.isUniqueSymbol(ast)) return [ast.symbol]
+    if (SchemaAST.isEnum(ast)) return ast.enums.map(([, value]) => value)
+    if (SchemaAST.isUnion(ast)) return ast.types.flatMap(tags)
+    if (SchemaAST.isSuspend(ast)) return tags(ast.thunk())
+    return []
+  }
+  const schemaTags = (schema: Machine.TaggedSchema): ReadonlyArray<PropertyKey> => {
+    const ast = SchemaAST.toType(schema.ast)
+    if (SchemaAST.isObjects(ast)) {
+      const tag = ast.propertySignatures.find(({ name }) => name === "_tag")
+      const discriminants = tag === undefined ? [] : tags(tag.type)
+      if (discriminants.length > 0) return discriminants
+    }
+    try {
+      return Schema.Union([schema]).pipe(Schema.toTaggedUnion("_tag")).discriminants
+    } catch {
+      return []
+    }
+  }
+  for (const schema of leaves) {
+    const discriminants = schemaTags(schema)
+    if (discriminants.length === 0) {
+      continue
+    }
+    for (const tag of discriminants) {
+      if (hasProperty(constructors, tag)) {
+        throw new Error(`Duplicate machine event constructor tag: ${String(tag)}`)
+      }
+      Object.defineProperty(constructors, tag, {
+        value: (...args: ReadonlyArray<unknown>) =>
+          makeEventConstruction(kind, schema, tag, args.length === 0 ? {} : args[0]),
+        enumerable: true
+      })
+    }
+  }
+  return constructors
+}
+
+export const makeEventProtocol = <
+  Kind extends Machine.EventProtocolKind,
+  Schemas extends ReadonlyArray<Machine.TaggedSchema>
+>(
+  kind: Kind,
+  schemas: Schemas
+): Machine.EventProtocol<Kind, Schemas> => {
+  const ownedSchemas = Object.freeze(Array.from(schemas)) as unknown as Schemas
+  const protocol = eventConstructors(kind, ownedSchemas) as Machine.EventProtocol<Kind, Schemas>
+  eventProtocolDefinitions.set(protocol as object, { kind, schemas: ownedSchemas })
+  return Object.freeze(protocol) as Machine.EventProtocol<Kind, Schemas>
+}
+
 export const decodeBoundary = <A>(
   machine: Machine.Any,
   schema: Schema.Top,
@@ -172,26 +354,106 @@ const makeBoundarySync = <A>(
   }
 }
 
-/** Constructs an event through one of the machine protocol's own schemas and
- * records the decoded value as trusted by that protocol. Machine clones share
- * the protocol record, while unrelated machines retain independent trust. */
-export const makeEvent = <Schema extends Machine.TaggedSchema>(
+const eventConstructionProtocolError = (
   machine: Machine.Any,
-  schema: Schema,
-  input: unknown
-): Schema["Type"] => {
-  const protocol = getProtocolSchemas(machine)
-  if (!protocol.eventConstructors.has(schema as object)) {
-    throw new Error("Machine.event expected a schema from the machine event protocol")
+  construction: EventConstruction,
+  boundary: "event" | "emission"
+): MachineSchemaDecodeError =>
+  new MachineSchemaDecodeError({
+    machineId: machine.id,
+    boundary,
+    event: String(construction._tag),
+    cause: Cause.die(new Error(`Constructed ${boundary} schema does not belong to the machine ${boundary} protocol`))
+  })
+
+const eventConstructionInput = (
+  construction: EventConstruction,
+  definition: EventConstructionDefinition
+): unknown => {
+  if (definition.inputError !== undefined) throw definition.inputError
+  return typeof definition.input === "object" && definition.input !== null
+    ? { ...definition.input, _tag: construction._tag }
+    : { _tag: construction._tag }
+}
+
+const eventConstructionInputError = (
+  machine: Machine.Any,
+  construction: EventConstruction,
+  boundary: "event" | "emission",
+  cause: unknown
+): MachineSchemaDecodeError =>
+  new MachineSchemaDecodeError({
+    machineId: machine.id,
+    boundary,
+    event: String(construction._tag),
+    cause: Cause.die(cause)
+  })
+
+const decodeEventConstruction = (
+  machine: Machine.Any,
+  protocol: MachineProtocolSchemas,
+  construction: EventConstruction,
+  boundary: "event" | "emission"
+): Effect.Effect<unknown, MachineSchemaDecodeError> => {
+  const definition = eventConstructionDefinitions.get(construction)
+  const constructors = boundary === "event" ? protocol.eventConstructors : protocol.emissionConstructors
+  if (
+    definition === undefined ||
+    (boundary === "emission" ? definition.kind !== "emitted" : definition.kind === "emitted") ||
+    !constructors.has(definition.schema as object)
+  ) {
+    return Effect.fail(eventConstructionProtocolError(machine, construction, boundary))
   }
-  const inputName = getEventName(input)
-  const event = makeBoundarySync<Schema["Type"]>(
-    machine,
-    schema,
-    input,
-    inputName === undefined ? { boundary: "event" } : { boundary: "event", event: inputName }
+  return Effect.try({
+    try: () => eventConstructionInput(construction, definition),
+    catch: (cause) => eventConstructionInputError(machine, construction, boundary, cause)
+  }).pipe(
+    Effect.flatMap((input) =>
+      definition.schema.makeEffect(input as never).pipe(
+        Effect.mapError((cause) =>
+          new MachineSchemaDecodeError({
+            machineId: machine.id,
+            boundary,
+            event: String(construction._tag),
+            cause: new Schema.SchemaError(cause)
+          })
+        )
+      )
+    ),
+    Effect.tap((event) =>
+      Effect.sync(() =>
+        (boundary === "event" ? protocol.trustedEvents : protocol.trustedEmissions).add(event as object)
+      )
+    )
   )
-  protocol.trustedEvents.add(event as object)
+}
+
+const decodeEventConstructionSync = (
+  machine: Machine.Any,
+  protocol: MachineProtocolSchemas,
+  construction: EventConstruction,
+  boundary: "event" | "emission"
+): unknown => {
+  const definition = eventConstructionDefinitions.get(construction)
+  const constructors = boundary === "event" ? protocol.eventConstructors : protocol.emissionConstructors
+  if (
+    definition === undefined ||
+    (boundary === "emission" ? definition.kind !== "emitted" : definition.kind === "emitted") ||
+    !constructors.has(definition.schema as object)
+  ) {
+    throw eventConstructionProtocolError(machine, construction, boundary)
+  }
+  let input: unknown
+  try {
+    input = eventConstructionInput(construction, definition)
+  } catch (cause) {
+    throw eventConstructionInputError(machine, construction, boundary, cause)
+  }
+  const event = makeBoundarySync(machine, definition.schema, input, {
+    boundary,
+    event: String(construction._tag)
+  })
+  ;(boundary === "event" ? protocol.trustedEvents : protocol.trustedEmissions).add(event as object)
   return event
 }
 
@@ -210,6 +472,12 @@ export const decodeEvent = <const Events extends ReadonlyArray<Machine.TaggedSch
   event: unknown
 ): Effect.Effect<Machine.EventOf<Events>, MachineSchemaDecodeError> => {
   const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstruction(machine, protocol, event, "event") as Effect.Effect<
+      Machine.EventOf<Events>,
+      MachineSchemaDecodeError
+    >
+  }
   if (isTrustedEvent(protocol, event)) {
     return Effect.succeed(event as Machine.EventOf<Events>)
   }
@@ -227,6 +495,9 @@ export const decodeEventSync = <const Events extends ReadonlyArray<Machine.Tagge
   event: unknown
 ): Machine.EventOf<Events> => {
   const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstructionSync(machine, protocol, event, "event") as Machine.EventOf<Events>
+  }
   if (isTrustedEvent(protocol, event)) {
     return event as Machine.EventOf<Events>
   }
@@ -243,12 +514,22 @@ export const decodeEmit = <const Emits extends ReadonlyArray<Machine.TaggedSchem
   machine: Machine.Any,
   event: unknown
 ): Effect.Effect<Machine.EmitOf<Emits>, MachineSchemaDecodeError> => {
+  const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstruction(machine, protocol, event, "emission") as Effect.Effect<
+      Machine.EmitOf<Emits>,
+      MachineSchemaDecodeError
+    >
+  }
+  if (typeof event === "object" && event !== null && protocol.trustedEmissions.has(event)) {
+    return Effect.succeed(event as Machine.EmitOf<Emits>)
+  }
   const eventName = getEventName(event)
   return decodeBoundary<Machine.EmitOf<Emits>>(
     machine,
-    getProtocolSchemas(machine).emit,
+    protocol.emit,
     event,
-    eventName === undefined ? { boundary: "emit" } : { boundary: "emit", event: eventName }
+    eventName === undefined ? { boundary: "emission" } : { boundary: "emission", event: eventName }
   )
 }
 
@@ -256,12 +537,19 @@ export const decodeEmitSync = <const Emits extends ReadonlyArray<Machine.TaggedS
   machine: Machine.Any,
   event: unknown
 ): Machine.EmitOf<Emits> => {
+  const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstructionSync(machine, protocol, event, "emission") as Machine.EmitOf<Emits>
+  }
+  if (typeof event === "object" && event !== null && protocol.trustedEmissions.has(event)) {
+    return event as Machine.EmitOf<Emits>
+  }
   const eventName = getEventName(event)
   return decodeBoundarySync<Machine.EmitOf<Emits>>(
     machine,
-    getProtocolSchemas(machine).emit,
+    protocol.emit,
     event,
-    eventName === undefined ? { boundary: "emit" } : { boundary: "emit", event: eventName }
+    eventName === undefined ? { boundary: "emission" } : { boundary: "emission", event: eventName }
   )
 }