foldkit 0.121.0 → 0.122.0

package/dist/asyncData/asyncData.js

@@ -0,0 +1,415 @@
+import { Array, Function, Match as M, Option, Predicate, Result, Schema as S, } from 'effect';
+import { ts } from '../schema/index.js';
+/** Constructs the `Idle` state. A parameter-free callable Schema, so it can
+ *  also serve as a Union member. */
+export const Idle = ts('Idle');
+/** Constructs the `Loading` state. A parameter-free callable Schema, so it
+ *  can also serve as a Union member. */
+export const Loading = ts('Loading');
+/** Constructs a `Refreshing` state holding the previous good data. Plain
+ *  value builder, generic in `A`; use the `Schema` factory's `Refreshing`
+ *  for a Schema-bound constructor. */
+export const Refreshing = (payload) => ({
+    _tag: 'Refreshing',
+    data: payload.data,
+});
+/** Constructs a `Failure` state carrying the error only. Plain value
+ *  builder, generic in `E`; use the `Schema` factory's `Failure` for a
+ *  Schema-bound constructor. */
+export const Failure = (payload) => ({
+    _tag: 'Failure',
+    error: payload.error,
+});
+/** Constructs a `Stale` state carrying both the refresh error and the
+ *  last good data. Plain value builder, generic in `A` and `E`; use the
+ *  `Schema` factory's `Stale` for a Schema-bound constructor. */
+export const Stale = (payload) => ({
+    _tag: 'Stale',
+    error: payload.error,
+    data: payload.data,
+});
+/** Constructs a `Success` state holding the data. Plain value builder,
+ *  generic in `A`; use the `Schema` factory's `Success` for a Schema-bound
+ *  constructor. */
+export const Success = (payload) => ({
+    _tag: 'Success',
+    data: payload.data,
+});
+/** Bare-value alias for `Success({ data })`, mirroring `Result.succeed`. */
+export const succeed = (data) => Success({ data });
+/** Bare-value alias for `Failure({ error })`, mirroring `Result.fail`. */
+export const fail = (error) => Failure({ error });
+/** Builds the six-state `AsyncData` Schema for the given data and error
+ *  Schemas (value-first). Put `schema` in your Model; use the returned
+ *  constructors when you want ones typed to this instance's `A` and `E`.
+ *
+ *  @example
+ *  ```ts
+ *  import { AsyncData } from 'foldkit'
+ *  import { Schema as S } from 'effect'
+ *
+ *  const Note = S.Struct({ id: S.String, body: S.String })
+ *  const Notes = AsyncData.Schema(S.Array(Note), S.String)
+ *
+ *  // Model field: typeof Notes.schema.Type
+ *  const initial = AsyncData.Idle()
+ *  const loaded = Notes.Success({ data: [] })
+ *  ```
+ */
+export const Schema = (dataSchema, errorSchema) => {
+    const RefreshingSchema = ts('Refreshing', { data: dataSchema });
+    const FailureSchema = ts('Failure', { error: errorSchema });
+    const StaleSchema = ts('Stale', { error: errorSchema, data: dataSchema });
+    const SuccessSchema = ts('Success', { data: dataSchema });
+    const schema = S.Union([
+        Idle,
+        Loading,
+        RefreshingSchema,
+        FailureSchema,
+        StaleSchema,
+        SuccessSchema,
+    ]);
+    return {
+        schema,
+        Idle,
+        Loading,
+        Refreshing: RefreshingSchema,
+        Failure: FailureSchema,
+        Stale: StaleSchema,
+        Success: SuccessSchema,
+    };
+};
+// OPERATION
+/** Handles all six states exhaustively, passing each handler its unwrapped
+ *  payload. `onStale` alone receives the whole `{ error, data }` payload
+ *  object because `Stale` carries two fields. Use `matchData` when the view
+ *  does not care which of the data-bearing states it is rendering.
+ *
+ *  @example
+ *  ```ts
+ *  import { AsyncData } from 'foldkit'
+ *
+ *  AsyncData.match(notes, {
+ *    onIdle: () => 'Not loaded',
+ *    onLoading: () => 'Loading',
+ *    onRefreshing: notes => `Refreshing ${notes.length} notes`,
+ *    onFailure: error => `Failed: ${error}`,
+ *    onStale: ({ error, data }) => `${data.length} notes (stale: ${error})`,
+ *    onSuccess: notes => `${notes.length} notes`,
+ *  })
+ *  ```
+ */
+// NOTE: match, matchData, matchDataSplit, getData, and getError use
+// refinement chains instead of Match because tagsExhaustive returns
+// Unify<B>, which does not reduce when the handlers return a caller's
+// naked generic in effect 4.0.0-beta.88. Combinators whose handlers
+// return concrete AsyncData shapes use Match as usual.
+export const match = Function.dual(2, (self, handlers) => {
+    if (isIdle(self)) {
+        return handlers.onIdle();
+    }
+    if (isLoading(self)) {
+        return handlers.onLoading();
+    }
+    if (isRefreshing(self)) {
+        return handlers.onRefreshing(self.data);
+    }
+    if (isFailure(self)) {
+        return handlers.onFailure(self.error);
+    }
+    if (isStale(self)) {
+        return handlers.onStale({ error: self.error, data: self.data });
+    }
+    return handlers.onSuccess(self.data);
+});
+/** Collapses the six states to the three channels a view usually renders:
+ *  `onData` spans the data-bearing states (`Success`, `Refreshing`,
+ *  `Stale`), `onFailure` receives the `Failure` error, and `onEmpty` covers
+ *  `Idle` and `Loading` together. A `Stale` renders through `onData` so its
+ *  data stays on screen. Use `matchDataSplit` when `Idle` and `Loading`
+ *  render differently, and `match` when the stale error or the `Refreshing`
+ *  signal matters. */
+export const matchData = Function.dual(2, (self, handlers) => {
+    const maybeData = getData(self);
+    if (Option.isSome(maybeData)) {
+        return handlers.onData(maybeData.value);
+    }
+    if (isFailure(self)) {
+        return handlers.onFailure(self.error);
+    }
+    return handlers.onEmpty();
+});
+/** Like `matchData`, but the two cold states are split: `onIdle` handles
+ *  `Idle` and `onLoading` handles `Loading`, for views that render nothing
+ *  requested yet differently from a request in flight. `onData` and
+ *  `onFailure` behave exactly as in `matchData`. */
+export const matchDataSplit = Function.dual(2, (self, handlers) => {
+    const maybeData = getData(self);
+    if (Option.isSome(maybeData)) {
+        return handlers.onData(maybeData.value);
+    }
+    if (isFailure(self)) {
+        return handlers.onFailure(self.error);
+    }
+    if (isLoading(self)) {
+        return handlers.onLoading();
+    }
+    return handlers.onIdle();
+});
+/** Maps the data of all three data-bearing states, preserving each tag so
+ *  the `Refreshing` and `Stale` signals survive a pure transform. `Stale`
+ *  maps only its `data`, keeping its `error`. The no-data states pass
+ *  through unchanged. */
+export const map = Function.dual(2, (self, f) => M.value(self).pipe(M.withReturnType(), M.tagsExhaustive({
+    Idle: idle => idle,
+    Loading: loading => loading,
+    Refreshing: ({ data }) => Refreshing({ data: f(data) }),
+    Failure: failure => failure,
+    Stale: ({ error, data }) => Stale({ error, data: f(data) }),
+    Success: ({ data }) => Success({ data: f(data) }),
+})));
+/** Maps the error of the two error-bearing states: `Failure` and `Stale`
+ *  transform (`Stale` keeps its `data`), everything else passes through.
+ *  Use it to unify heterogeneous error types before a combine. */
+export const mapError = Function.dual(2, (self, f) => M.value(self).pipe(M.withReturnType(), M.tagsExhaustive({
+    Idle: idle => idle,
+    Loading: loading => loading,
+    Refreshing: refreshing => refreshing,
+    Failure: ({ error }) => Failure({ error: f(error) }),
+    Stale: ({ error, data }) => Stale({ error: f(error), data }),
+    Success: success => success,
+})));
+/** Maps both channels with channel-named handlers: `onData` spans `Success`,
+ *  `Refreshing`, and `Stale`; `onError` spans `Failure` and `Stale`. For
+ *  `Stale`, both handlers apply. Tags are preserved. */
+export const mapBoth = Function.dual(2, (self, handlers) => M.value(self).pipe(M.withReturnType(), M.tagsExhaustive({
+    Idle: idle => idle,
+    Loading: loading => loading,
+    Refreshing: ({ data }) => Refreshing({ data: handlers.onData(data) }),
+    Failure: ({ error }) => Failure({ error: handlers.onError(error) }),
+    Stale: ({ error, data }) => Stale({
+        error: handlers.onError(error),
+        data: handlers.onData(data),
+    }),
+    Success: ({ data }) => Success({ data: handlers.onData(data) }),
+})));
+/** Treats every data-bearing state (`Success`, `Refreshing`, `Stale`)
+ *  exactly like `Success(data)`: returns `f(data)` unchanged, dropping the
+ *  tag and any `Stale` error, so a caller can settle in-flight or stale data
+ *  into `Success`. The no-data states pass through. Widens the error channel
+ *  to `E | E2`, matching `Result.flatMap`. */
+export const flatMap = Function.dual(2, (self, f) => M.value(self).pipe(M.withReturnType(), M.tagsExhaustive({
+    Idle: idle => idle,
+    Loading: loading => loading,
+    Refreshing: ({ data }) => f(data),
+    Failure: failure => failure,
+    Stale: ({ data }) => f(data),
+    Success: ({ data }) => f(data),
+})));
+/** Returns the data as an `Option`, spanning all three data-bearing states:
+ *  `Some` for `Success`, `Refreshing`, and `Stale`, `None` otherwise.
+ *  Payload-named because it deliberately spans three tags. */
+export const getData = (self) => {
+    if (isSuccess(self) || isRefreshing(self) || isStale(self)) {
+        return Option.some(self.data);
+    }
+    return Option.none();
+};
+/** Returns the error as an `Option`, spanning both error-bearing states:
+ *  `Some` for `Failure` and `Stale`, `None` otherwise. Symmetric with
+ *  `getData`. */
+export const getError = (self) => {
+    if (isFailure(self) || isStale(self)) {
+        return Option.some(self.error);
+    }
+    return Option.none();
+};
+/** Returns the data of any data-bearing state, or `onEmpty()` for the three
+ *  no-data states. The fallback is a nullary thunk, mirroring
+ *  `Option.getOrElse`, because the no-data states collapse to empty with no
+ *  single payload. */
+export const getOrElse = Function.dual(2, (self, onEmpty) => Option.getOrElse(getData(self), onEmpty));
+/** Returns `true` only for the `Idle` state. Refinement. */
+export const isIdle = (self) => self._tag === 'Idle';
+/** Returns `true` only for the empty `Loading` state, not `Refreshing`.
+ *  Refinement. */
+export const isLoading = (self) => self._tag === 'Loading';
+/** Returns `true` only for the `Refreshing` state. Refinement. */
+export const isRefreshing = (self) => self._tag === 'Refreshing';
+/** Returns `true` only for the `Failure` state, not `Stale`. Refinement. */
+export const isFailure = (self) => self._tag === 'Failure';
+/** Returns `true` only for the `Stale` state: a failed refresh holding the
+ *  last good data. Refinement. */
+export const isStale = (self) => self._tag === 'Stale';
+/** Returns `true` only for the `Success` state, not `Refreshing` or
+ *  `Stale`. Refinement. */
+export const isSuccess = (self) => self._tag === 'Success';
+/** Returns `true` when the state holds data: `Success`, `Refreshing`, or
+ *  `Stale`. */
+export const hasData = (self) => Option.isSome(getData(self));
+/** Returns `true` when the state carries an error: `Failure` or `Stale`.
+ *  The error-channel twin of `hasData`. */
+export const hasError = (self) => Option.isSome(getError(self));
+/** Returns `true` when a request is in flight: `Loading` or `Refreshing`
+ *  only. `Stale` is not pending because its fetch already failed. Use for a
+ *  spinner regardless of held data. */
+export const isPending = (self) => isLoading(self) || isRefreshing(self);
+const stateTags = [
+    'Idle',
+    'Loading',
+    'Refreshing',
+    'Failure',
+    'Stale',
+    'Success',
+];
+/** Type guard on `unknown`: checks that the value has a `_tag` belonging to
+ *  the six `AsyncData` states. */
+export const isAsyncData = (input) => Predicate.hasProperty(input, '_tag') &&
+    Predicate.isString(input._tag) &&
+    Array.contains(stateTags, input._tag);
+/** Returns `self` when it holds data (`Success`, `Refreshing`, or `Stale`),
+ *  otherwise `that()`. The recovery and cache-fallback combinator: recover
+ *  an `Idle`, `Loading`, or `Failure` into a secondary source without
+ *  `match`. */
+export const orElse = Function.dual(2, (self, that) => (hasData(self) ? self : that()));
+/** The revalidate-on-entry transition: revalidates loaded data and loads
+ *  cold data. The data-bearing loaded states (`Success`, `Stale`) move to
+ *  `Refreshing`; the cold no-data states (`Idle`, `Failure`) start a fresh
+ *  `Loading`; the already-pending states (`Loading`, `Refreshing`) yield
+ *  `None` so the request in flight is not restarted. `None` means no
+ *  transition, and no load Command, is needed. */
+export const revalidateOrLoad = (self) => M.value(self).pipe(M.withReturnType(), M.tagsExhaustive({
+    Idle: () => Option.some(Loading()),
+    Loading: () => Option.none(),
+    Refreshing: () => Option.none(),
+    Failure: () => Option.some(Loading()),
+    Stale: ({ data }) => Option.some(Refreshing({ data })),
+    Success: ({ data }) => Option.some(Refreshing({ data })),
+}));
+/** The loaded-only revalidation transition: `Success` and `Stale` move to
+ *  `Refreshing`, every other state yields `None`. Unlike
+ *  `revalidateOrLoad` there is no cold-start `Loading`, so only caches
+ *  that actually hold data revalidate; this is the generic refresher path
+ *  after a mutation. */
+export const revalidate = (self) => M.value(self).pipe(M.tag('Success', 'Stale', ({ data }) => Refreshing({ data })), M.option);
+/** Combines two values under the two-tier lattice
+ *  `Failure > Loading > Idle > Stale > Refreshing > Success`. If either
+ *  input is a no-data state, the highest-ranked such state wins with no
+ *  combination (`self`'s error wins when both are `Failure`). Otherwise both
+ *  hold data: combine with `f` and tag the result with the highest-ranked
+ *  data state present (`self`'s error wins when both are `Stale`).
+ *
+ *  Because the combined value needs both inputs' data, a single no-data
+ *  input collapses the whole combine to that state:
+ *  `zipWith(Idle(), Success({ data }), f)` yields `Idle`. */
+export const zipWith = Function.dual(3, (self, that, f) => {
+    if (isFailure(self)) {
+        return self;
+    }
+    if (isFailure(that)) {
+        return that;
+    }
+    if (isLoading(self) || isLoading(that)) {
+        return Loading();
+    }
+    if (isIdle(self) || isIdle(that)) {
+        return Idle();
+    }
+    const data = f(self.data, that.data);
+    if (isStale(self)) {
+        return Stale({ error: self.error, data });
+    }
+    if (isStale(that)) {
+        return Stale({ error: that.error, data });
+    }
+    if (isRefreshing(self) || isRefreshing(that)) {
+        return Refreshing({ data });
+    }
+    return Success({ data });
+});
+const combineLattice = (states, combineData) => {
+    const maybeFailure = Array.findFirst(states, isFailure);
+    if (Option.isSome(maybeFailure)) {
+        return maybeFailure.value;
+    }
+    if (Array.some(states, isLoading)) {
+        return Loading();
+    }
+    if (Array.some(states, isIdle)) {
+        return Idle();
+    }
+    const data = combineData(Array.getSomes(Array.map(states, getData)));
+    const maybeStale = Array.findFirst(states, isStale);
+    if (Option.isSome(maybeStale)) {
+        return Stale({ error: maybeStale.value.error, data });
+    }
+    if (Array.some(states, isRefreshing)) {
+        return Refreshing({ data });
+    }
+    return Success({ data });
+};
+const allIterable = (inputs) => combineLattice(Array.fromIterable(inputs), Function.identity);
+const allRecord = (inputs) => {
+    const entries = Object.entries(inputs);
+    const keys = Array.map(entries, ([key]) => key);
+    const states = Array.map(entries, ([, state]) => state);
+    return combineLattice(states, datas => Object.fromEntries(Array.zip(keys, datas)));
+};
+/** Combines an iterable or record of values under the `zipWith` lattice.
+ *  An iterable collapses to an in-order array of data (empty input yields
+ *  `Success({ data: [] })`); a record builds a struct (empty input yields
+ *  `Success({ data: {} })`). The highest-ranked no-data state blocks, the
+ *  leftmost `Failure` error wins, and any `Stale` in an all-data set makes
+ *  the result `Stale` with the leftmost `Stale` error. All inputs must share
+ *  one error type; unify with `mapError` first.
+ *
+ *  The record form is the multi-resource screen:
+ *  `all({ user, orders, prefs })` combines into one value whose data is the
+ *  struct of all datas. */
+export const all = (inputs) => {
+    if (Symbol.iterator in inputs) {
+        return allIterable(inputs);
+    }
+    return allRecord(inputs);
+};
+/** Folds a settled `Result` into the previous state, keeping the last good
+ *  data: a `Result` success becomes `Success`, and a `Result` failure
+ *  becomes `Stale({ error, data })` when `self` holds data, else a bare
+ *  `Failure`. The primary way to fold a fetch back into the Model, and the
+ *  reason a failed refresh keeps data on screen: without `settle`, every
+ *  fetch needs a success arm and a failure arm that hand-assemble
+ *  `Success`, `Stale`, and `Failure` from the previous state. When a
+ *  failure should deliberately drop the previous data, match on the
+ *  `Result` directly and build the `Failure` explicitly.
+ *
+ *  @example
+ *  ```ts
+ *  import { Effect, pipe } from 'effect'
+ *  import { AsyncData, Command } from 'foldkit'
+ *
+ *  // The Command settles the fetch into a Result instead of throwing:
+ *  const LoadNotes = Command.define(
+ *    'LoadNotes',
+ *    SettledLoadNotes,
+ *  )(
+ *    pipe(
+ *      fetchNotes,
+ *      Effect.result,
+ *      Effect.map(result => SettledLoadNotes({ result })),
+ *    ),
+ *  )
+ *
+ *  // One update arm folds it in, whatever the previous state was:
+ *  SettledLoadNotes: ({ result }) => [
+ *    evo(model, { notes: AsyncData.settle(result) }),
+ *    [],
+ *  ]
+ *  ```
+ */
+export const settle = Function.dual(2, (self, result) => Result.match(result, {
+    onSuccess: data => Success({ data }),
+    onFailure: error => Option.match(getData(self), {
+        onNone: () => Failure({ error }),
+        onSome: data => Stale({ error, data }),
+    }),
+}));

package/dist/asyncData/index.d.ts

@@ -0,0 +1,2 @@
+export * from './asyncData.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asyncData/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}

package/dist/asyncData/index.js

@@ -0,0 +1 @@
+export * from './asyncData.js';

package/dist/asyncData/public.d.ts

@@ -0,0 +1,3 @@
+export { Idle, Loading, Refreshing, Failure, Stale, Success, succeed, fail, Schema, match, matchData, matchDataSplit, map, mapError, mapBoth, flatMap, getData, getError, getOrElse, isIdle, isLoading, isRefreshing, isFailure, isStale, isSuccess, hasData, hasError, isPending, isAsyncData, orElse, revalidate, revalidateOrLoad, zipWith, all, settle, } from './index.js';
+export type { AsyncData, AsyncDataEncoded, AsyncDataSchema } from './index.js';
+//# sourceMappingURL=public.d.ts.map

package/dist/asyncData/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/asyncData/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,KAAK,EACL,OAAO,EACP,OAAO,EACP,IAAI,EACJ,MAAM,EACN,KAAK,EACL,SAAS,EACT,cAAc,EACd,GAAG,EACH,QAAQ,EACR,OAAO,EACP,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,YAAY,EACZ,SAAS,EACT,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,GAAG,EACH,MAAM,GACP,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/asyncData/public.js

@@ -0,0 +1 @@
+export { Idle, Loading, Refreshing, Failure, Stale, Success, succeed, fail, Schema, match, matchData, matchDataSplit, map, mapError, mapBoth, flatMap, getData, getError, getOrElse, isIdle, isLoading, isRefreshing, isFailure, isStale, isSuccess, hasData, hasError, isPending, isAsyncData, orElse, revalidate, revalidateOrLoad, zipWith, all, settle, } from './index.js';

package/dist/html/index.d.ts

@@ -1070,6 +1070,9 @@ declare const buildHtmlFactory: <Message>() => {
     } | {
         readonly _tag: "Filter";
         readonly value: string;
+    } | {
+        readonly _tag: "Loading";
+        readonly value: string;
     } | {
         readonly _tag: "Start";
         readonly value: number;
@@ -1513,9 +1516,6 @@ declare const buildHtmlFactory: <Message>() => {
     } | {
         readonly _tag: "Sizes";
         readonly value: string;
-    } | {
-        readonly _tag: "Loading";
-        readonly value: string;
     } | {
         readonly _tag: "Decoding";
         readonly value: string;