foldkit 0.165.0 → 0.166.0

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://www.npmjs.com/package/foldkit"><img src="https://img.shields.io/npm/v/foldkit" alt="npm version"></a>
 </p>
 
-<h3 align="center">The frontend framework for correctness.</h3>
+<h3 align="center">Build faster. Understand what ships.</h3>
 
 <p align="center">
   <a href="https://foldkit.dev"><strong>Documentation</strong></a> · <a href="https://foldkit.dev/introduction/why-foldkit"><strong>Why Foldkit</strong></a> · <a href="https://foldkit.dev/example-apps"><strong>Examples</strong></a> · <a href="https://foldkit.dev/get-started"><strong>Get Started</strong></a> · <a href="https://discord.gg/kav8VNxqGm"><strong>Discord</strong></a>
@@ -153,6 +153,7 @@ Some of what you can build with Foldkit. [See all example apps on foldkit.dev](h
 - **[Job Application](https://foldkit.dev/example-apps/job-application)**: Multi-step form with cross-field validation, file uploads, and per-step error indicators
 - **[Weather](https://foldkit.dev/example-apps/weather)**: HTTP requests with async state handling
 - **[API Cache](https://foldkit.dev/example-apps/api-cache)**: Query caching with stale-while-revalidate, request deduplication, and interval refetching
+- **[API Cache Query](https://foldkit.dev/example-apps/api-cache-query)**: The same app with experimental `Query.define` owning fetch and keyed slots
 - **[Routing](https://foldkit.dev/example-apps/routing)**: URL routing with parser combinators
 - **[Route Transitions](https://foldkit.dev/example-apps/route-transitions)**: Live transition log with entry, exit, and stayed navigation policies
 - **[Query Sync](https://foldkit.dev/example-apps/query-sync)**: URL query parameter sync with filtering and sorting

package/dist/devTools/serialize.d.ts

@@ -1,7 +1,8 @@
 import type { SerializedCommand, SerializedEntry, SerializedMount } from './protocol.js';
 import type { CommandRecord, HistoryEntry, MountRecord } from './store.js';
 /**
- * Convert DOM-class instances (File, Blob, Date, URL) to plain-object
+ * Convert Effect `Redacted` values to their labeled placeholder strings and
+ * DOM-class instances (File, Blob, Date, URL) to plain-object
  * representations so the tree renderer's key-enumeration walk can see their
  * meaningful data, which otherwise lives on the prototype as getters and
  * is invisible to `Object.keys`. Recurses through arrays and records so
@@ -22,20 +23,23 @@ export declare const toInspectableValue: (value: unknown) => unknown;
 /**
  * Convert a runtime `CommandRecord` to its wire shape. Args are wrapped in an
  * `Option` so `None` cleanly distinguishes argless Commands from Commands that
- * happen to have an empty args record.
+ * happen to have an empty args record. Nested Effect `Redacted` values become
+ * their placeholder strings before transmission.
  */
 export declare const toSerializedCommand: (command: CommandRecord) => SerializedCommand;
 /**
  * Convert a runtime `MountRecord` to its wire shape. Args are wrapped in an
  * `Option` so `None` cleanly distinguishes argless Mounts from Mounts that
- * happen to have an empty args record.
+ * happen to have an empty args record. Nested Effect `Redacted` values become
+ * their placeholder strings before transmission.
  */
 export declare const toSerializedMount: (mount: MountRecord) => SerializedMount;
 /**
  * Convert a `HistoryEntry` plus its absolute index into the wire-friendly
  * `SerializedEntry` shape. Flattens the diff's `HashSet` path collections to
  * plain string arrays for JSON transmission and runs the message body through
- * `toInspectableValue` so DOM-class instances become inspectable objects.
+ * `toInspectableValue` so Effect `Redacted` values become placeholders and
+ * DOM-class instances become inspectable objects.
  */
 export declare const toSerializedEntry: (entry: HistoryEntry, index: number) => SerializedEntry;
 //# sourceMappingURL=serialize.d.ts.map

package/dist/devTools/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/devTools/serialize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EAChB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAwB1E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OAUnD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YACrB,aAAa,KACrB,iBAID,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,UAAW,WAAW,KAAG,eAGrD,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UACrB,YAAY,SACZ,MAAM,KACZ,eAoBF,CAAA"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/devTools/serialize.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EAChB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAyB1E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,OAUnD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,YACrB,aAAa,KACrB,iBAOD,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAW,WAAW,KAAG,eAMrD,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,UACrB,YAAY,SACZ,MAAM,KACZ,eAoBF,CAAA"}

package/dist/devTools/serialize.js

@@ -1,7 +1,7 @@
-import { Array, Function, Match, Option, Predicate, Record } from 'effect';
+import { Array, Function, Match, Option, Predicate, Record, Redacted, } from 'effect';
 import { extractSubmodelInfo } from './submodelPath.js';
 const inspectableCache = new WeakMap();
-const computeInspectableValue = (value) => Match.value(value).pipe(Match.when(Match.instanceOf(File), file => ({
+const computeInspectableValue = (value) => Match.value(value).pipe(Match.when(Redacted.isRedacted, globalThis.String), Match.when(Match.instanceOf(File), file => ({
     name: file.name,
     size: file.size,
     type: file.type,
@@ -11,7 +11,8 @@ const computeInspectableValue = (value) => Match.value(value).pipe(Match.when(Ma
     type: blob.type,
 })), Match.when(Match.instanceOf(Date), date => date.toISOString()), Match.when(Match.instanceOf(URL), ({ href }) => href), Match.when(globalThis.Array.isArray, Array.map(toInspectableValue)), Match.when(Predicate.isObject, Record.map(toInspectableValue)), Match.orElse(Function.identity));
 /**
- * Convert DOM-class instances (File, Blob, Date, URL) to plain-object
+ * Convert Effect `Redacted` values to their labeled placeholder strings and
+ * DOM-class instances (File, Blob, Date, URL) to plain-object
  * representations so the tree renderer's key-enumeration walk can see their
  * meaningful data, which otherwise lives on the prototype as getters and
  * is invisible to `Object.keys`. Recurses through arrays and records so
@@ -42,27 +43,30 @@ export const toInspectableValue = (value) => {
 /**
  * Convert a runtime `CommandRecord` to its wire shape. Args are wrapped in an
  * `Option` so `None` cleanly distinguishes argless Commands from Commands that
- * happen to have an empty args record.
+ * happen to have an empty args record. Nested Effect `Redacted` values become
+ * their placeholder strings before transmission.
  */
 export const toSerializedCommand = (command) => ({
     name: command.name,
-    args: Option.fromNullishOr(command.args),
+    args: Option.map(Option.fromNullishOr(command.args), Record.map(toInspectableValue)),
     maybeSubmodelPath: command.maybeSubmodelPath,
 });
 /**
  * Convert a runtime `MountRecord` to its wire shape. Args are wrapped in an
  * `Option` so `None` cleanly distinguishes argless Mounts from Mounts that
- * happen to have an empty args record.
+ * happen to have an empty args record. Nested Effect `Redacted` values become
+ * their placeholder strings before transmission.
  */
 export const toSerializedMount = (mount) => ({
     name: mount.name,
-    args: Option.fromNullishOr(mount.args),
+    args: Option.map(Option.fromNullishOr(mount.args), Record.map(toInspectableValue)),
 });
 /**
  * Convert a `HistoryEntry` plus its absolute index into the wire-friendly
  * `SerializedEntry` shape. Flattens the diff's `HashSet` path collections to
  * plain string arrays for JSON transmission and runs the message body through
- * `toInspectableValue` so DOM-class instances become inspectable objects.
+ * `toInspectableValue` so Effect `Redacted` values become placeholders and
+ * DOM-class instances become inspectable objects.
  */
 export const toSerializedEntry = (entry, index) => {
     const { submodelPath, maybeLeafTag } = extractSubmodelInfo(entry.tag, entry.message);

package/dist/experimental/index.d.ts

@@ -1,3 +1,4 @@
 export * as Machine from './machine/index.js';
+export * as Query from './query/index.js';
 export * as Server from './server/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/experimental/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/experimental/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/experimental/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAA;AAC7C,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA"}

package/dist/experimental/index.js

@@ -1,2 +1,3 @@
 export * as Machine from './machine/index.js';
+export * as Query from './query/index.js';
 export * as Server from './server/index.js';

package/dist/experimental/query/define.d.ts

@@ -0,0 +1,15 @@
+import { type KeyedQuery, type KeyedQueryConfig, type SyncFields } from './keyedQuery.js';
+import { type Query, type QueryConfig } from './query.js';
+/**
+ * Defines a Submodel that fetches data and retains it in the application
+ * Model. Add `args` to define a {@link KeyedQuery}; omit them to define a
+ * {@link Query}.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export declare function define<Name extends string, A, AI, E, EI, Fields extends SyncFields, R = never>(config: KeyedQueryConfig<Name, A, AI, E, EI, Fields, R>): KeyedQuery<Name, A, AI, E, EI, Fields, R>;
+export declare function define<Name extends string, A, AI, E, EI, R = never>(config: QueryConfig<Name, A, AI, E, EI, R> & {
+    readonly args?: never;
+    readonly toKey?: never;
+}): Query<Name, A, AI, E, EI, R>;
+//# sourceMappingURL=define.d.ts.map

package/dist/experimental/query/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/experimental/query/define.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEhB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,WAAW,EAAe,MAAM,YAAY,CAAA;AA6BtE;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,IAAI,SAAS,MAAM,EACnB,CAAC,EACD,EAAE,EACF,CAAC,EACD,EAAE,EACF,MAAM,SAAS,UAAU,EACzB,CAAC,GAAG,KAAK,EAET,MAAM,EAAE,gBAAgB,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,GACtD,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;AAC5C,wBAAgB,MAAM,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,EACjE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CACvB,GACA,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA"}

package/dist/experimental/query/define.js

@@ -0,0 +1,10 @@
+import { Predicate } from 'effect';
+import { defineKeyedQuery, } from './keyedQuery.js';
+import { defineQuery } from './query.js';
+const isKeyedQueryConfig = (config) => Predicate.hasProperty(config, 'args');
+export function define(config) {
+    if (isKeyedQueryConfig(config)) {
+        return defineKeyedQuery(config);
+    }
+    return defineQuery(config);
+}

package/dist/experimental/query/index.d.ts

@@ -0,0 +1,4 @@
+export { define } from './define.js';
+export type { KeyedQuery } from './keyedQuery.js';
+export type { Query } from './query.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/experimental/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/experimental/query/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/dist/experimental/query/index.js

@@ -0,0 +1 @@
+export { define } from './define.js';

package/dist/experimental/query/internal.d.ts

@@ -0,0 +1,57 @@
+import { Effect, Option, Schema } from 'effect';
+import * as AsyncData from '../../asyncData/index.js';
+import * as Command from '../../command/index.js';
+import * as Update from '../../update/index.js';
+export type FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage> = Pick<Update.ChildFold<ParentModel, ParentMessage, ChildModel, never, ChildMessage>, 'read' | 'write' | 'toParentMessage'>;
+export type ParentFieldOf<ParentModel, ChildModel> = Extract<{
+    [K in keyof ParentModel]-?: ParentModel[K] extends ChildModel ? K : never;
+}[keyof ParentModel], string>;
+export type ParentFieldConfig<ParentModel, ParentMessage, ChildModel, ChildMessage> = Readonly<{
+    parentField: ParentFieldOf<ParentModel, ChildModel>;
+    toParentMessage: (message: ChildMessage) => ParentMessage;
+}>;
+export type LiftConfig<ParentModel, ParentMessage, ChildModel, ChildMessage> = ParentFieldConfig<ParentModel, ParentMessage, ChildModel, ChildMessage> | FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage>;
+export type LiftQuery<ChildModel, ChildMessage, R> = {
+    <ParentModel, ParentMessage>(config: ParentFieldConfig<ParentModel, ParentMessage, ChildModel, ChildMessage>): LiftedQuery<ParentModel, ParentMessage, ChildMessage, R>;
+    <ParentModel, ParentMessage>(config: FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage>): LiftedQuery<ParentModel, ParentMessage, ChildMessage, R>;
+};
+export type LiftKeyedQuery<ChildModel, ChildMessage, Args, R> = {
+    <ParentModel, ParentMessage>(config: ParentFieldConfig<ParentModel, ParentMessage, ChildModel, ChildMessage>): LiftedKeyedQuery<ParentModel, ParentMessage, ChildMessage, Args, R>;
+    <ParentModel, ParentMessage>(config: FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage>): LiftedKeyedQuery<ParentModel, ParentMessage, ChildMessage, Args, R>;
+};
+export declare const isParentFieldConfig: <ParentModel, ParentMessage, ChildModel, ChildMessage>(config: LiftConfig<ParentModel, ParentMessage, ChildModel, ChildMessage>) => config is Extract<LiftConfig<ParentModel, ParentMessage, ChildModel, ChildMessage>, {
+    readonly parentField: string;
+}>;
+export declare const parentFieldToLens: <ParentModel extends Record<ParentFieldOf<ParentModel, ChildModel>, ChildModel>, ParentMessage, ChildModel, ChildMessage>(config: ParentFieldConfig<ParentModel, ParentMessage, ChildModel, ChildMessage>) => FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage>;
+export declare const liftChildFold: <ParentModel, ParentMessage, ChildModel, ChildMessage, Input, R>(childFold: Update.Fold<ChildModel, ChildMessage, Input, R>, lens: FoldLens<ParentModel, ParentMessage, ChildModel, ChildMessage>) => Update.Fold<ParentModel, ParentMessage, Input, R>;
+export type AsyncDataTransition = <A, E>(data: AsyncData.AsyncData<A, E>) => Option.Option<AsyncData.AsyncData<A, E>>;
+export type QueryStore<Model, Args, A, E, Message, R> = Readonly<{
+    read: (model: Model, args: Args) => AsyncData.AsyncData<A, E>;
+    start: (model: Model, args: Args, data: AsyncData.AsyncData<A, E>) => Readonly<{
+        model: Model;
+        generation: number;
+    }>;
+    fetch: (args: Args, generation: number) => Command.Command<Message, never, R>;
+}>;
+export declare const applyTransition: <Model, Args, A, E, Message, R>(store: QueryStore<Model, Args, A, E, Message, R>, model: Model, args: Args, transition: AsyncDataTransition) => Update.Return<Model, Message, R>;
+export declare const runExecute: <A, E, R>(execute: Effect.Effect<A, E, R>) => Effect.Effect<AsyncData.AsyncData<A, E>, never, R>;
+export type CompletedFetchOf<Message extends Schema.Top> = Extract<Message['Type'], {
+    readonly _tag: 'CompletedFetch';
+}>;
+export type KeyedArgs<Fields extends Schema.Struct.Fields> = Schema.Schema.Type<Schema.Struct<Fields>>;
+type LiftedQuery<ParentModel, ParentMessage, ChildMessage, R> = Readonly<{
+    fold: Update.Fold<ParentModel, ParentMessage, ChildMessage>;
+    reset: Update.Step<ParentModel, ParentMessage>;
+    revalidate: Update.Step<ParentModel, ParentMessage, R>;
+    revalidateOrLoad: Update.Step<ParentModel, ParentMessage, R>;
+    loadIfMissing: Update.Step<ParentModel, ParentMessage, R>;
+}>;
+type LiftedKeyedQuery<ParentModel, ParentMessage, ChildMessage, Args, R> = Readonly<{
+    fold: Update.Fold<ParentModel, ParentMessage, ChildMessage>;
+    reset: Update.Step<ParentModel, ParentMessage>;
+    revalidate: Update.Fold<ParentModel, ParentMessage, Args, R>;
+    revalidateOrLoad: Update.Fold<ParentModel, ParentMessage, Args, R>;
+    loadIfMissing: Update.Fold<ParentModel, ParentMessage, Args, R>;
+}>;
+export {};
+//# sourceMappingURL=internal.d.ts.map

package/dist/experimental/query/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/experimental/query/internal.ts"],"names":[],"mappings":"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"}

package/dist/experimental/query/internal.js

@@ -0,0 +1,25 @@
+import { Effect, Option, Predicate, pipe } from 'effect';
+import * as AsyncData from '../../asyncData/index.js';
+import * as Update from '../../update/index.js';
+export const isParentFieldConfig = (config) => Predicate.hasProperty(config, 'parentField');
+const setField = (model, field, value) => ({ ...model, [field]: value });
+export const parentFieldToLens = (config) => ({
+    read: (model) => Option.some(model[config.parentField]),
+    write: (model, nextChild) => setField(model, config.parentField, nextChild),
+    toParentMessage: config.toParentMessage,
+});
+export const liftChildFold = (childFold, lens) => Update.foldChild({
+    update: (childModel, input) => childFold(childModel, input),
+    ...lens,
+});
+export const applyTransition = (store, model, args, transition) => Option.match(transition(store.read(model, args)), {
+    onNone: () => ({ model }),
+    onSome: nextData => {
+        const queryStart = store.start(model, args, nextData);
+        return {
+            model: queryStart.model,
+            commands: [store.fetch(args, queryStart.generation)],
+        };
+    },
+});
+export const runExecute = (execute) => pipe(execute, Effect.result, Effect.map(result => AsyncData.settle(AsyncData.Loading(), result)));

package/dist/experimental/query/keyedQuery.d.ts

@@ -0,0 +1,89 @@
+import { Effect, Schema } from 'effect';
+import * as AsyncData from '../../asyncData/index.js';
+import * as Command from '../../command/index.js';
+import * as Update from '../../update/index.js';
+import { type CompletedFetchOf, type KeyedArgs, type LiftKeyedQuery } from './internal.js';
+export type SyncFields = {
+    readonly [x: PropertyKey]: Schema.Codec<unknown, unknown, never, never>;
+};
+export type KeyedQueryConfig<Name extends string, A, AI, E, EI, Fields extends SyncFields, R> = Readonly<{
+    name: Name;
+    data: Schema.Codec<A, AI, never, never>;
+    error: Schema.Codec<E, EI, never, never>;
+    args: Fields;
+    toKey?: (args: Schema.Schema.Type<Schema.Struct<Fields>>) => string;
+    execute: (args: Schema.Schema.Type<Schema.Struct<Fields>>) => Effect.Effect<A, E, R>;
+}>;
+declare const makeKeyedQueryMessage: <A, AI, E, EI, Fields extends SyncFields>(data: Schema.Codec<A, AI>, error: Schema.Codec<E, EI>, Args: Schema.Struct<Fields>) => import("../../schema/index.js").MessageUnion<{
+    readonly CompletedFetch: {
+        args: Schema.Struct<Fields>;
+        generation: Schema.Number;
+        result: Schema.Result<Schema.Codec<A, AI, never, never>, Schema.Codec<E, EI, never, never>>;
+    };
+}>;
+/**
+ * Schema-backed Message union dispatched when a KeyedQuery fetch completes.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export type KeyedQueryMessage<A, AI, E, EI, Fields extends SyncFields> = ReturnType<typeof makeKeyedQueryMessage<A, AI, E, EI, Fields>>;
+/** Builds the Model Schema for a KeyedQuery. */
+export declare const makeKeyedQueryModel: <A, AI, E, EI, Fields extends SyncFields>(data: Schema.Codec<A, AI>, error: Schema.Codec<E, EI>, Args: Schema.Struct<Fields>) => Schema.Struct<{
+    readonly generation: Schema.Number;
+    readonly entries: Schema.HashMap<Schema.String, Schema.Struct<{
+        readonly args: Schema.Struct<Fields>;
+        readonly data: Schema.Codec<AsyncData.AsyncData<A, E>, AsyncData.AsyncDataEncoded<AI, EI>, never, never>;
+        readonly generation: Schema.Number;
+    }>>;
+}>;
+/**
+ * Model Schema for a KeyedQuery containing retained `AsyncData` entries.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export type KeyedQueryModel<A, AI, E, EI, Fields extends SyncFields> = ReturnType<typeof makeKeyedQueryModel<A, AI, E, EI, Fields>>;
+/**
+ * Submodel for fetching and retaining `AsyncData` values by argument key.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export interface KeyedQuery<Name extends string, A, AI, E, EI, Fields extends SyncFields, R = never> {
+    /** Schema for this KeyedQuery's Model. */
+    readonly Model: KeyedQueryModel<A, AI, E, EI, Fields>;
+    /** Schema-backed union of Messages handled by this KeyedQuery. */
+    readonly Message: KeyedQueryMessage<A, AI, E, EI, Fields>;
+    /**
+     * Command definition for matching this KeyedQuery's pending fetch in Story
+     * and Scene tests. Start fetches through a loading operation so the Model
+     * and request generation advance together; do not call this directly.
+     */
+    readonly Fetch: Command.CommandDefinitionWithArgs<`Fetch${Name}`, {
+        readonly args: Schema.Struct<Fields>;
+        readonly generation: typeof Schema.Number;
+    }, Effect.Effect<CompletedFetchOf<KeyedQueryMessage<A, AI, E, EI, Fields>>, never, R>>;
+    /**
+     * Creates a KeyedQuery Model for initial parent Model construction. Never
+     * replace a live KeyedQuery with `init()`: it can reuse an in-flight request
+     * generation. Use `reset` instead.
+     */
+    readonly init: () => KeyedQueryModel<A, AI, E, EI, Fields>['Type'];
+    /** Clears every entry while preserving request identity. */
+    readonly reset: (model: KeyedQueryModel<A, AI, E, EI, Fields>['Type']) => Update.Return<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type']>;
+    /** Reads one entry, returning `Idle` when that entry does not exist. */
+    readonly read: (model: KeyedQueryModel<A, AI, E, EI, Fields>['Type'], args: KeyedArgs<Fields>) => AsyncData.AsyncData<A, E>;
+    /** Folds a keyed Fetch completion into the matching entry. */
+    readonly update: (model: KeyedQueryModel<A, AI, E, EI, Fields>['Type'], message: KeyedQueryMessage<A, AI, E, EI, Fields>['Type']) => Update.Return<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type']>;
+    /** Refreshes a loaded entry and does nothing when it has no data. */
+    readonly revalidate: Update.Fold<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type'], KeyedArgs<Fields>, R>;
+    /** Loads a missing entry or refreshes a loaded entry. */
+    readonly revalidateOrLoad: Update.Fold<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type'], KeyedArgs<Fields>, R>;
+    /** Loads an entry only when it has no usable value. */
+    readonly loadIfMissing: Update.Fold<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type'], KeyedArgs<Fields>, R>;
+    /** Lifts this KeyedQuery's update and loading operations into a parent Model. */
+    readonly lift: LiftKeyedQuery<KeyedQueryModel<A, AI, E, EI, Fields>['Type'], KeyedQueryMessage<A, AI, E, EI, Fields>['Type'], KeyedArgs<Fields>, R>;
+    /** Executes one keyed fetch directly and returns settled `AsyncData`. */
+    readonly run: (args: KeyedArgs<Fields>) => Effect.Effect<AsyncData.AsyncData<A, E>, never, R>;
+}
+export declare function defineKeyedQuery<Name extends string, A, AI, E, EI, Fields extends SyncFields, R>(config: KeyedQueryConfig<Name, A, AI, E, EI, Fields, R>): KeyedQuery<Name, A, AI, E, EI, Fields, R>;
+export {};
+//# sourceMappingURL=keyedQuery.d.ts.map

package/dist/experimental/query/keyedQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedQuery.d.ts","sourceRoot":"","sources":["../../../src/experimental/query/keyedQuery.ts"],"names":[],"mappings":"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"}

package/dist/experimental/query/keyedQuery.js

@@ -0,0 +1,144 @@
+import { Array, Effect, Function, HashMap, Number, Option, Order, Predicate, Record, Schema, pipe, } from 'effect';
+import * as AsyncData from '../../asyncData/index.js';
+import * as Command from '../../command/index.js';
+import { defineMessageUnion } from '../../message/index.js';
+import { modifyFields } from '../../struct/index.js';
+import * as Update from '../../update/index.js';
+import { applyTransition, isParentFieldConfig, liftChildFold, parentFieldToLens, runExecute, } from './internal.js';
+const canonicalizeJsonEntry = ([key, value]) => [key, canonicalizeJson(value)];
+const jsonEntryOrder = Order.mapInput(Order.String, ([key]) => key);
+const isJsonObject = (value) => Predicate.isObject(value) && !globalThis.Array.isArray(value);
+const canonicalizeJson = (value) => {
+    if (globalThis.Array.isArray(value)) {
+        return Array.map(value, canonicalizeJson);
+    }
+    if (isJsonObject(value)) {
+        return pipe(value, Record.toEntries, Array.sort(jsonEntryOrder), Array.map(canonicalizeJsonEntry), Record.fromEntries);
+    }
+    return value;
+};
+const encodeJsonString = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Json));
+const encodeKey = (schema) => {
+    const encodeJson = Schema.encodeUnknownSync(Schema.toCodecJson(schema));
+    return (value) => encodeJsonString(canonicalizeJson(encodeJson(value)));
+};
+const makeKeyedQueryMessage = (data, error, Args) => defineMessageUnion({
+    CompletedFetch: {
+        args: Args,
+        generation: Schema.Number,
+        result: Schema.Result(data, error),
+    },
+});
+/** Builds the Model Schema for a KeyedQuery. */
+export const makeKeyedQueryModel = (data, error, Args) => {
+    const asyncData = AsyncData.Schema(data, error);
+    return Schema.Struct({
+        generation: Schema.Number,
+        entries: Schema.HashMap(Schema.String, Schema.Struct({
+            args: Args,
+            data: asyncData.schema,
+            generation: Schema.Number,
+        })),
+    });
+};
+export function defineKeyedQuery(config) {
+    const asyncData = AsyncData.Schema(config.data, config.error);
+    const Args = Schema.Struct(config.args);
+    if (Array.isArrayEmpty(Record.keys(config.args))) {
+        throw new Error(`Query.define("${config.name}"): keyed args must include at least one field`);
+    }
+    const argsToKey = config.toKey ?? encodeKey(Args);
+    const Message = makeKeyedQueryMessage(config.data, config.error, Args);
+    const Fetch = Command.define(`Fetch${config.name}`, {
+        args: { args: Args, generation: Schema.Number },
+        messages: [Message.CompletedFetch],
+        execute: ({ args, generation }) => pipe(config.execute(args), Effect.result, Effect.map((result) => 
+        // NOTE: CompletedFetch's constructor input view rejects args that are already the decoded Type.
+        ({
+            _tag: 'CompletedFetch',
+            args,
+            generation,
+            result,
+        }))),
+    });
+    const Model = makeKeyedQueryModel(config.data, config.error, Args);
+    const store = {
+        read: (model, args) => AsyncData.fromOptionOrIdle(Option.map(HashMap.get(model.entries, argsToKey(args)), entry => entry.data)),
+        start: (model, args, data) => {
+            const nextGeneration = Number.increment(model.generation);
+            return {
+                model: modifyFields(model, {
+                    entries: HashMap.set(argsToKey(args), {
+                        args,
+                        data,
+                        generation: nextGeneration,
+                    }),
+                    generation: () => nextGeneration,
+                }),
+                generation: nextGeneration,
+            };
+        },
+        fetch: (args, generation) => Fetch({ args, generation }),
+    };
+    const init = () => Model.make({ entries: HashMap.empty(), generation: 0 });
+    const reset = (model) => ({
+        model: modifyFields(model, { entries: () => HashMap.empty() }),
+    });
+    const read = (model, args) => store.read(model, args);
+    const liftTransition = (transition) => Function.dual(2, (model, args) => applyTransition(store, model, args, transition));
+    const revalidate = liftTransition(AsyncData.revalidate);
+    const revalidateOrLoad = liftTransition(AsyncData.revalidateOrLoad);
+    const loadIfMissing = liftTransition(AsyncData.loadIfMissing);
+    const update = (model, message) => Message.match(message, {
+        CompletedFetch({ args, generation, result }) {
+            const key = argsToKey(args);
+            const maybeEntry = HashMap.get(model.entries, key);
+            if (Option.isNone(maybeEntry)) {
+                return { model };
+            }
+            const entry = maybeEntry.value;
+            if (!AsyncData.isPending(entry.data) ||
+                generation !== entry.generation) {
+                return { model };
+            }
+            return {
+                model: modifyFields(model, {
+                    entries: HashMap.set(key, modifyFields(entry, {
+                        data: () => AsyncData.settle(entry.data, result),
+                    })),
+                }),
+            };
+        },
+    });
+    const liftFromLens = (lens) => ({
+        fold: Update.foldChild({ update, ...lens }),
+        reset: Update.foldChildStep({
+            update: reset,
+            ...lens,
+        }),
+        revalidate: liftChildFold(revalidate, lens),
+        revalidateOrLoad: liftChildFold(revalidateOrLoad, lens),
+        loadIfMissing: liftChildFold(loadIfMissing, lens),
+    });
+    function lift(config) {
+        if (isParentFieldConfig(config)) {
+            return liftFromLens(parentFieldToLens(config));
+        }
+        return liftFromLens(config);
+    }
+    const run = (args) => runExecute(config.execute(args));
+    return {
+        Model,
+        Message,
+        Fetch,
+        init,
+        reset,
+        read,
+        update,
+        revalidate,
+        revalidateOrLoad,
+        loadIfMissing,
+        lift,
+        run,
+    };
+}

package/dist/experimental/query/public.d.ts

@@ -0,0 +1,4 @@
+export { define } from './index.js';
+export type { KeyedQuery } from './keyedQuery.js';
+export type { Query } from './query.js';
+//# sourceMappingURL=public.d.ts.map

package/dist/experimental/query/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/experimental/query/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/dist/experimental/query/public.js

@@ -0,0 +1 @@
+export { define } from './index.js';

package/dist/experimental/query/query.d.ts

@@ -0,0 +1,78 @@
+import { Effect, Schema } from 'effect';
+import * as AsyncData from '../../asyncData/index.js';
+import * as Command from '../../command/index.js';
+import * as Update from '../../update/index.js';
+import { type CompletedFetchOf, type LiftQuery } from './internal.js';
+export type QueryConfig<Name extends string, A, AI, E, EI, R> = Readonly<{
+    name: Name;
+    data: Schema.Codec<A, AI, never, never>;
+    error: Schema.Codec<E, EI, never, never>;
+    execute: Effect.Effect<A, E, R>;
+}>;
+declare const makeQueryMessage: <A, AI, E, EI>(data: Schema.Codec<A, AI>, error: Schema.Codec<E, EI>) => import("../../schema/index.js").MessageUnion<{
+    readonly CompletedFetch: {
+        generation: Schema.Number;
+        result: Schema.Result<Schema.Codec<A, AI, never, never>, Schema.Codec<E, EI, never, never>>;
+    };
+}>;
+/**
+ * Schema-backed Message union dispatched when a Query Fetch completes.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export type QueryMessage<A, AI, E, EI> = ReturnType<typeof makeQueryMessage<A, AI, E, EI>>;
+/** Builds the Model Schema for a Query. */
+export declare const makeQueryModel: <A, AI, E, EI>(data: Schema.Codec<A, AI>, error: Schema.Codec<E, EI>) => Schema.Struct<{
+    readonly data: Schema.Codec<AsyncData.AsyncData<A, E>, AsyncData.AsyncDataEncoded<AI, EI>, never, never>;
+    readonly generation: Schema.Number;
+}>;
+/**
+ * Model Schema for a Query containing one `AsyncData` value.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export type QueryModel<A, AI, E, EI> = ReturnType<typeof makeQueryModel<A, AI, E, EI>>;
+/**
+ * Submodel for fetching and retaining one `AsyncData` value.
+ *
+ * @experimental Ships from `foldkit/experimental/query`; expect breaking changes while the API settles.
+ */
+export interface Query<Name extends string, A, AI, E, EI, R = never> {
+    /** Schema for this Query's Model. */
+    readonly Model: QueryModel<A, AI, E, EI>;
+    /** Schema-backed union of Messages handled by this Query. */
+    readonly Message: QueryMessage<A, AI, E, EI>;
+    /**
+     * Command definition for matching this Query's pending fetch in Story and
+     * Scene tests. Start fetches through a loading operation so the Model and
+     * request generation advance together; do not call this directly.
+     */
+    readonly Fetch: Command.CommandDefinitionWithArgs<`Fetch${Name}`, {
+        readonly generation: typeof Schema.Number;
+    }, Effect.Effect<CompletedFetchOf<QueryMessage<A, AI, E, EI>>, never, R>>;
+    /**
+     * Creates a Query Model for initial parent Model construction. Never replace
+     * a live Query with `init()`: it can reuse an in-flight request generation.
+     * Use `reset` instead.
+     */
+    readonly init: () => QueryModel<A, AI, E, EI>['Type'];
+    /** Clears the Query while preserving its request identity. */
+    readonly reset: (model: QueryModel<A, AI, E, EI>['Type']) => Update.Return<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type']>;
+    /** Reads the `AsyncData` value from the Query Model. */
+    readonly read: (model: QueryModel<A, AI, E, EI>['Type']) => AsyncData.AsyncData<A, E>;
+    /** Folds a Fetch completion into the Query Model. */
+    readonly update: (model: QueryModel<A, AI, E, EI>['Type'], message: QueryMessage<A, AI, E, EI>['Type']) => Update.Return<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type']>;
+    /** Refreshes loaded data and does nothing when no data is present. */
+    readonly revalidate: (model: QueryModel<A, AI, E, EI>['Type']) => Update.Return<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type'], R>;
+    /** Loads missing data or refreshes loaded data. */
+    readonly revalidateOrLoad: (model: QueryModel<A, AI, E, EI>['Type']) => Update.Return<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type'], R>;
+    /** Loads data only when the Query has no usable value. */
+    readonly loadIfMissing: (model: QueryModel<A, AI, E, EI>['Type']) => Update.Return<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type'], R>;
+    /** Lifts this Query's update and loading operations into a parent Model. */
+    readonly lift: LiftQuery<QueryModel<A, AI, E, EI>['Type'], QueryMessage<A, AI, E, EI>['Type'], R>;
+    /** Executes the configured fetch directly and returns settled `AsyncData`. */
+    readonly run: Effect.Effect<AsyncData.AsyncData<A, E>, never, R>;
+}
+export declare function defineQuery<Name extends string, A, AI, E, EI, R>(config: QueryConfig<Name, A, AI, E, EI, R>): Query<Name, A, AI, E, EI, R>;
+export {};
+//# sourceMappingURL=query.d.ts.map