aeon-ui-engine 1.9.0 → 1.10.1

package/packages/primitives/dist/machines/store.d.ts

@@ -0,0 +1,286 @@
+import * as xstate from 'xstate';
+import { fromCallback } from 'xstate';
+import { CacheState, CacheView } from './cache.js';
+
+/**
+ * One store per app: every entity lives once, by id, in its slice. Charts and
+ * components read through selectors and project state onto `data-aeon-*`
+ * attributes; the only way to change anything is an event sent to the store.
+ */
+interface SliceOptions<E, Q> {
+    idOf: (entity: E) => string;
+    /** Loads the entities a query names. Slices without `load` are filled by events only. */
+    load?: (query: Q, context: {
+        signal: AbortSignal;
+    }) => Promise<readonly E[]>;
+    /** Milliseconds a query result stays fresh. Default 30 seconds. */
+    ttl?: number | ((query: Q) => number);
+    tags?: (query: Q) => readonly string[];
+    /** Turns a query into the key its result is stored under. Defaults to `String` for strings, else JSON. */
+    queryKey?: (query: Q) => string;
+    /** An incoming entity equal to the held one keeps the held object, so selectors stay quiet. Default: shallow equality. */
+    equals?: (a: E, b: E) => boolean;
+    /** Saved by the store's persistence adapter. Default true. */
+    persist?: boolean;
+}
+interface SliceDefinition<E, Q> extends SliceOptions<E, Q> {
+    readonly __types?: {
+        entity: E;
+        query: Q;
+    };
+}
+declare function defineSlice<E, Q = string>(options: SliceOptions<E, Q>): SliceDefinition<E, Q>;
+type AnySlices = Record<string, SliceDefinition<any, any>>;
+type EntityOf<D> = D extends {
+    readonly __types?: {
+        entity: infer E;
+    };
+} ? E : never;
+type QueryOf<D> = D extends {
+    readonly __types?: {
+        query: infer Q;
+    };
+} ? Q : never;
+/** One query's result: its load state and the ids it returned, in order. */
+interface QueryView {
+    readonly state: CacheState;
+    readonly ids: readonly string[];
+    readonly error: string | null;
+    readonly loadedAt: number | null;
+}
+interface SliceState<E> {
+    readonly byId: Readonly<Record<string, E>>;
+    /** Every held id, in arrival order. */
+    readonly ids: readonly string[];
+    readonly queries: Readonly<Record<string, QueryView>>;
+    /** Entity id → the optimistic write it waits on. */
+    readonly pending: Readonly<Record<string, string>>;
+    /** Entity id → why its last write was rolled back. Cleared by the next write to it. */
+    readonly failed: Readonly<Record<string, string>>;
+}
+type StoreStatus = 'hydrating' | 'ready';
+interface PendingWrite {
+    slice: string;
+    /** Values before the write, restored on rollback. */
+    before: Record<string, unknown>;
+    /** Values the write put in place; rollback only restores entities still holding them. */
+    after: Record<string, unknown>;
+}
+interface StoreState<S extends AnySlices> {
+    readonly status: StoreStatus;
+    readonly slices: {
+        readonly [N in keyof S]: SliceState<EntityOf<S[N]>>;
+    };
+    readonly writes: Readonly<Record<string, PendingWrite>>;
+}
+type SliceEvent<N extends string, E, Q> = {
+    type: 'ENTITY.UPSERT';
+    slice: N;
+    entities: readonly E[];
+} | {
+    type: 'ENTITY.PATCH';
+    slice: N;
+    id: string;
+    patch: Partial<E>;
+} | {
+    type: 'ENTITY.REMOVE';
+    slice: N;
+    ids: readonly string[];
+} | {
+    type: 'QUERY.FETCH';
+    slice: N;
+    query: Q;
+} | {
+    type: 'QUERY.REFRESH';
+    slice: N;
+    query: Q;
+} | {
+    type: 'QUERY.INVALIDATE';
+    slice: N;
+    query?: Q;
+    tag?: string;
+}
+/** Applies at once and marks the entities pending until WRITE.CONFIRM or WRITE.ROLLBACK. */
+ | {
+    type: 'WRITE.BEGIN';
+    slice: N;
+    write: string;
+    upsert?: readonly E[];
+    remove?: readonly string[];
+};
+/** Everything a store accepts. Writes, loads and invalidations all go through here. */
+type StoreEvent<S extends AnySlices> = {
+    [N in keyof S & string]: SliceEvent<N, EntityOf<S[N]>, QueryOf<S[N]>>;
+}[keyof S & string] | {
+    type: 'WRITE.CONFIRM';
+    write: string;
+} | {
+    type: 'WRITE.ROLLBACK';
+    write: string;
+    error?: string;
+}
+/** Marks every query stale; watched ones reload (reconnect, window focus). */
+ | {
+    type: 'STORE.INVALIDATE';
+}
+/** Drops all data, running loads and saved data (lock, account or network switch). */
+ | {
+    type: 'STORE.CLEAR';
+};
+interface StoreAdapter {
+    load(key: string): string | null | undefined | Promise<string | null | undefined>;
+    save(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+interface StorePersistOptions {
+    adapter: StoreAdapter;
+    /** Bump when the saved shape changes; older data goes through `migrate` or is dropped. */
+    version: number;
+    migrate?: (saved: PersistedSlices, fromVersion: number) => PersistedSlices | null | undefined;
+    /** Milliseconds of quiet before a save. Default 250. */
+    delayMs?: number;
+}
+type PersistedSlices = Record<string, {
+    byId: Record<string, unknown>;
+    ids: string[];
+}>;
+interface StoreOptions<S extends AnySlices> {
+    /** Names the store and its saved data. Names of secrets, keys or spend decisions are refused. */
+    id: string;
+    slices: S;
+    persist?: StorePersistOptions;
+    /** Starts a server or disk feed that sends store events; returns its stop function. */
+    sync?: (send: (event: StoreEvent<S>) => void) => (() => void) | void;
+    now?: () => number;
+}
+/** A query's view with its entities resolved. Stable until the view or one of its entities changes. */
+interface QueryResult<E> extends QueryView {
+    readonly entities: readonly E[];
+}
+interface Selection<T> {
+    get(): T;
+    /** Calls back only when the selected value changes under `equals`. */
+    subscribe(listener: (value: T) => void): () => void;
+}
+/** What the invoked store actor sends its parent chart whenever its selection changes. */
+interface StoreUpdate<T> {
+    type: 'STORE.UPDATE';
+    store: string;
+    value: T;
+}
+interface AeonStore<S extends AnySlices> {
+    readonly id: string;
+    getSnapshot(): StoreState<S>;
+    /** For `useSyncExternalStore`: calls back after every change. */
+    subscribe(listener: () => void): () => void;
+    send(event: StoreEvent<S>): void;
+    select<T>(selector: (state: StoreState<S>) => T, equals?: (a: T, b: T) => boolean): Selection<T>;
+    entity<N extends keyof S & string>(slice: N, id: string): EntityOf<S[N]> | undefined;
+    query<N extends keyof S & string>(slice: N, query: QueryOf<S[N]>): QueryResult<EntityOf<S[N]>>;
+    /** Resolves once saved data has loaded (at once without persistence). */
+    readonly ready: Promise<void>;
+    /** Saves now instead of after the quiet delay (app quit). */
+    flush(): Promise<void>;
+    stop(): void;
+    /**
+     * Invoke from a chart: `invoke: { id: 'store', src: store.actor, input: { select } }`.
+     * It sends `STORE.UPDATE` whenever the selection changes and forwards store
+     * events the chart sends it (`sendTo('store', …)`).
+     */
+    readonly actor: ReturnType<typeof fromCallback<StoreEvent<S>, {
+        select: (state: StoreState<S>) => unknown;
+        equals?: (a: unknown, b: unknown) => boolean;
+    }>>;
+}
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+/** Field and slice names are checked word by word, so `seedPhrase` and `privateKey` are caught. */
+declare function isStorableName(name: string): boolean;
+/** The first field name, at any depth, that names a secret, key or spend decision. */
+declare function unstorableField(value: unknown, depth?: number): string | null;
+/** `data-aeon-*` projection of a query: its load state and how many entities it holds. */
+declare function queryAttrs(result: QueryView): Record<string, string>;
+/** `data-aeon-*` projection of one entity: pending while a write waits on the server, failed after a rollback. */
+declare function entityAttrs<E>(slice: SliceState<E>, sliceName: string, id: string): Record<string, string>;
+declare function memoryAdapter(initial?: Record<string, string>): StoreAdapter & {
+    readonly data: Map<string, string>;
+};
+declare function webStorageAdapter(storage?: Storage): StoreAdapter;
+type AnyEntity = unknown;
+type AnySliceState = SliceState<AnyEntity>;
+interface Data {
+    status: StoreStatus;
+    slices: Record<string, AnySliceState>;
+    writes: Record<string, PendingWrite>;
+}
+/**
+ * The store's chart: `hydrating` until saved data has loaded, then `ready`.
+ * Every event folds into one immutable snapshot (`context.data`) that keeps
+ * its identity, and that of every untouched slice and entity, when an event
+ * changes nothing.
+ */
+declare function createStoreMachine(defs: AnySlices): xstate.StateMachine<{
+    data: Data;
+}, {
+    type: "ENTITY.REMOVE";
+    slice: string;
+    ids: readonly string[];
+} | {
+    type: "WRITE.CONFIRM";
+    write: string;
+} | {
+    type: "WRITE.ROLLBACK";
+    write: string;
+    error?: string;
+} | {
+    type: "STORE.INVALIDATE";
+} | {
+    type: "STORE.CLEAR";
+} | {
+    type: "ENTITY.UPSERT";
+    slice: string;
+    entities: readonly any[];
+} | {
+    type: "ENTITY.PATCH";
+    slice: string;
+    id: string;
+    patch: Partial<any>;
+} | {
+    type: "QUERY.FETCH";
+    slice: string;
+    query: any;
+} | {
+    type: "QUERY.REFRESH";
+    slice: string;
+    query: any;
+} | {
+    type: "QUERY.INVALIDATE";
+    slice: string;
+    query?: any;
+    tag?: string;
+} | {
+    type: "WRITE.BEGIN";
+    slice: string;
+    write: string;
+    upsert?: readonly any[] | undefined;
+    remove?: readonly string[];
+} | {
+    type: "QUERY.UPDATE";
+    slice: string;
+    key: string;
+    view: CacheView<readonly AnyEntity[]>;
+} | {
+    type: "STORE.HYDRATED";
+    slices: PersistedSlices | null;
+}, {}, never, never, never, never, "ready" | "hydrating" | "boot", string, {
+    hydrate: boolean;
+}, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "aeonStore";
+    states: {
+        readonly boot: {};
+        readonly hydrating: {};
+        readonly ready: {};
+    };
+}>;
+declare function createAeonStore<S extends AnySlices>(options: StoreOptions<S>): AeonStore<S>;
+
+export { type AeonStore, type AnySlices, type EntityOf, type PersistedSlices, type QueryOf, type QueryResult, type QueryView, type Selection, type SliceDefinition, type SliceOptions, type SliceState, type StoreAdapter, type StoreEvent, type StoreOptions, type StorePersistOptions, type StoreState, type StoreStatus, type StoreUpdate, createAeonStore, createStoreMachine, defineSlice, entityAttrs, isStorableName, memoryAdapter, queryAttrs, shallowEqual, unstorableField, webStorageAdapter };

package/packages/primitives/dist/machines/store.js

@@ -0,0 +1,25 @@
+import {
+  createAeonStore,
+  createStoreMachine,
+  defineSlice,
+  entityAttrs,
+  isStorableName,
+  memoryAdapter,
+  queryAttrs,
+  shallowEqual,
+  unstorableField,
+  webStorageAdapter
+} from "../chunk-H5XJGZHT.js";
+import "../chunk-5BNAV4S2.js";
+export {
+  createAeonStore,
+  createStoreMachine,
+  defineSlice,
+  entityAttrs,
+  isStorableName,
+  memoryAdapter,
+  queryAttrs,
+  shallowEqual,
+  unstorableField,
+  webStorageAdapter
+};

package/packages/primitives/dist/machines/tabs.d.ts

@@ -18,10 +18,10 @@ declare const tabsMachine: xstate.StateMachine<TabsContext, {
     type: "SET_VALUE";
     value: string;
 }, {}, never, {
-    type: "setValue";
+    type: "select";
     params: xstate.NonReducibleUnknown;
 } | {
-    type: "select";
+    type: "setValue";
     params: xstate.NonReducibleUnknown;
 }, {
     type: "notDisabled";

package/packages/primitives/src/index.ts

@@ -17,3 +17,4 @@ export * from './machines/sticky-bar.js'
 export * from './machines/content-region.js'
 export * from './machines/clipboard.js'
 export * from './machines/cache.js'
+export * from './machines/store.js'