@playfast/reform-resource 0.1.0 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-resource",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Async resources for Reform — a layer that builds synchronously, loads in the background, and flips a reactive store from pending to ready/failed. The sanctioned home for async work that would otherwise break reform's synchronous scene build.",
   "keywords": [

package/src/asyncResource.ts

@@ -1,32 +1,17 @@
 import { type Store } from '@playfast/reform'
 
-// The value an `AsyncResource` holds: a tagged union discriminated by `isReady`.
-// A resource builds synchronously as `pending`, its load runs in the background,
-// and the store flips to `ready` (or `failed`, only when an `error` schema is
-// declared) when it settles. Consumed with a plain `if`:
-//
-//   const r = yield* MyResource
-//   if (r.isReady) use(r.value)
-//   else if (r.failed) handle(r.error)   // only present when E is not `never`
-//
-// `_tag` is the constant `'AsyncResource'` (so the value reads well in logs and a
-// `Match.tag` still groups it); `isReady` is the real discriminant.
-
-/** The initial state: the load has not settled yet. */
 export interface AsyncResourcePending {
   readonly _tag: 'AsyncResource'
   readonly isReady: false
   readonly failed: false
 }
 
-/** The load resolved; `value` is the acquired resource. */
 export interface AsyncResourceReady<A> {
   readonly _tag: 'AsyncResource'
   readonly isReady: true
   readonly value: A
 }
 
-/** The load failed with the declared error. Only occurs when `E` is not `never`. */
 export interface AsyncResourceFailed<E> {
   readonly _tag: 'AsyncResource'
   readonly isReady: false
@@ -34,17 +19,11 @@ export interface AsyncResourceFailed<E> {
   readonly error: E
 }
 
-/**
- * The resource lifecycle, narrowed by the definition: the `Failed` arm exists
- * only when the resource declares an `error` schema (a non-`never` `E`), so a
- * resource with no error schema is exactly the two-arm `pending | ready` shape.
- */
 export type AsyncResource<A, E = never> =
   | AsyncResourcePending
   | AsyncResourceReady<A>
   | ([E] extends [never] ? never : AsyncResourceFailed<E>)
 
-/** The full (un-narrowed) union — held by the live store, narrowed at the read boundary. */
 export type AnyAsyncResource<A, E> = AsyncResourcePending | AsyncResourceReady<A> | AsyncResourceFailed<E>
 
 const pending: AsyncResourcePending = { _tag: 'AsyncResource', isReady: false, failed: false }
@@ -56,26 +35,14 @@ const failed = <E>(error: E): AsyncResourceFailed<E> => ({
   error,
 })
 
-/** The arm-constructor namespace exposed as `AsyncResource`. */
 export interface AsyncResourceConstructors {
   readonly pending: AsyncResourcePending
   readonly ready: <A>(value: A) => AsyncResourceReady<A>
   readonly failed: <E>(error: E) => AsyncResourceFailed<E>
 }
 
-/**
- * Constructors for the arms, namespaced under the same name as the type so call
- * sites read `AsyncResource.ready(v)` / `AsyncResource.failed(e)` — one obvious
- * home for every arm (mirrors `AsyncData` in reform core).
- */
 export const AsyncResource: AsyncResourceConstructors = { pending, ready, failed }
 
-/**
- * Narrow the live store (which holds the full `AnyAsyncResource` union) to the
- * arms the definition permits (drops `Failed` when `E` is `never`). The single
- * documented home for that narrowing, so `Resource.live` returns it without an
- * inline cast — the established `asyncData.narrowStore` pattern.
- */
 export const narrowStore = <A, E>(store: Store<AnyAsyncResource<A, E>>): Store<AsyncResource<A, E>> =>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- sanctioned variance seam: the live store holds the full union; this is the one documented home for narrowing it to the definition-permitted arms (mirrors asyncData.narrowStore).
   store as unknown as Store<AsyncResource<A, E>>

package/src/index.ts

@@ -1,10 +1,3 @@
-// @playfast/reform-resource — async resources for reform.
-//
-// A `Resource` is a layer that builds synchronously (so it's safe in reform's
-// synchronous scene build), forks an async load under the scene scope, and flips
-// a reactive store from `pending` to `ready`/`failed` when it settles — the
-// sanctioned home for the async work that otherwise trips `AsyncSceneLayer`.
-
 export * as Resource from './resource'
 export type { ResourceClass, ResourceConfig, ResourceManifest } from './resource'
 export {

package/src/reform-resource.test.ts

@@ -2,10 +2,6 @@ import { expect, it } from '@effect/vitest'
 import { Context, Data, Duration, Effect, Layer, Option, Ref, Schema as S } from 'effect'
 import { Resource } from './index'
 
-// A Resource builds synchronously as `pending`, forks its load under the scene
-// scope, and flips a reactive store to `ready`/`failed` when it settles. Scoped
-// acquire/release ties to the scene scope.
-
 const tick = (ms = 30) => Effect.sleep(Duration.millis(ms))
 
 class Boom extends Data.TaggedError('Boom')<{ readonly message: string }> {}
@@ -16,7 +12,6 @@ it.live('builds pending then resolves to ready', () => {
 
   return Effect.gen(function* () {
     const store = yield* Num.store
-    // Synchronous build → the value is available immediately as pending.
     expect(store.get().isReady).toBe(false)
     yield* tick(60)
     const value = store.get()
@@ -70,10 +65,8 @@ it.live('ties acquire/release to the scene scope', () =>
         const store = Context.get(context, Conn.store)
         yield* tick()
         expect(store.get().isReady).toBe(true)
-        // Still open while the scene scope is alive.
         expect(yield* Ref.get(released)).toBe(false)
       }),
     )
-    // Scene scope closed → the acquire's finalizer ran.
     expect(yield* Ref.get(released)).toBe(true)
   }))

package/src/resource.ts

@@ -13,20 +13,13 @@ import {
   narrowStore,
 } from './asyncResource'
 
-// `Resource` is the sanctioned home for async work that would otherwise run during
-// reform's synchronous layer build (and trip `AsyncSceneLayer`). Its `live` layer
-// builds synchronously — seeding a `pending` store — then forks the load under the
-// scene scope and flips the store to `ready`/`failed` when it settles. The flip is
-// an ordinary `Store.set`, so a render that read the resource (via `readTracked`)
-// re-runs just like for any state/calc. Unlike `AsyncCalc` it has no reactive
-// inputs and no query driver: a one-shot, scoped load.
+type AnySchema<A> = Schema.Schema<A, Schema.Schema.Encoded<Schema.Schema.AnyNoContext>>
 
 export interface ResourceManifest<N extends string, A, E> extends Manifest {
   readonly kind: 'Resource'
   readonly name: N
-  readonly output: Schema.Schema<A, any>
-  /** Schema of the failure. `None` ⇒ the load is infallible and there is no `Failed` arm. */
-  readonly error: Option.Option<Schema.Schema<E, any>>
+  readonly output: AnySchema<A>
+  readonly error: Option.Option<AnySchema<E>>
 }
 
 export interface ResourceClass<out N extends string, in out A, in out E>
@@ -34,22 +27,14 @@ export interface ResourceClass<out N extends string, in out A, in out E>
   new (): {}
   readonly manifest: ResourceManifest<N, A, E>
   readonly store: Context.Tag<Store<AsyncResource<A, E>>, Store<AsyncResource<A, E>>>
-  /** The resource's name. */
   readonly name: N
 }
 
 export interface ResourceConfig<A, E> {
-  /** Schema of the ready value. */
-  readonly output: Schema.Schema<A, any>
-  /** Schema of the failure. `None` ⇒ infallible: no `Failed` arm in the value type. */
-  readonly error: Option.Option<Schema.Schema<E, any>>
+  readonly output: AnySchema<A>
+  readonly error: Option.Option<AnySchema<E>>
 }
 
-/**
- * Define an async resource. `output`/`error` schemas shape the value type, so
- * `yield* MyResource` is typed to exactly the arms that can occur (no `Failed` arm
- * without an `error` schema). The load effect itself is supplied by `Resource.live`.
- */
 export const make = <const N extends string, A, E = never>(
   name: N,
   config: ResourceConfig<A, E>,
@@ -65,15 +50,6 @@ export const make = <const N extends string, A, E = never>(
   return yieldableClass(read, { manifest, store, name })
 }
 
-/**
- * Wire the load for a resource. The layer builds synchronously (the store starts
- * `pending`), then forks `acquire` and flips the store to `ready` on success or
- * `failed` on a declared failure. `acquire` may be scoped: its `acquireRelease`
- * finalizers attach to the scene/layer scope (via `Scope.extend`), so an opened
- * connection stays alive while the resource is mounted and releases on dispose.
- * A defect (an unexpected throw) is logged and leaves the resource `pending`,
- * rather than vanishing silently.
- */
 export const live = <N extends string, A, E, R>(
   resource: ResourceClass<N, A, E>,
   acquire: Effect.Effect<A, E, R | Scope.Scope>,
@@ -83,14 +59,11 @@ export const live = <N extends string, A, E, R>(
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
       const scope = yield* Effect.scope
-      // The store holds the full union; the tag (and `yield* Resource`) see the
-      // definition-narrowed arms. Built `pending` so the sync layer build returns
-      // immediately and never trips `AsyncSceneLayer`.
+      // Sync build seeds pending so layer mount never trips AsyncSceneLayer; store holds full union, tag sees narrowed arms.
       const store = makeStore<AnyAsyncResource<A, E>>(AsyncResource.pending, scheduler)
       yield* Effect.forkScoped(
         acquire.pipe(
-          // Finalizers in `acquire` attach to the scene scope, not the load fiber:
-          // a resource opened here lives until the scene unmounts.
+          // Finalizers attach to scene scope, not the load fiber — resource lives until unmount.
           Scope.extend(scope),
           Effect.matchCauseEffect({
             onSuccess: (acquired) => Effect.sync(() => store.set(AsyncResource.ready(acquired))),