@playfast/reform-resource 0.0.6 → 1.0.1

package/README.md

@@ -22,10 +22,14 @@ a one-shot, scoped load.
 
 ```typescript
 import { Resource } from '@playfast/reform-resource'
-import { Effect, Schema as S } from 'effect'
+import { Effect, Option, Schema as S } from 'effect'
 
-// Define — output schema shapes the ready value; add `error` for a failed arm.
-class Config extends Resource.make('Config', { output: S.Struct({ url: S.String }) }) {}
+// Define — `output` shapes the ready value; `error` is required (`Option.none()`
+// for an infallible load, `Option.some(schema)` to add a `failed` arm).
+class Config extends Resource.make('Config', {
+  output: S.Struct({ url: S.String }),
+  error: Option.none(),
+}) {}
 
 // Wire — `acquire` may be scoped (acquire/release tied to the scene scope).
 const ConfigLive = Resource.live(
@@ -40,13 +44,7 @@ const view = Effect.gen(function* () {
 })
 ```
 
-The value is a union discriminated by `isReady`:
+The value is a union discriminated by `isReady` (`pending | ready`, plus a `failed`
+arm only when an `error` schema is declared).
 
-```typescript
-type AsyncResource<A, E = never> =
-  | { _tag: 'AsyncResource'; isReady: false; failed: false }       // pending
-  | { _tag: 'AsyncResource'; isReady: true;  value: A }            // ready
-  | { _tag: 'AsyncResource'; isReady: false; failed: true; error: E } // only when E ≠ never
-```
-
-The public API is re-exported from [the package index](./src/index.ts).
+See the [playbook](./playbook/api.doc.md) for the full API and `AsyncResource` type.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-resource",
   "playbook": "./playbook",
-  "version": "0.0.6",
+  "version": "1.0.1",
   "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

@@ -48,7 +48,7 @@ export type AsyncResource<A, E = never> =
 export type AnyAsyncResource<A, E> = AsyncResourcePending | AsyncResourceReady<A> | AsyncResourceFailed<E>
 
 const pending: AsyncResourcePending = { _tag: 'AsyncResource', isReady: false, failed: false }
-const ready = <A>(value: A): AsyncResourceReady<A> => ({ _tag: 'AsyncResource', isReady: true, value })
+const ready = <A>(acquired: A): AsyncResourceReady<A> => ({ _tag: 'AsyncResource', isReady: true, value: acquired })
 const failed = <E>(error: E): AsyncResourceFailed<E> => ({
   _tag: 'AsyncResource',
   isReady: false,
@@ -77,4 +77,5 @@ export const AsyncResource: AsyncResourceConstructors = { pending, ready, failed
  * 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/reform-resource.test.ts

@@ -1,5 +1,5 @@
 import { expect, it } from '@effect/vitest'
-import { Context, Data, Duration, Effect, Layer, Ref, Schema as S } from 'effect'
+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
@@ -11,7 +11,7 @@ const tick = (ms = 30) => Effect.sleep(Duration.millis(ms))
 class Boom extends Data.TaggedError('Boom')<{ readonly message: string }> {}
 
 it.live('builds pending then resolves to ready', () => {
-  class Num extends Resource.make('Num', { output: S.Number }) {}
+  class Num extends Resource.make('Num', { output: S.Number, error: Option.none() }) {}
   const layer = Resource.live(Num, Effect.delay(Effect.succeed(7), Duration.millis(20)))
 
   return Effect.gen(function* () {
@@ -26,7 +26,7 @@ it.live('builds pending then resolves to ready', () => {
 })
 
 it.live('a failing load resolves to the failed arm carrying the error', () => {
-  class Conn extends Resource.make('Conn', { output: S.Number, error: S.instanceOf(Boom) }) {}
+  class Conn extends Resource.make('Conn', { output: S.Number, error: Option.some(S.instanceOf(Boom)) }) {}
   const layer = Resource.live(Conn, Effect.fail(new Boom({ message: 'nope' })))
 
   return Effect.gen(function* () {
@@ -39,7 +39,7 @@ it.live('a failing load resolves to the failed arm carrying the error', () => {
 })
 
 it.live('notifies subscribers when it flips to ready', () => {
-  class Num extends Resource.make('Num', { output: S.Number }) {}
+  class Num extends Resource.make('Num', { output: S.Number, error: Option.none() }) {}
   const layer = Resource.live(Num, Effect.succeed(1))
 
   return Effect.gen(function* () {
@@ -58,7 +58,7 @@ it.live('notifies subscribers when it flips to ready', () => {
 it.live('ties acquire/release to the scene scope', () =>
   Effect.gen(function* () {
     const released = yield* Ref.make(false)
-    class Conn extends Resource.make('Conn', { output: S.Number }) {}
+    class Conn extends Resource.make('Conn', { output: S.Number, error: Option.none() }) {}
     const layer = Resource.live(
       Conn,
       Effect.acquireRelease(Effect.succeed(1), () => Ref.set(released, true)),

package/src/resource.ts

@@ -25,8 +25,8 @@ 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. Omitted ⇒ the load is infallible and there is no `Failed` arm. */
-  readonly error?: Schema.Schema<E, any>
+  /** Schema of the failure. `None` ⇒ the load is infallible and there is no `Failed` arm. */
+  readonly error: Option.Option<Schema.Schema<E, any>>
 }
 
 export interface ResourceClass<out N extends string, in out A, in out E>
@@ -41,8 +41,8 @@ export interface ResourceClass<out N extends string, in out A, in out E>
 export interface ResourceConfig<A, E> {
   /** Schema of the ready value. */
   readonly output: Schema.Schema<A, any>
-  /** Schema of the failure. Omitted ⇒ infallible: no `Failed` arm in the value type. */
-  readonly error?: Schema.Schema<E, any>
+  /** Schema of the failure. `None` ⇒ infallible: no `Failed` arm in the value type. */
+  readonly error: Option.Option<Schema.Schema<E, any>>
 }
 
 /**
@@ -59,7 +59,7 @@ export const make = <const N extends string, A, E = never>(
     kind: 'Resource',
     name,
     output: config.output,
-    ...(config.error !== undefined ? { error: config.error } : {}),
+    error: config.error,
   }
   const read = Effect.flatMap(store, readTracked)
   return yieldableClass(read, { manifest, store, name })
@@ -93,14 +93,15 @@ export const live = <N extends string, A, E, R>(
           // a resource opened here lives until the scene unmounts.
           Scope.extend(scope),
           Effect.matchCauseEffect({
-            onSuccess: (value) => Effect.sync(() => store.set(AsyncResource.ready(value))),
+            onSuccess: (acquired) => Effect.sync(() => store.set(AsyncResource.ready(acquired))),
             onFailure: (cause) =>
               Option.match(Cause.failureOption(cause), {
                 onSome: (error) => Effect.sync(() => store.set(AsyncResource.failed(error))),
                 onNone: () =>
                   Cause.isInterruptedOnly(cause)
                     ? Effect.void
-                    : Effect.logError(`reform-resource: load for '${resource.name}' failed`, cause),
+                    : // oxlint-disable-next-line reform-rules/no-effect-log -- reform-resource has no @play/effect-utils dep (same as reform core); the package logs via Effect directly.
+                      Effect.logError(`reform-resource: load for '${resource.name}' failed`, cause),
               }),
           }),
         ),