firstly 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # firstly
 
+## 0.6.1
+
+### Patch Changes
+
+- [#294](https://github.com/jycouet/firstly/pull/294) [`7e8c2af`](https://github.com/jycouet/firstly/commit/7e8c2afa7806cf3383d64b048e8f3b9b5b19d237) Thanks [@jycouet](https://github.com/jycouet)! - ff: add `onNew` and `onIssue` lifecycle hooks to the reactive handle (and make `onFirst` chainable)
+  - **`onItem(record => …)`** (`one` mode) / **`onItems(items => …)`** (list modes) - run after each fetch with the loaded data, mirroring the handle's `.item` / `.items` (replaces the old `storeList`/`storeItem` `onNewData`). `onItem` fires only when a row is found - a not-found goes to `onIssue`. `onFirst` stays the once-only seed.
+  - **`onIssue(issue => …)`** - runs when a read doesn't yield the expected data. `issue` is `{ kind: 'notFound' | 'forbidden' | 'error', status?, message? }`; switch on `kind` to react (e.g. redirect). A `one` query that resolves with no row reports `{ kind: 'notFound', status: 404 }`; a rejected read reports `forbidden` (403) or `error`.
+  - All three hooks are now chainable: `ff(E).one(getter).onIssue(…).onNew(…).onFirst(…)`.
+  - **`ff(E).one()` accepts `{ id }` or `{ where }`** (mutually exclusive - a type error if both). `{ id }` loads by primary key via `findId` (no `_sort`/`_limit` on a unique lookup, and dedups with other findId callers); `{ where }` loads via `findFirst` (with optional `orderBy`). `{ id }` re-runs reactively when the id changes.
+
 ## 0.6.0
 
 ### Minor Changes

package/esm/svelte/ff.svelte.d.ts

@@ -36,8 +36,12 @@ export type AggregateOptions<Entity> = Omit<GroupByOptions<Entity, never, Numeri
 export type QueryOptionsHelper<Entity> = QueryOptions<Entity> & {
     aggregate?: AggregateOptions<Entity>;
 };
+/** The primary-key type of an entity (single value, or a composite-id object) - from remult's `findId`. */
+export type FF_Id<Entity> = Parameters<Repository<Entity>['findId']>[0];
 export type FF_RepoOptions<Entity> = {
     where?: EntityFilter<Entity>;
+    /** `one` mode: load by primary key via `findId` (no sort/limit). Mutually exclusive with `where`. */
+    id?: FF_Id<Entity>;
     orderBy?: EntityOrderBy<Entity>;
     /** paginate: rows per page (default 25). */
     pageSize?: number;
@@ -49,6 +53,23 @@ export type FF_RepoOptions<Entity> = {
     /** Aggregations to compute alongside the page (paginate mode only). `$count` is always returned. */
     aggregate?: AggregateOptions<Entity>;
 };
+/**
+ * Options for `ff(E).one(...)`: load a single record either by primary key
+ * (`id` -> `findId`, no sort/limit) OR by filter (`where` -> `findFirst`, with `orderBy`).
+ * Exactly one of `id` / `where` - setting both is a type error.
+ */
+export type FF_OneOptions<Entity> = {
+    include?: MembersToInclude<Entity>;
+    enabled?: boolean;
+} & ({
+    id: FF_Id<Entity>;
+    where?: never;
+    orderBy?: never;
+} | {
+    id?: never;
+    where?: EntityFilter<Entity>;
+    orderBy?: EntityOrderBy<Entity>;
+});
 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 = {
@@ -75,6 +96,20 @@ export type FF_RepoLoading = {
     saving: boolean;
     deleting: boolean;
 };
+/**
+ * What `onIssue` reports when a read doesn't yield the expected data:
+ * - `notFound`  - a `one` query resolved with no row (status 404)
+ * - `forbidden` - the API rejected the read (status 403, e.g. permissions)
+ * - `error`     - any other failure (network, server, ...)
+ *
+ * `status`/`message` are best-effort, read off the underlying error when present.
+ * Switch on `kind` to react (e.g. redirect on `notFound`/`forbidden`).
+ */
+export type FF_Issue = {
+    kind: 'notFound' | 'forbidden' | 'error';
+    status?: number;
+    message?: string;
+};
 type Mode = 'live' | 'load' | 'paginate' | 'one';
 /**
  * The reactive handle implementation (internal). `ff().one()` returns an Omit'd view of this
@@ -118,7 +153,31 @@ declare class FF_RepoHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOp
      * list.onFirst((latest) => (draft.title = latest.title)) // seed once, then edit freely
      * ```
      */
-    onFirst(fn: (latest: Entity) => void): void;
+    onFirst(fn: (latest: Entity) => void): this;
+    /**
+     * `one` mode only. Run `fn` with the record after EVERY fetch that finds one (a
+     * not-found goes to `onIssue` instead). Mirrors the handle's `.item`. Unlike
+     * `onFirst` (once, on the first row), this fires on each load / refresh. Chainable.
+     */
+    onItem(fn: (item: Entity) => void): this;
+    /**
+     * List modes only. Run `fn` with the fresh `items` after EVERY read (mimics the old
+     * `storeList` `onNewData`). Fires on each load / refresh / paginate page / live tick.
+     * Mirrors the handle's `.items`. Chainable.
+     */
+    onItems(fn: (items: Entity[]) => void): this;
+    /**
+     * Run `fn` when a read doesn't yield the expected data: a `one` query with no row
+     * (`notFound`), a rejected read (`forbidden`, 403), or any other failure (`error`).
+     * The arg is an `FF_Issue` ({@link FF_Issue}) - switch on `issue.kind` to react,
+     * e.g. redirect on not-found. Chainable.
+     *
+     * ```svelte
+     * const site = ff(Site).one(() => ({ where: { id } }))
+     *   .onIssue((i) => { if (i.kind === 'notFound') goto('/app/sites') })
+     * ```
+     */
+    onIssue(fn: (issue: FF_Issue) => void): this;
     /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args: Parameters<Repository<Entity>['create']>): Entity;
     /** Save the current `item` (from `one` / `create()`). To save a specific row, use remult `repo(E).save(row)`. */
@@ -168,13 +227,13 @@ declare class FF_RepoHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOp
     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 remult `repo(E)`). */
-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' | 'syncs'>;
+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' | 'syncs' | 'onItem'>;
 /** 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' | 'reconcile' | 'syncs'>;
+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' | 'reconcile' | 'syncs' | 'onItem'>;
 /** 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' | 'syncs'>;
+export type FF_RepoPaginate<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'onFirst' | 'onItem' | 'item' | 'save' | 'delete' | 'create' | 'syncs'>;
 /** 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' | 'reconcile'>;
+export type FF_RepoOne<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Entity>> = Omit<FF_RepoHandle<Entity, O>, 'more' | 'hasNextPage' | 'aggregates' | 'addItem' | 'updateItem' | 'removeItem' | 'reconcile' | 'onItems'>;
 /** The list strategy backing `many`. Maps `listen` → live mode internally. */
 export type ManyStrategy = 'load' | 'listen' | 'paginate';
 /**
@@ -267,7 +326,11 @@ declare class FF_ManyHandle<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOp
      * `$bindable` the user then mutates), not the draft; for pure display prefer
      * `$derived(handle.items[0])`. Delegates to the list handle (see `onFirst` there).
      */
-    onFirst(fn: (latest: Entity) => void): void;
+    onFirst(fn: (latest: Entity) => void): this;
+    /** Run `fn` after every successful list read, with the fresh `items`. Delegates to the list handle. Chainable. */
+    onItems(fn: (items: Entity[]) => void): this;
+    /** Run `fn` when a list read fails (`forbidden`/`error`). Delegates to the list handle. Chainable. */
+    onIssue(fn: (issue: FF_Issue) => void): this;
     get meta(): EntityMetadata<Entity>;
     get repo(): Repository<Entity>;
 }
@@ -280,8 +343,8 @@ export type FF_One<Entity, O extends FF_RepoOptions<Entity> = FF_RepoOptions<Ent
 export type FF_Builder<Entity> = {
     /** A crud composite (list + editing draft + writes). `strategy` picks the fetch (default `paginate`). */
     many: <O extends FF_RepoOptions<Entity>, S extends ManyStrategy = 'paginate'>(opts: StrictGetter<Entity, O>, strategy?: S) => FF_Many<Entity, S, O>;
-    /** A single reactive record bound to `item`. */
-    one: <O extends FF_RepoOptions<Entity>>(opts: StrictGetter<Entity, O>) => FF_One<Entity, O>;
+    /** A single reactive record bound to `item` - by primary key (`{ id }` -> findId) or filter (`{ where }` -> findFirst). */
+    one: (opts: () => FF_OneOptions<Entity>) => FF_One<Entity>;
     /** The entity's remult metadata (captions, permissions, fields). */
     readonly meta: EntityMetadata<Entity>;
 };

package/esm/svelte/ff.svelte.js

@@ -1,5 +1,13 @@
 import { repo as remultRepo, } from 'remult';
 import { dialog } from './dialog.svelte.js';
+/** Classify a thrown read error into an {@link FF_Issue} (best-effort status sniffing). */
+function toIssue(e) {
+    const err = e;
+    const status = err?.httpStatusCode ?? err?.status;
+    const message = e instanceof Error ? e.message : typeof e === 'string' ? e : err?.message;
+    const kind = status === 403 ? 'forbidden' : status === 404 ? 'notFound' : 'error';
+    return { kind, status, message };
+}
 /**
  * The reactive handle implementation (internal). `ff().one()` returns an Omit'd view of this
  * (`FF_One`); `ff().many()` wraps a list handle + a `.syncs`-linked one in `FF_ManyHandle`
@@ -13,6 +21,9 @@ class FF_RepoHandle {
     #paginator;
     #seq = 0;
     #syncTargets = [];
+    #onItemCbs = [];
+    #onItemsCbs = [];
+    #onIssueCbs = [];
     items = $state([]);
     /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
     item = $state(undefined);
@@ -56,10 +67,12 @@ class FF_RepoHandle {
                     next: (info) => {
                         this.items = info.items;
                         this.loading.init = false;
+                        this.#fireItems();
                     },
                     error: (e) => {
                         this.error = e instanceof Error ? e.message : String(e);
                         this.loading.init = false;
+                        this.#fireIssue(toIssue(e));
                     },
                 });
                 return () => unsub();
@@ -98,16 +111,23 @@ class FF_RepoHandle {
                 // `aggregates` is only on the paginator type when the aggregate is non-empty,
                 // but remult returns `$count` for the empty case too - so read it through a cast.
                 this.aggregates = p.aggregates;
+                this.#fireItems();
             }
             else if (this.#mode === 'one') {
-                const found = await this.#repo.findFirst(o.where, {
-                    orderBy: o.orderBy,
-                    include: o.include,
-                });
+                // `id` -> findId (by primary key, no sort/limit); otherwise `where` -> findFirst.
+                const found = o.id != null
+                    ? await this.#repo.findId(o.id, { include: o.include })
+                    : await this.#repo.findFirst(o.where, { orderBy: o.orderBy, include: o.include });
                 if (seq !== this.#seq)
                     return;
                 this.item = found ?? undefined;
                 this.items = found ? [found] : [];
+                // Found -> onItem; not found -> onIssue (a row was deleted, the id is wrong, or a
+                // prefilter hid it) so callers can redirect/404 instead of sitting on an empty record.
+                if (found)
+                    this.#fireItem(found);
+                else
+                    this.#fireIssue({ kind: 'notFound', status: 404 });
             }
             else {
                 const items = await this.#repo.find({
@@ -119,11 +139,14 @@ class FF_RepoHandle {
                 if (seq !== this.#seq)
                     return;
                 this.items = items;
+                this.#fireItems();
             }
         }
         catch (e) {
-            if (seq === this.#seq)
+            if (seq === this.#seq) {
                 this.error = e instanceof Error ? e.message : String(e);
+                this.#fireIssue(toIssue(e));
+            }
         }
         finally {
             if (seq === this.#seq) {
@@ -189,6 +212,52 @@ class FF_RepoHandle {
             fn(latest);
             done = true;
         });
+        return this;
+    }
+    #fireItem(item) {
+        for (const fn of this.#onItemCbs)
+            fn(item);
+    }
+    #fireItems() {
+        for (const fn of this.#onItemsCbs)
+            fn(this.items);
+    }
+    #fireIssue(issue) {
+        for (const fn of this.#onIssueCbs)
+            fn(issue);
+    }
+    /**
+     * `one` mode only. Run `fn` with the record after EVERY fetch that finds one (a
+     * not-found goes to `onIssue` instead). Mirrors the handle's `.item`. Unlike
+     * `onFirst` (once, on the first row), this fires on each load / refresh. Chainable.
+     */
+    onItem(fn) {
+        this.#onItemCbs.push(fn);
+        return this;
+    }
+    /**
+     * List modes only. Run `fn` with the fresh `items` after EVERY read (mimics the old
+     * `storeList` `onNewData`). Fires on each load / refresh / paginate page / live tick.
+     * Mirrors the handle's `.items`. Chainable.
+     */
+    onItems(fn) {
+        this.#onItemsCbs.push(fn);
+        return this;
+    }
+    /**
+     * Run `fn` when a read doesn't yield the expected data: a `one` query with no row
+     * (`notFound`), a rejected read (`forbidden`, 403), or any other failure (`error`).
+     * The arg is an `FF_Issue` ({@link FF_Issue}) - switch on `issue.kind` to react,
+     * e.g. redirect on not-found. Chainable.
+     *
+     * ```svelte
+     * const site = ff(Site).one(() => ({ where: { id } }))
+     *   .onIssue((i) => { if (i.kind === 'notFound') goto('/app/sites') })
+     * ```
+     */
+    onIssue(fn) {
+        this.#onIssueCbs.push(fn);
+        return this;
     }
     /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args) {
@@ -570,6 +639,17 @@ class FF_ManyHandle {
      */
     onFirst(fn) {
         this.#list.onFirst(fn);
+        return this;
+    }
+    /** Run `fn` after every successful list read, with the fresh `items`. Delegates to the list handle. Chainable. */
+    onItems(fn) {
+        this.#list.onItems(fn);
+        return this;
+    }
+    /** Run `fn` when a list read fails (`forbidden`/`error`). Delegates to the list handle. Chainable. */
+    onIssue(fn) {
+        this.#list.onIssue(fn);
+        return this;
     }
     get meta() {
         return this.#repo.metadata;

package/esm/svelte/index.d.ts

@@ -1,5 +1,5 @@
 export { ff } from './ff.svelte.js';
-export type { FF_Many, FF_One, FF_Builder, FF_RepoOptions, FF_RepoLoading, ManyStrategy, AggregateOptions, QueryOptionsHelper, } from './ff.svelte.js';
+export type { FF_Many, FF_One, FF_Builder, FF_RepoOptions, FF_OneOptions, FF_RepoLoading, FF_Issue, ManyStrategy, AggregateOptions, QueryOptionsHelper, } from './ff.svelte.js';
 export { infiniteScroll } from './infiniteScroll.js';
 export type { InfiniteScrollOptions } from './infiniteScroll.js';
 export { dialog, ffAutofocus, resolveMessage } from './dialog.svelte.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",