@playfast/reform 0.0.9 → 0.0.11

package/src/feature/feature.ts

@@ -1,4 +1,4 @@
-import { type Context, Effect, Layer, type Scope } from 'effect'
+import { type Context, Effect, Layer, Option, type Scope } from 'effect'
 import { type Engine } from '../runtime/loop'
 import { type StoresOf } from '../internal/sources'
 import { FeatureLoadFailed } from '../internal/errors'
@@ -114,10 +114,10 @@ export interface FeatureManifest extends Manifest {
   readonly name: string
   readonly strategy: 'lazy' | 'default'
   readonly composition: Manifest & { readonly kind: 'Composition' }
-  readonly placeholder?: {
+  readonly placeholder: Option.Option<{
     readonly loading: Manifest & { readonly kind: 'Composition' }
     readonly failed: Manifest & { readonly kind: 'Composition' }
-  }
+  }>
 }
 
 /**
@@ -152,6 +152,7 @@ export interface FeatureBinding {
   readonly composition: CompositionClass<unknown>
   readonly strategy: 'lazy' | 'default'
   readonly load: Effect.Effect<LoadedModule, FeatureLoadFailed>
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- read at the react host seam via `binding.placeholder === undefined`; an Option here would force a cross-package edit (react host) owned by another agent
   readonly placeholder?: {
     readonly loading: CompositionClass<unknown>
     readonly failed: CompositionClass<unknown>
@@ -160,8 +161,8 @@ export interface FeatureBinding {
 }
 
 /** Whether a slot's bound child is a lazy/eager feature (vs a plain composition). */
-export const isFeatureBinding = (u: unknown): u is FeatureBinding =>
-  typeof u === 'object' && u !== null && FeatureBindingTypeId in u
+export const isFeatureBinding = (candidate: unknown): candidate is FeatureBinding =>
+  typeof candidate === 'object' && candidate !== null && FeatureBindingTypeId in candidate
 
 /**
  * A feature *definition*: a reflectable manifest (`kind: 'Feature'`) that carries
@@ -195,11 +196,14 @@ export interface FeatureClass<
 export type AnyFeature = FeatureClass<any, any, any, ReadonlyArray<RequireCarrier>>
 
 /** Whether a value is a feature definition (its target shape in `provide(slot, Feature)`). */
-export const isFeature = (u: unknown): u is AnyFeature =>
-  (typeof u === 'function' || typeof u === 'object') &&
-  u !== null &&
-  'manifest' in u &&
-  (u as { readonly manifest: { readonly kind?: unknown } }).manifest?.kind === 'Feature'
+export const isFeature = (candidate: unknown): candidate is AnyFeature =>
+  (typeof candidate === 'function' || typeof candidate === 'object') &&
+  candidate !== null &&
+  'manifest' in candidate &&
+  typeof candidate.manifest === 'object' &&
+  candidate.manifest !== null &&
+  'kind' in candidate.manifest &&
+  candidate.manifest.kind === 'Feature'
 
 /**
  * The placeholders a lazy feature must ship — both eager compositions (their
@@ -213,7 +217,12 @@ export interface Placeholders {
   readonly failed: CompositionClass<any, UiContract>
 }
 
-type FeatureConfig<P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>> = {
+type FeatureConfigExternalApi<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<RequireCarrier>,
+> = {
   readonly composition: CompositionClass<P, C>
   readonly boot?: ReadonlyArray<Tagged>
 } & (
@@ -240,7 +249,7 @@ type FeatureConfig<P, C extends UiContract, ROut, Requires extends ReadonlyArray
  */
 export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>>(
   name: string,
-  config: FeatureConfig<P, C, ROut, Requires>,
+  config: FeatureConfigExternalApi<P, C, ROut, Requires>,
 ): FeatureClass<P, C, ROut, Requires> => {
   const strategy: 'lazy' | 'default' = config.loadingStrategy ?? 'default'
   const load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed> =
@@ -253,9 +262,12 @@ export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArr
     name,
     strategy,
     composition: config.composition.manifest,
-    ...(placeholder
-      ? { placeholder: { loading: placeholder.loading.manifest, failed: placeholder.failed.manifest } }
-      : {}),
+    placeholder: Option.fromNullable(placeholder).pipe(
+      Option.map((placeholders) => ({
+        loading: placeholders.loading.manifest,
+        failed: placeholders.failed.manifest,
+      })),
+    ),
   }
 
   const binding: FeatureBinding = {
@@ -267,7 +279,7 @@ export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArr
     // assignment to the erased `LoadedModule` needs no cast — see `LoadedModule`.
     load,
     ...(placeholder ? { placeholder: { loading: placeholder.loading, failed: placeholder.failed } } : {}),
-    boot: config.boot ?? [],
+    boot: Option.getOrElse(Option.fromNullable(config.boot), () => []),
   }
 
   return definitionClass<FeatureClass<P, C, ROut, Requires>>({ manifest, load, binding, eagerModule })
@@ -289,12 +301,14 @@ export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArr
  * we re-attach the concrete `engineContext` it builds against. `R` is the engine
  * context's service set, supplied by the host.
  */
+// oxlint-disable-next-line reform-rules/prefer-effect-fn -- generic export: Effect.fn's inferred type isn't portable under isolatedDeclarations
 export const mountFeature = <R>(
   binding: FeatureBinding,
   engineContext: Context.Context<R>,
 ): Effect.Effect<Context.Context<unknown>, FeatureLoadFailed, Scope.Scope> =>
   Effect.gen(function* () {
     const { layer } = yield* binding.load
+    // oxlint-disable-next-line reform-rules/no-type-assertion -- documented erasure boundary: re-attach the concrete engine context to the type-erased `LoadedModule` layer (mirrors `buildRuntime`); RIn was verified cast-free at `provide`/scene wiring
     const featureLayer = layer as Layer.Layer<unknown, never, R>
     const context = yield* Layer.build(
       Layer.provideMerge(featureLayer, Layer.succeedContext(engineContext)),

package/src/feature/feature.typecheck.ts

@@ -65,7 +65,7 @@ const AppFeatureBase: Feature.FeatureClass<
 > = Feature.make('appFeature', {
   loadingStrategy: 'lazy',
   composition: AppComp,
-  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  load: lazyImport(async () => ({ default: featureModule([], Layer.empty) })),
   placeholder: { loading: AppComp, failed: AppComp },
 })
 class AppFeature extends AppFeatureBase {}
@@ -95,7 +95,7 @@ const OtherFeatureBase: Feature.FeatureClass<
 > = Feature.make('otherFeature', {
   loadingStrategy: 'lazy',
   composition: OtherComp,
-  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  load: lazyImport(async () => ({ default: featureModule([], Layer.empty) })),
   placeholder: { loading: OtherComp, failed: OtherComp },
 })
 class OtherFeature extends OtherFeatureBase {}

package/src/index.ts

@@ -31,6 +31,23 @@ export {
   type AsyncLoading,
   type AsyncSuccess,
 } from './calc/asyncData'
+// The flat, data-oriented query value (`data`/`error`/`isFetching`/`isStale`) an
+// `AsyncCalc` is driven by; `toAsyncData` projects it onto the matchable arms.
+export { isLoading, type QueryState, toAsyncData } from './calc/queryState'
+// Optional host seams an `AsyncCalc` consults — persistence and lifecycle signals.
+// Concrete implementations live in edge packages (e.g. `@playfast/reform-query-browser`).
+export {
+  noopQueryStore,
+  QueryStore,
+  type QueryStoreApi,
+  resolveQueryStore,
+} from './internal/queryStore'
+export {
+  noopQueryEvents,
+  QueryEvents,
+  type QueryEventsApi,
+  resolveQueryEvents,
+} from './internal/queryEvents'
 export * as RemoteState from './remote/remoteState'
 // Direct type re-exports alongside the namespace (TS2742 nameability): an app
 // layer's inferred type references these (`Store<ReadonlyArray<PendingIntent<…>>>`),
@@ -146,10 +163,14 @@ export { type SlotChild } from './compose/slot'
 // A scene bundles a composition with the closed wiring that runs it — the single
 // handle the react host, proofs, and the dev tool all consume.
 export { isScene, type MountedServices, type Scene, scene, seedScene } from './scene/scene'
+export type { SeedsOf } from './state/stateGroup'
 
 // Runtime surface for hosts (`@reform/react`) and headless tests.
 export { Bus, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
 export { Engine, type ReducerEntry, Reducers } from './runtime/loop'
+// The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
+// `AsyncCalc.refetch` and provider layers act on a query by name through it.
+export { Queries, type QueryHandle, type QueryRegistry } from './runtime/queries'
 export {
   type ChannelClass,
   type ChannelPolicy,

package/src/internal/capture.ts

@@ -17,6 +17,7 @@ export interface UiCapture {
    * components and has no fill key, so it is omitted there. Lets the proof
    * facade select a child by key (`byKey`) instead of by render index.
    */
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- omitted (not Option-none) on the legacy Node path; built in compose/structure.ts and read by the proof package, both outside this batch
   readonly key?: string
 }
 

package/src/internal/errors.ts

@@ -94,8 +94,12 @@ export class AsyncSceneLayer extends AsyncSceneLayerBase {
  * shapes are checked.
  */
 const isAsyncBuildDefect = (error: unknown): boolean => {
-  if (Runtime.isAsyncFiberException(error)) return true
-  if (!Runtime.isFiberFailure(error)) return false
+  if (Runtime.isAsyncFiberException(error)) {
+    return true
+  }
+  if (!Runtime.isFiberFailure(error)) {
+    return false
+  }
   const die = Cause.dieOption(error[Runtime.FiberFailureCauseId])
   return Option.isSome(die) && Runtime.isAsyncFiberException(die.value)
 }
@@ -107,11 +111,12 @@ const isAsyncBuildDefect = (error: unknown): boolean => {
  * the React host and the remote server.
  */
 export const forceSync = <A>(thunk: () => A): A => {
+  // oxlint-disable-next-line reform-rules/no-try-catch -- sync-build boundary must throw the exact value, which Effect.runSync would re-wrap in a FiberFailure
   try {
     return thunk()
   } catch (error) {
-    if (isAsyncBuildDefect(error)) throw new AsyncSceneLayer()
-    throw error
+    // oxlint-disable-next-line reform-rules/no-throw -- rethrow the exact value (translated for the async-build defect) so callers can match on it
+    throw isAsyncBuildDefect(error) ? new AsyncSceneLayer() : error
   }
 }
 

package/src/internal/inspect.ts

@@ -21,14 +21,14 @@ export const inspectable = (toJSON: () => unknown): Inspectable => ({
  * whose statics are merged in separately.
  */
 export const attachInspectable = <T extends object>(target: T, toJSON: () => unknown): T => {
-  const trio = inspectable(toJSON) as unknown as Record<PropertyKey, unknown>
-  for (const key of Reflect.ownKeys(trio)) {
+  const trio = inspectable(toJSON)
+  Reflect.ownKeys(trio).forEach((key) => {
     Object.defineProperty(target, key, {
-      value: trio[key],
+      value: Reflect.get(trio, key),
       enumerable: false,
       writable: true,
       configurable: true,
     })
-  }
+  })
   return target
 }