firstly 0.4.5 → 0.5.1

package/esm/svelte/FF_Repo.svelte.d.ts

@@ -1,18 +1,83 @@
-import { type ClassType, type FindOptions, type GroupByOptions, type GroupByResult, type MembersOnly, type NumericKeys, type QueryOptions, type Repository } from 'remult';
-type EmptyAggregateResult = {
-    $count: number;
+import { type ClassType, type EntityFilter, type EntityMetadata, type EntityOrderBy, type GroupByOptions, type GroupByResult, type MembersOnly, type MembersToInclude, type NumericKeys, type QueryOptions, type Repository } from 'remult';
+/**
+ * `ffRepo` - thin reactive wrapper around a Remult `repo`, exposing its results as
+ * Svelte runes. Pick the mode with a verb:
+ *
+ *   ffRepo(E).load(() => ({ where }))       // load  - one-shot list + refresh()
+ *   ffRepo(E).listen(() => ({ where }))     // live  - liveQuery, auto-updates
+ *   ffRepo(E).paginate(() => ({ where }))   // paginate - more() / hasNextPage / aggregates
+ *   ffRepo(E).one(() => ({ where }))        // one   - reactive single record in `item`
+ *
+ * Two surfaces, one rule: anything NOT under `.repo` is reactive (a verb returns a
+ * runes handle; that handle's writes sync its own state). Anything under `.repo` is
+ * the plain remult repo - imperative, returns Promises, touches no runes state.
+ *
+ * The options getter is reactive: change `where` (e.g. a search box), `orderBy`,
+ * `enabled`, etc. and the query re-runs - `listen` re-subscribes (the old
+ * subscription is torn down), `load`/`paginate`/`one` re-fetch and ignore any
+ * stale in-flight response. `orderBy` defaults to the entity's `defaultOrderBy`.
+ *
+ * Getter hygiene: read SvelteKit load `data` through a `$derived`
+ * (`const did = $derived(data.targetDid)`), never raw inside the getter. A derived
+ * only propagates on value change, so a parent layout load revalidating - e.g. an
+ * SP URL write re-running url-dependent loads on every filter - hands you a new
+ * `data` object but does NOT re-fetch unless the value actually changed; a real
+ * change (route param switch) still does. Reading `data.x` raw re-fetches on every
+ * revalidation (a duplicate request per filter).
+ *
+ * `enabled: false` skips the query entirely (keeps the last result) and runs it
+ * the moment it flips true - use it for search-min-length, tab visibility,
+ * dependent queries, or a manual button trigger.
+ *
+ * Writes: only the record handle (`one` / `create()`) writes - argless `save()` / `delete()`
+ * act on its `item` and re-sync it. List handles (`load` / `listen` / `paginate`) don't write;
+ * go through `.repo` (the plain remult repo: `insert` / `update` / `save` / `delete` /
+ * `deleteMany`), then reflect it in a `load` / `paginate` list with the local reconcilers
+ * (`addItem` / `updateItem` / `removeItem`) - a `listen` list re-syncs itself via the liveQuery.
+ * A failed write fills `error` and re-throws.
+ *
+ * The factory's return type is mode-specific, so e.g. `.more()` doesn't exist on
+ * a `listen()` handle. Methods also throw if reached via a cast in the wrong mode.
+ *
+ * Reactive vs imperative: the reactive verbs take a *getter* (`() => ({ ... })`) and
+ * return a runes handle; they build an `$effect`, so they must be created during
+ * component init. For a one-off read/write in a click handler / async fn (no runes
+ * context) go through `.repo` (plain remult): `ffRepo(E).repo.findFirst(where)`,
+ * `ffRepo(E).repo.findId(id)`, `ffRepo(E).repo.find(...)`.
+ *
+ * Tip: prefer `.paginate()` whenever you want a total - it returns `aggregates.$count`
+ * for free in the same request. `load`/`listen`/`one` don't count; for a one-off count
+ * use `ffRepo(E).repo.count(where)`.
+ */
+/** The aggregate request shape - remult's `GroupByOptions` minus the grouping/paging keys. */
+export type AggregateOptions<Entity> = Omit<GroupByOptions<Entity, never, NumericKeys<Entity>[], NumericKeys<Entity>[], (keyof MembersOnly<Entity>)[], (keyof MembersOnly<Entity>)[], (keyof MembersOnly<Entity>)[]>, 'group' | 'orderBy' | 'where' | 'limit' | 'page'>;
+/**
+ * Remult `QueryOptions` plus the `aggregate` request shape. Exported for callers
+ * that build query options outside `ffRepo` (e.g. a generic table component).
+ */
+export type QueryOptionsHelper<Entity> = QueryOptions<Entity> & {
+    aggregate?: AggregateOptions<Entity>;
 };
-type Loading = {
-    init: boolean;
-    fetching: boolean;
-    more: boolean;
-    saving: boolean;
-    deleting: boolean;
+export type FF_RepoOptions<Entity> = {
+    where?: EntityFilter<Entity>;
+    orderBy?: EntityOrderBy<Entity>;
+    /** paginate: rows per page (default 25). */
+    pageSize?: number;
+    /** find/one/live: cap the rows returned. No default - returns every matching row. */
+    limit?: number;
+    include?: MembersToInclude<Entity>;
+    /** When false, the query is skipped (last result kept) until it flips true. */
+    enabled?: boolean;
+    /** Aggregations to compute alongside the page (paginate mode only). `$count` is always returned. */
+    aggregate?: AggregateOptions<Entity>;
 };
-type QueryOptionsHelper<entityType> = QueryOptions<entityType> & {
-    aggregate?: Omit<GroupByOptions<entityType, never, NumericKeys<entityType>[], NumericKeys<entityType>[], (keyof MembersOnly<entityType>)[], (keyof MembersOnly<entityType>)[], (keyof MembersOnly<entityType>)[]>, 'group' | 'orderBy' | 'where' | 'limit' | 'page'>;
+type Getter<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = () => O;
+/** `$count` is always present; richer keys appear only for the requested `aggregate`. */
+type EmptyAggregateResult = {
+    $count: number;
 };
-type ExtractAggregateResult<Entity, Options extends QueryOptionsHelper<Entity>> = Options extends {
+/** The typed aggregate result for a given options object (paginate mode). */
+type ExtractAggregateResult<Entity, O extends FF_RepoOptions<Entity>> = O extends {
     aggregate: infer A;
 } ? GroupByResult<Entity, never, A extends {
     sum?: infer S;
@@ -20,57 +85,114 @@ type ExtractAggregateResult<Entity, Options extends QueryOptionsHelper<Entity>>
     avg?: infer V;
 } ? (V extends NumericKeys<Entity>[] ? V : never) : never, A extends {
     min?: infer M;
-} ? (M extends (keyof MembersOnly<Entity>)[] ? M : never) : never, A extends {
+} ? (M extends NumericKeys<Entity>[] ? M : never) : never, A extends {
     max?: infer X;
-} ? (X extends (keyof MembersOnly<Entity>)[] ? X : never) : never, A extends {
+} ? (X extends NumericKeys<Entity>[] ? X : never) : never, A extends {
     distinctCount?: infer D;
 } ? D extends (keyof MembersOnly<Entity>)[] ? D : never : never> : EmptyAggregateResult;
-export declare class FF_Repo<Entity, QueryOptions extends QueryOptionsHelper<Entity> = QueryOptionsHelper<Entity>> {
+export type FF_RepoLoading = {
+    init: boolean;
+    fetching: boolean;
+    more: boolean;
+    saving: boolean;
+    deleting: boolean;
+};
+type Mode = 'live' | 'load' | 'paginate' | 'one';
+/**
+ * The reactive handle implementation. Not exported directly - consumers use a per-mode
+ * alias (`FF_RepoLoad`/`FF_RepoLive`/`FF_RepoPaginate`/`FF_RepoOne`) or the umbrella
+ * union `FF_Repo` (any mode). Each verb returns the Omit'd per-mode view of this.
+ */
+declare class FF_RepoHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> {
     #private;
-    ent: ClassType<Entity>;
-    fields: Repository<Entity>['fields'];
-    metadata: Repository<Entity>['metadata'];
-    loading: Loading;
-    items: Entity[] | undefined;
-    aggregates: ExtractAggregateResult<Entity, QueryOptions> | undefined;
-    hasNextPage: boolean | undefined;
+    items: Entity[];
+    /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
     item: Entity | undefined;
-    globalError: string | undefined;
-    private loadingEnd;
-    constructor(ent: ClassType<Entity>, o?: ({
-        findOptions?: FindOptions<Entity> & {
-            skipAutoFetch?: boolean;
-        };
-        queryOptions?: never;
-    } | {
-        findOptions?: never;
-        queryOptions?: QueryOptions & {
-            skipAutoFetch?: boolean;
-        };
-    }) & {
-        item?: Entity;
-    });
-    find(options: FindOptions<Entity>): Promise<Entity[] | undefined>;
-    query(options: Pick<QueryOptionsHelper<Entity>, 'where' | 'orderBy'>): Promise<{
-        items: Entity[];
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | undefined>;
-    queryMore(): Promise<{
-        items: Entity[] | undefined;
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | undefined>;
+    loading: FF_RepoLoading;
+    error: string | undefined;
+    hasNextPage: boolean;
+    /** Aggregations for the whole query (paginate mode). `aggregates.$count` is the total row count. */
+    aggregates: ExtractAggregateResult<Entity, O> | undefined;
+    constructor(r: Repository<Entity>, opts: Getter<Entity, O>, mode: Mode);
+    /** Re-run the current query (load/paginate/one), back to the first page. */
+    refresh(): Promise<void>;
+    /** Load and append the next page (paginate mode). */
+    more(): Promise<void>;
     /**
-     * Refresh query keeping current items count (BIG refresh)
-     * Useful after edit/delete to stay at current scroll position
+     * Run `fn` once - the first time a row exists (`items[0]`).
+     *
+     * The point: seed editable UI state from the latest row WITHOUT a live query
+     * clobbering in-progress edits. It fires a single time, on the first non-empty
+     * result, and never again - later ticks (an edit, a delete, a re-sort) are
+     * ignored. Empty snapshots are skipped (a liveQuery often emits one before the
+     * data lands; there is nothing to seed from an empty result).
+     *
+     * For pure derived state prefer `$derived`; reach for `onFirst` only when the
+     * seed must become independently editable (a draft the user then mutates).
+     *
+     * ```svelte
+     * const list = ffRepo(Plan).listen(() => ({ where: { ownerDid } }))
+     * let draft = $state({ title: '' })
+     * list.onFirst((latest) => (draft.title = latest.title)) // seed once, then edit freely
+     * ```
      */
-    queryRefresh(options: Pick<QueryOptionsHelper<Entity>, 'where' | 'orderBy'>): Promise<{
-        items: Entity[];
-        aggregates: ExtractAggregateResult<Entity, QueryOptions>;
-        hasNextPage: boolean;
-    } | undefined>;
+    onFirst(fn: (latest: Entity) => void): void;
+    /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args: Parameters<Repository<Entity>['create']>): Entity;
-    delete(...args: Parameters<Repository<Entity>['delete']>): Promise<undefined>;
+    /** Save the current `item` (from `one` / `create()`). To save a specific row, use `.repo.save(row)`. */
+    save(): Promise<Entity>;
+    /** Delete the current `item`. To delete a specific row/id, use `.repo.delete(idOrRow)`. */
+    delete(): Promise<void>;
+    /** Insert into `items` at `top` (default) / `bottom` / an index (`-1` = last). +1 to `$count`. */
+    addItem(item: Entity, options?: {
+        at?: 'top' | 'bottom' | number;
+    }): void;
+    /** Replace the row whose id matches `item`'s id (no `$count` change). */
+    updateItem(item: Entity): void;
+    /** Drop the matching row (pass an id or the item). -1 to `$count`. */
+    removeItem(idOrItem: Parameters<Repository<Entity>['delete']>[0]): void;
+    /**
+     * The entity's remult metadata - the single escape hatch for everything not on
+     * this handle: permissions (`apiInsertAllowed()`, `apiUpdateAllowed(item)`,
+     * `apiDeleteAllowed(item)`, `apiReadAllowed`), `fields`, `idMetadata`, `options`,
+     * `key`. Reflects the current `remult.user`.
+     */
+    get meta(): EntityMetadata<Entity>;
+    /** Escape hatch to the underlying repo (count, findId, upsert, projections, ...). */
+    get repo(): Repository<Entity>;
 }
+/** load: one-shot list (`refresh()` to re-run) - a read+reconcile view. No paging/aggregates, and no `item`/`save`/`delete`/`create` (edit via `one`, write via `.repo`). */
+export type FF_RepoLoad<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates' | 'item' | 'save' | 'delete' | 'create'>;
+/** live: reactive subscription, auto-updates - a read view. No refresh/paging/aggregates/reconcilers (the liveQuery does it), and no `item`/`save`/`delete`/`create`. */
+export type FF_RepoLive<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'refresh' | 'more' | 'hasNextPage' | 'aggregates' | 'addItem' | 'updateItem' | 'removeItem' | 'item' | 'save' | 'delete' | 'create'>;
+/** paginate: `more()` / `hasNextPage` / `aggregates` - a read+reconcile view. No `onFirst` (paged ≠ latest), and no `item`/`save`/`delete`/`create`. */
+export type FF_RepoPaginate<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'onFirst' | 'item' | 'save' | 'delete' | 'create'>;
+/** one: a single reactive record in `item`. No paging / aggregates / list reconcilers. */
+export type FF_RepoOne<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates' | 'addItem' | 'updateItem' | 'removeItem'>;
+/**
+ * Umbrella handle type - any mode. Use for a component prop that accepts a
+ * `load`/`listen`/`paginate`/`one` handle (`r: FF_Repo<T>`). It exposes the surface
+ * common to every mode (`items`/`loading`/`error`/`meta`/`repo`); mode-specific members
+ * (`item`/`save`/`delete`/`create` on `one`; `more`/`hasNextPage`/`aggregates`/`refresh`/
+ * `onFirst`/`addItem`/`updateItem`/`removeItem`) require the matching per-mode type.
+ */
+export type FF_Repo<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = FF_RepoLoad<Entity, O> | FF_RepoLive<Entity, O> | FF_RepoPaginate<Entity, O> | FF_RepoOne<Entity, O>;
+type StrictGetter<Entity, O extends FF_RepoOptions<Entity>> = () => O & Record<Exclude<keyof O, keyof FF_RepoOptions<Entity>>, never>;
+/**
+ * The builder returned by `ffRepo(E)`. Two surfaces only: the reactive verbs
+ * (`load`/`listen`/`paginate`/`one`), and `.repo` - the plain remult repo for every
+ * imperative read/write (`findFirst`, `findId`, `find`, `insert`, `update`, `save`,
+ * `delete`, `count`, `upsert`, ...). `.meta` is a shortcut to `repo.metadata`.
+ */
+export type FF_RepoBuilder<Entity> = {
+    load: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoLoad<Entity, O>;
+    listen: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoLive<Entity, O>;
+    paginate: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoPaginate<Entity, O>;
+    one: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_RepoOne<Entity, O>;
+    /** The entity's remult metadata (permissions, fields, key). Shortcut to `repo.metadata`. */
+    readonly meta: EntityMetadata<Entity>;
+    /** The underlying remult repo - every imperative read/write lives here. */
+    readonly repo: Repository<Entity>;
+};
+export declare function ffRepo<Entity>(entity: ClassType<Entity>): FF_RepoBuilder<Entity>;
 export {};