@typeonce/effect-machine 0.27.1 → 0.28.0

package/dist/unstable/reactivity/AtomMachine.js

@@ -3,6 +3,7 @@
  *
  * @since 0.4.0
  */
+import { dual } from "effect/Function";
 import * as internal from "../../internal/machine/atom.js";
 /**
  * Error returned when a machine command is issued before startup completes.
@@ -45,6 +46,8 @@ export const inspection = internal.inspection;
  * @since 0.10.0
  */
 export const childEmissions = internal.childEmissions;
+const InvalidSelectorPathTypeId = "~effect/reactivity/AtomMachine/InvalidSelectorPath";
+const SelectorProjectionTypeId = "~effect/reactivity/AtomMachine/SelectorProjection";
 /**
  * Selects the typed value for an active state path.
  *
@@ -79,7 +82,7 @@ export const childEmissions = internal.childEmissions;
  * @category combinators
  * @since 0.4.0
  */
-export const select = internal.select;
+export const select = dual(2, internal.select);
 /**
  * Selects the typed logical snapshot for an active state path.
  *
@@ -90,7 +93,7 @@ export const select = internal.select;
  * @category combinators
  * @since 0.7.0
  */
-export const selectSnapshot = internal.selectSnapshot;
+export const selectSnapshot = dual(2, internal.selectSnapshot);
 /**
  * Selects the typed value for an active state path in a directly owned child.
  *
@@ -108,7 +111,7 @@ export const selectSnapshot = internal.selectSnapshot;
  * @category combinators
  * @since 0.4.0
  */
-export const selectChild = internal.selectChild;
+export const selectChild = dual(2, internal.selectChild);
 /**
  * Selects the typed logical snapshot for an active state path in an invoked
  * child.
@@ -120,7 +123,7 @@ export const selectChild = internal.selectChild;
  * @category combinators
  * @since 0.7.0
  */
-export const selectSnapshotChild = internal.selectSnapshotChild;
+export const selectSnapshotChild = dual(2, internal.selectSnapshotChild);
 /**
  * Returns whether a state path is active.
  *
@@ -153,7 +156,7 @@ export const selectSnapshotChild = internal.selectSnapshotChild;
  * @category combinators
  * @since 0.4.0
  */
-export const matches = internal.matches;
+export const matches = dual(2, internal.matches);
 /**
  * Returns whether a state path is active in a directly owned child.
  *
@@ -164,8 +167,63 @@ export const matches = internal.matches;
  * @category combinators
  * @since 0.4.0
  */
-export const matchesChild = internal.matchesChild;
+export const matchesChild = dual(2, internal.matchesChild);
 const BoundRequirementsTypeId = "~effect/reactivity/AtomMachine/BoundRequirements";
+const FamilyInputRequiredTypeId = "~effect/reactivity/AtomMachine/FamilyInputRequired";
+/**
+ * Creates retained atom families for independent machine inputs.
+ *
+ * The machine input is both startup input and family identity. Each property
+ * in `atoms` projects one public atom family from a private machine bridge.
+ * Retaining any projected atom retains that bridge without keeping its
+ * registry runtime mounted. Keys follow Effect `Equal` and `Hash` semantics.
+ * The optional `label` function labels each public projected atom.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const processAtoms = AtomMachine.family(processMachine, {
+ *   atoms: {
+ *     ready: AtomMachine.matches("Ready"),
+ *     state: (machine) => machine.state,
+ *     send: (machine) => machine.send
+ *   }
+ * })
+ *
+ * const readyAtom = processAtoms.ready("effect")
+ * const sendAtom = processAtoms.send("effect")
+ * ```
+ *
+ * @category constructors
+ * @since 0.28.0
+ */
+export const family = internal.family;
+/**
+ * Creates retained atom families for keyed direct-child lookup.
+ *
+ * The `child` function maps each family key to one direct child descriptor.
+ * Every projected atom retains the resulting child bridge while the projected
+ * atom remains reachable. Keys follow Effect `Equal` and `Hash` semantics.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const Plant = Machine.childFamily(plantMachine)
+ *
+ * const plantAtoms = AtomMachine.familyChild(parentMachineAtom, {
+ *   child: (plantId: string) => Plant(plantId),
+ *   atoms: {
+ *     broken: AtomMachine.matchesChild("Broken"),
+ *     state: (child) => child.state,
+ *     send: (child) => child.send
+ *   }
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.28.0
+ */
+export const familyChild = internal.familyChild;
 /**
  * Creates atoms backed by a running machine.
  *

package/dist/unstable/reactivity/AtomMachine.js.map

@@ -1 +1 @@
-{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAE+D,QAAQ,CAAC,UAAU,CAAA;AAEzG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAoJ3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,MAAM,GAUf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAUvB,QAAQ,CAAC,cAAc,CAAA;AAE3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GASpB,QAAQ,CAAC,WAAW,CAAA;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAS5B,QAAQ,CAAC,mBAAmB,CAAA;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,OAAO,GAWmD,QAAQ,CAAC,OAAO,CAAA;AAEvF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAMrB,QAAQ,CAAC,YAAY,CAAA;AAEzB,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAkHlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,IAAI,GAqDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}
+{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAMtC,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAE+D,QAAQ,CAAC,UAAU,CAAA;AAEzG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAwJ3B,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AACtF,MAAM,wBAAwB,GAAG,mDAAmD,CAAA;AA0BpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,MAAM,GA0Cf,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;AAE5B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GA0CvB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAsCpB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAoC5B,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,OAAO,GAsChB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;AAE7B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GA2BrB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;AAElC,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAkJlF,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AAyFtF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,MAAM,GAkBgE,QAAQ,CAAC,MAAa,CAAA;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,WAAW,GAYqC,QAAQ,CAAC,WAAkB,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,IAAI,GAqDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}

package/docs/effect-atom-react.md

@@ -1,6 +1,6 @@
 # Effect Atom and React patterns
 
-This guide records the folder organization and three integration patterns
+This guide records the folder organization and four integration patterns
 validated in the process app. Use the API reference for individual AtomMachine
 operations. Read the [Effect Machine agent guide](./agent-guide.md) for
 statechart modeling, transitions, services, and testing.
@@ -74,35 +74,56 @@ export const counterStateAtom = AtomMachine.select(
 Consumers read `counterStateAtom` and use `counterMachineAtom.send` directly.
 Do not add a redundant `counterSendAtom` alias.
 
-## 2. A machine with startup input selected through a family
+## 2. A keyed machine with startup input
 
-Use the family key as machine identity. The same value can also be startup
-input:
+`AtomMachine.family` uses the machine input as both startup input and family
+key. It returns one direct atom family for each entry in `atoms`:
 
 ```ts
 import { machineAtoms } from "@/lib/atom-runtime"
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { Atom } from "effect/unstable/reactivity"
 import { processMachine } from "./machine"
 
-export const processFamily = Atom.family((query: string) => {
-  const machine = machineAtoms.make(processMachine, { query })
-
-  return {
-    detailsAtom: AtomMachine.select(machine, "process"),
-    resultAtom: AtomMachine.select(machine, "process.Ready"),
-    sendAtom: machine.send
-  }
+export const processAtoms = machineAtoms.family(processMachine, {
+  atoms: {
+    details: AtomMachine.select("process"),
+    result: AtomMachine.select("process.Ready"),
+    send: (machine) => machine.send
+  },
+  label: (input, name) => `process:${input.query}:${name}`
 })
 ```
 
-A consumer calls `processFamily(query)` and uses the returned focused atoms. If
-several nested components need the same scope, an optional Context can expose
-`ReturnType<typeof processFamily>`. The provider resolves the query once instead
-of drilling it through every component.
+React consumes each projected family directly:
+
+```tsx
+const input = { query }
+const details = useAtomValue(processAtoms.details(input))
+const send = useAtomSet(processAtoms.send(input))
+```
+
+Each public atom retains its private machine bridge. Keeping only `details` or
+only `send` is safe. The bridge still starts lazily in the registry and stops
+when that registry releases or disposes it. A writable source remains writable,
+and a projection keeps the source atom's equality function.
+
+The family uses Effect `Equal` and `Hash` semantics. Equal records such as
+`{ query: "effect" }` select the same family value even when reconstructed.
+Keep inputs immutable because mutating a hashed key makes later lookup
+unreliable. Different input values select independent machines. If a changing
+value should update one running workflow, model the change as an event instead
+of putting it in the machine input.
 
-Changing `query` selects another family member and therefore another machine.
-If a changing value should update the current workflow, model it as an event.
+Service-free machines use the module function directly:
+
+```ts
+export const processAtoms = AtomMachine.family(processMachine, {
+  atoms: {
+    details: AtomMachine.select("process"),
+    send: (machine) => machine.send
+  }
+})
+```
 
 ## 3. Reusing one machine definition for multiple instances
 
@@ -127,8 +148,6 @@ export function makeDialogScope() {
 export type DialogScope = ReturnType<typeof makeDialogScope>
 ```
 
-Choose one of the following ownership forms.
-
 ### React-tree-owned instance
 
 ```tsx
@@ -150,56 +169,10 @@ Each provider owns one independent dialog. Descendants use a small
 `DialogScope` through props when Context is unnecessary. Do not add a wrapper
 component whose only job is forwarding the scope.
 
-### Stable keyed instances shared across scattered components
-
-Use one private family to create the scope for an ID. Public selector families
-reach that same scope:
-
-```ts
-import { Atom } from "effect/unstable/reactivity"
-
-const dialogScopeFamily = Atom.family((dialogId: string) => {
-  const scope = makeDialogScope()
-
-  return {
-    isOpenAtom: scope.isOpenAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:isOpen-source`)
-    ),
-    openStateAtom: scope.openStateAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:openState-source`)
-    ),
-    sendAtom: scope.sendAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:send-source`)
-    )
-  }
-})
-
-export const dialogIsOpenFamily = Atom.family((dialogId: string) => {
-  const scope = dialogScopeFamily(dialogId)
-
-  return Atom.transform(
-    scope.sendAtom,
-    (get) => get(scope.isOpenAtom)
-  ).pipe(Atom.withLabel(`dialog:${dialogId}:isOpen`))
-})
-
-export const dialogOpenStateFamily = Atom.family((dialogId: string) => {
-  const scope = dialogScopeFamily(dialogId)
-
-  return Atom.transform(
-    scope.sendAtom,
-    (get) => get(scope.openStateAtom)
-  ).pipe(Atom.withLabel(`dialog:${dialogId}:openState`))
-})
-```
-
-Components using the same `dialogId` share one machine. Different IDs create
-independent machines. The two public projections let consumers subscribe
-independently. Both remain writable through `Atom.transform`, so either can send
-the inferred dialog events.
-
-Use `dialogId` in atom labels for diagnostics. Do not pass it into
-`dialogMachine` as unused fake input.
+For a no-input machine, use one module-level bridge or an explicitly owned
+React scope. Do not add a family key that the machine does not consume. When an
+ID is part of startup semantics, declare it in the machine input and use
+`AtomMachine.family`.
 
 ## 4. Selecting process-owned child machines
 
@@ -211,18 +184,23 @@ const Plant = Machine.childFamily(plantMachine)
 
 export const centralMachineAtom = machineAtoms.make(centralMachine)
 
-export const plantScopeFamily = Atom.family((plantId: string) => {
-  const plant = centralMachineAtom.child(Plant(plantId))
-
-  return {
-    stateAtom: plant.state,
-    isBrokenAtom: AtomMachine.matchesChild(plant, "Broken"),
-    sendAtom: plant.send,
-    stopAtom: plant.stop
+export const plantAtoms = AtomMachine.familyChild(centralMachineAtom, {
+  child: (plantId: string) => Plant(plantId),
+  atoms: {
+    state: (plant) => plant.state,
+    isBroken: AtomMachine.matchesChild("Broken"),
+    send: (plant) => plant.send,
+    stop: (plant) => plant.stop
   }
 })
+
+const broken = useAtomValue(plantAtoms.isBroken(plantId))
+const send = useAtomSet(plantAtoms.send(plantId))
 ```
 
+`familyChild` keeps child lookup separate from root machine startup. Each
+projected atom retains the child bridge returned for its key.
+
 `Plant(plantId)` may be reconstructed wherever the id is available. Child
 lookup and bridge reuse match by machine identity and id, not descriptor object
 identity. Before the parent spawns that child, selectors contain `Option.none`

package/docs/machine-review.md

@@ -65,27 +65,16 @@ const handlers = {
 Review check: search for `.resolve(...)` callbacks that only return an empty
 `target.from()` and remove the callback.
 
-## Let `Atom.family` own keyed identity
+## Use retained families for keyed machine input
 
-Treat `useMemo` around an atom family lookup as a warning sign. `Atom.family`
-already returns the same retained object for the same key, including when
-separate components perform the lookup.
-
-```tsx
-// Redundant and local to one component
-const scope = useMemo(() => processFamily(processId), [processId])
-
-// The family owns identity
-const scope = processFamily(processId)
-```
-
-If the component constructs the atoms or machine scope directly, move that
-construction into a module-level family:
+Effect Atom keeps a family value for an equal key while that returned value is
+reachable. Current runtimes may hold family values through `WeakRef`. Retaining
+one field from a composite family value does not retain the composite itself:
 
 ```ts
-export const processFamily = Atom.family((processId: string) => {
-  const machine = machineAtoms.make(processMachine, { processId })
-
+// Unsafe when consumers retain only stateAtom or sendAtom
+const processScope = Atom.family((input: ProcessInput) => {
+  const machine = machineAtoms.make(processMachine, input)
   return {
     stateAtom: AtomMachine.select(machine, "process"),
     sendAtom: machine.send
@@ -93,17 +82,33 @@ export const processFamily = Atom.family((processId: string) => {
 })
 ```
 
-Use a stable domain key. A new key means a different machine instance. Send an
-event when a value should update the current workflow instead.
+Use `AtomMachine.family` for an input-bearing machine. It returns direct atom
+families whose atoms retain the private machine bridge:
+
+```ts
+export const processAtoms = machineAtoms.family(processMachine, {
+  atoms: {
+    state: AtomMachine.select("process"),
+    send: (machine) => machine.send
+  }
+})
+
+const stateAtom = processAtoms.state(input)
+const sendAtom = processAtoms.send(input)
+```
+
+No component `useMemo` is needed. The registry retains the public atom while a
+hook subscribes to it, and that atom retains the machine owner. Equal inputs
+use Effect `Equal` and `Hash` semantics and select the same family value.
 
-`useMemo` may still be useful for unrelated expensive calculations. It should
-not establish atom or machine identity. For one instance owned only by a React
-subtree, use a lazy `useState(makeScope)` initializer as described in the React
-guide.
+For a no-input machine, use one module-level bridge or a lazy
+`useState(makeScope)` value owned by a React subtree. Do not add an unused key.
 
-Review check: search for `useMemo` around atom creation, family lookup, or
-`machineAtoms.make`. Replace component-local identity with `Atom.family`, or
-with an intentional component-owned scope.
+Review check: search for composite `Atom.family` values that own a machine,
+`useMemo` around family lookup, and component-local calls to
+`machineAtoms.make`. Replace an input-bearing machine with
+`AtomMachine.family`. Give a no-input instance an explicit module or React-tree
+owner.
 
 ## Justify each `RegistryProvider`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {

package/src/internal/machine/atom.ts

@@ -8,6 +8,7 @@ import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as Equal from "effect/Equal"
 import * as Fiber from "effect/Fiber"
+import * as MutableHashMap from "effect/MutableHashMap"
 import * as Option from "effect/Option"
 import type * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
@@ -78,6 +79,47 @@ const preparedByMachineAtom = new WeakMap<
   Atom.Atom<AsyncResult.AsyncResult<Machine.Prepared<any, any, any, any, any, any, any>, any>>
 >()
 
+type WeakFamilyEntry<Value extends object> = {
+  readonly ref: WeakRef<Value>
+}
+
+// This follows Atom.family, but cleanup is generation-aware. A finalizer for a
+// collected value must not remove a newer value installed for the same key.
+const retainedFamily = <Key, Value extends object>(
+  makeValue: (key: Key) => Value
+): (key: Key) => Value => {
+  if (typeof WeakRef === "undefined" || typeof FinalizationRegistry === "undefined") {
+    return Atom.family(makeValue)
+  }
+
+  const values = MutableHashMap.empty<Key, WeakFamilyEntry<Value>>()
+  const registry = new FinalizationRegistry<{
+    readonly key: Key
+    readonly entry: WeakFamilyEntry<Value>
+  }>(({ entry, key }) => {
+    const current = MutableHashMap.get(values, key)
+    if (Option.isSome(current) && current.value === entry) {
+      MutableHashMap.remove(values, key)
+    }
+  })
+
+  return (key) => {
+    const current = MutableHashMap.get(values, key)
+    if (Option.isSome(current)) {
+      const value = current.value.ref.deref()
+      if (value !== undefined) {
+        return value
+      }
+    }
+
+    const value = makeValue(key)
+    const entry = { ref: new WeakRef(value) }
+    MutableHashMap.set(values, key, entry)
+    registry.register(value, { key, entry })
+    return value
+  }
+}
+
 const runMachineAtomEffect = <State, Event, Error, Output, Emitted, StartError, Requirements>(
   get: Atom.AtomContext,
   start: Effect.Effect<Machine.MachineRef<State, Event, Error, Output, Emitted>, StartError, Requirements>
@@ -738,6 +780,69 @@ const resumeWithRuntime = (
   return makeFromRefAtom(ref as any)
 }
 
+type FamilyBridge = MachineAtom<any, never, any, any, any, any> | ChildMachineAtom<any, any>
+
+type FamilyOptions = {
+  readonly atoms: Readonly<Record<string, (bridge: FamilyBridge) => Atom.Atom<any>>>
+  readonly label?: (key: any, atomName: string) => string | undefined
+}
+
+const retainFamilyOwner = <Source extends Atom.Atom<any>>(
+  owner: { readonly bridge: FamilyBridge },
+  source: Source,
+  label: string | undefined
+): Atom.WithoutSerializable<Source> => {
+  const retained = { owner, source }
+  let atom: Atom.Atom<any> = Atom.transform(
+    source,
+    (get) => get(retained.source),
+    { initialValueTarget: source }
+  ).pipe(
+    Atom.withEquality((value, next) => retained.source.equals(value, next))
+  )
+  if (label !== undefined) {
+    atom = atom.pipe(Atom.withLabel(label))
+  }
+  return atom as unknown as Atom.WithoutSerializable<Source>
+}
+
+const makeFamily = (
+  makeBridge: (key: any) => FamilyBridge,
+  options: FamilyOptions
+): Readonly<Record<string, (key: any) => Atom.Atom<any>>> => {
+  const owners = retainedFamily((key: any) => ({ bridge: makeBridge(key) }))
+  const atoms: Record<string, (key: any) => Atom.Atom<any>> = {}
+
+  for (const atomName of Object.keys(options.atoms)) {
+    const project = options.atoms[atomName]!
+    atoms[atomName] = retainedFamily((key: any) => {
+      const owner = owners(key)
+      const source = project(owner.bridge)
+      return retainFamilyOwner(owner, source, options.label?.(key, atomName))
+    })
+  }
+
+  return atoms
+}
+
+export const family = (
+  machine: Machine.Machine.Any,
+  options: FamilyOptions
+): Readonly<Record<string, (key: any) => Atom.Atom<any>>> =>
+  makeFamily(
+    (input) => (make as any)(machine, input),
+    options
+  )
+
+export const familyChild = (
+  parent: MachineAtom<any, never, any, any, any, any> | ChildMachineAtom<any, any>,
+  options: FamilyOptions & { readonly child: (key: any) => Machine.ChildMachine.Any }
+): Readonly<Record<string, (key: any) => Atom.Atom<any>>> =>
+  makeFamily(
+    (key) => parent.child(options.child(key)),
+    options
+  )
+
 export const bind = <Services, RuntimeError>(
   runtime: Atom.AtomRuntime<Services, RuntimeError>
 ): Bound<Services, RuntimeError> => ({
@@ -749,5 +854,10 @@ export const bind = <Services, RuntimeError>(
       >["make"],
   resume:
     ((machine: Machine.Machine.Any, snapshot: Machine.Machine.Snapshot<any>) =>
-      resumeWithRuntime(runtime, machine, snapshot)) as Bound<Services, RuntimeError>["resume"]
+      resumeWithRuntime(runtime, machine, snapshot)) as Bound<Services, RuntimeError>["resume"],
+  family: ((machine: Machine.Machine.Any, options: FamilyOptions) =>
+    makeFamily(
+      (input) => makeWithRuntime(runtime, machine, [input]),
+      options
+    )) as Bound<Services, RuntimeError>["family"]
 })