@typeonce/effect-machine 0.9.0 → 0.10.0

package/src/internal/machine/protocol.ts

@@ -15,7 +15,7 @@ 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
 }
@@ -25,17 +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>
@@ -105,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()
   })
 }
 
@@ -122,19 +184,39 @@ 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 => ({
-  [EventConstructionTypeId]: EventConstructionTypeId,
-  _tag: tag,
-  schema,
-  input
-})
+): 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 => hasProperty(value, EventConstructionTypeId)
+const isEventConstruction = (value: unknown): value is EventConstruction =>
+  typeof value === "object" && value !== null && eventConstructionDefinitions.has(value)
 
-export const eventConstructors = (
+const eventConstructors = (
+  kind: Machine.EventProtocolKind,
   schemas: ReadonlyArray<Machine.TaggedSchema>
 ): Readonly<Record<PropertyKey, (...args: ReadonlyArray<unknown>) => EventConstruction>> => {
   const leaves: Array<Machine.TaggedSchema> = []
@@ -182,20 +264,15 @@ export const eventConstructors = (
   for (const schema of leaves) {
     const discriminants = schemaTags(schema)
     if (discriminants.length === 0) {
-      throw new Error("Machine event constructors require finite literal or unique symbol event tags")
+      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>) => {
-          const fields = args.length === 0 ? {} : args[0]
-          const input = typeof fields === "object" && fields !== null
-            ? { ...fields, _tag: tag }
-            : { _tag: tag }
-          return makeEventConstruction(schema, tag, input)
-        },
+        value: (...args: ReadonlyArray<unknown>) =>
+          makeEventConstruction(kind, schema, tag, args.length === 0 ? {} : args[0]),
         enumerable: true
       })
     }
@@ -203,6 +280,19 @@ export const eventConstructors = (
   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,
@@ -264,74 +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")
-  }
-  const inputName = getEventName(input)
-  const event = makeBoundarySync<Schema["Type"]>(
-    machine,
-    schema,
-    input,
-    inputName === undefined ? { boundary: "event" } : { boundary: "event", event: inputName }
-  )
-  protocol.trustedEvents.add(event as object)
-  return event
+  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 eventConstructionProtocolError = (
+const eventConstructionInputError = (
   machine: Machine.Any,
-  construction: EventConstruction
+  construction: EventConstruction,
+  boundary: "event" | "emission",
+  cause: unknown
 ): MachineSchemaDecodeError =>
   new MachineSchemaDecodeError({
     machineId: machine.id,
-    boundary: "event",
+    boundary,
     event: String(construction._tag),
-    cause: Cause.die(new Error("Constructed event schema does not belong to the machine event protocol"))
+    cause: Cause.die(cause)
   })
 
 const decodeEventConstruction = (
   machine: Machine.Any,
   protocol: MachineProtocolSchemas,
-  construction: EventConstruction
+  construction: EventConstruction,
+  boundary: "event" | "emission"
 ): Effect.Effect<unknown, MachineSchemaDecodeError> => {
-  if (!protocol.eventConstructors.has(construction.schema as object)) {
-    return Effect.fail(eventConstructionProtocolError(machine, construction))
+  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))
   }
-  return construction.schema.makeEffect(construction.input as never).pipe(
-    Effect.mapError((cause) =>
-      new MachineSchemaDecodeError({
-        machineId: machine.id,
-        boundary: "event",
-        event: String(construction._tag),
-        cause: new Schema.SchemaError(cause)
-      })
+  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(() => protocol.trustedEvents.add(event as object)))
+    Effect.tap((event) =>
+      Effect.sync(() =>
+        (boundary === "event" ? protocol.trustedEvents : protocol.trustedEmissions).add(event as object)
+      )
+    )
   )
 }
 
 const decodeEventConstructionSync = (
   machine: Machine.Any,
   protocol: MachineProtocolSchemas,
-  construction: EventConstruction
+  construction: EventConstruction,
+  boundary: "event" | "emission"
 ): unknown => {
-  if (!protocol.eventConstructors.has(construction.schema as object)) {
-    throw eventConstructionProtocolError(machine, construction)
+  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, construction.schema, construction.input, {
-    boundary: "event",
+  const event = makeBoundarySync(machine, definition.schema, input, {
+    boundary,
     event: String(construction._tag)
   })
-  protocol.trustedEvents.add(event as object)
+  ;(boundary === "event" ? protocol.trustedEvents : protocol.trustedEmissions).add(event as object)
   return event
 }
 
@@ -351,7 +473,7 @@ export const decodeEvent = <const Events extends ReadonlyArray<Machine.TaggedSch
 ): Effect.Effect<Machine.EventOf<Events>, MachineSchemaDecodeError> => {
   const protocol = getProtocolSchemas(machine)
   if (isEventConstruction(event)) {
-    return decodeEventConstruction(machine, protocol, event) as Effect.Effect<
+    return decodeEventConstruction(machine, protocol, event, "event") as Effect.Effect<
       Machine.EventOf<Events>,
       MachineSchemaDecodeError
     >
@@ -374,7 +496,7 @@ export const decodeEventSync = <const Events extends ReadonlyArray<Machine.Tagge
 ): Machine.EventOf<Events> => {
   const protocol = getProtocolSchemas(machine)
   if (isEventConstruction(event)) {
-    return decodeEventConstructionSync(machine, protocol, event) as Machine.EventOf<Events>
+    return decodeEventConstructionSync(machine, protocol, event, "event") as Machine.EventOf<Events>
   }
   if (isTrustedEvent(protocol, event)) {
     return event as Machine.EventOf<Events>
@@ -392,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 }
   )
 }
 
@@ -405,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 }
   )
 }