firstly 0.5.1 → 0.6.1

package/esm/svelte/ff.svelte.js

@@ -0,0 +1,679 @@
+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`
+ * (exposed as `FF_Many`). The per-mode aliases below stay internal to this module.
+ */
+class FF_RepoHandle {
+    #repo;
+    #opts;
+    #mode;
+    #defaultOrderBy;
+    #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);
+    loading = $state({
+        init: true,
+        fetching: false,
+        more: false,
+        saving: false,
+        deleting: false,
+    });
+    error = $state(undefined);
+    hasNextPage = $state(false);
+    /** Aggregations for the whole query (paginate mode). `aggregates.$count` is the total row count. */
+    aggregates = $state(undefined);
+    /** Any read or write currently in flight (init/fetching/more/saving/deleting). */
+    get isBusy() {
+        const l = this.loading;
+        return l.init || l.fetching || l.more || l.saving || l.deleting;
+    }
+    /** A write (insert/update/delete) in flight. */
+    get isWriting() {
+        return this.loading.saving || this.loading.deleting;
+    }
+    constructor(r, opts, mode) {
+        this.#repo = r;
+        this.#opts = opts;
+        this.#mode = mode;
+        this.#defaultOrderBy = r.metadata.options.defaultOrderBy;
+        $effect(() => {
+            const o = this.#resolve();
+            if (o.enabled === false) {
+                this.loading.init = false;
+                return;
+            }
+            if (mode === 'live') {
+                // Pass orderBy so liveQuery re-sorts incrementally-added rows too;
+                // without it a freshly inserted row is appended and `items[0]` (the latest) goes stale.
+                const unsub = this.#repo
+                    .liveQuery({ where: o.where, orderBy: o.orderBy, limit: o.limit, include: o.include })
+                    .subscribe({
+                    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();
+            }
+            // load | paginate | one: (re)fetch; a newer opts() invalidates older responses.
+            void this.#load(o, ++this.#seq);
+        });
+    }
+    #resolve() {
+        const o = this.#opts();
+        return { ...o, orderBy: o.orderBy ?? this.#defaultOrderBy };
+    }
+    async #load(o, seq, keepCount) {
+        this.loading.fetching = true;
+        this.error = undefined;
+        try {
+            if (this.#mode === 'paginate') {
+                // One request returns the page AND the aggregates ($count always, plus any
+                // requested): on the client REST proxy remult fetches both together. It sets
+                // `hasNextPage` from whether a full page came back (no count probe); `more()`
+                // then fetches the next page via a keyset cursor (orderBy + PK).
+                const p = await this.#repo
+                    .query({
+                    where: o.where,
+                    orderBy: o.orderBy,
+                    pageSize: keepCount ?? o.pageSize ?? 25,
+                    include: o.include,
+                    aggregate: { ...o.aggregate },
+                })
+                    .paginator();
+                if (seq !== this.#seq)
+                    return;
+                this.#paginator = p;
+                this.items = p.items;
+                this.hasNextPage = p.hasNextPage;
+                // `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') {
+                // `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({
+                    where: o.where,
+                    orderBy: o.orderBy,
+                    limit: o.limit,
+                    include: o.include,
+                });
+                if (seq !== this.#seq)
+                    return;
+                this.items = items;
+                this.#fireItems();
+            }
+        }
+        catch (e) {
+            if (seq === this.#seq) {
+                this.error = e instanceof Error ? e.message : String(e);
+                this.#fireIssue(toIssue(e));
+            }
+        }
+        finally {
+            if (seq === this.#seq) {
+                this.loading.init = false;
+                this.loading.fetching = false;
+            }
+        }
+    }
+    /** Re-run the current query (load/paginate/one), back to the first page. */
+    async refresh() {
+        if (this.#mode === 'live')
+            throw new Error('FF_Repo: refresh() is not available in live mode');
+        await this.#load(this.#resolve(), ++this.#seq);
+    }
+    /** Load and append the next page (paginate mode). */
+    async more() {
+        if (this.#mode !== 'paginate')
+            throw new Error('FF_Repo: more() requires paginate mode');
+        if (!this.#paginator || this.loading.more || !this.hasNextPage)
+            return;
+        const seq = this.#seq;
+        this.loading.more = true;
+        try {
+            const next = await this.#paginator.nextPage();
+            // A newer query (where/orderBy/pageSize changed) ran while this page was in flight:
+            // drop the stale page rather than appending it to the new result.
+            if (seq !== this.#seq)
+                return;
+            this.#paginator = next;
+            this.items = [...this.items, ...next.items];
+            this.hasNextPage = next.hasNextPage;
+        }
+        finally {
+            this.loading.more = false;
+        }
+    }
+    /**
+     * 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 = ff(Plan).many(() => ({ where: { ownerDid } }), 'listen')
+     * let draft = $state({ title: '' })
+     * list.onFirst((latest) => (draft.title = latest.title)) // seed once, then edit freely
+     * ```
+     */
+    onFirst(fn) {
+        let done = false;
+        $effect(() => {
+            if (done)
+                return;
+            const latest = this.items[0];
+            if (latest == null)
+                return;
+            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) {
+        this.item = this.#repo.create(...args);
+        return this.item;
+    }
+    // Mutations: run `op`, then the post-write sync on SUCCESS only (a failed write
+    // leaves the result untouched). On failure we fill `error` AND re-throw - the
+    // caller still gets the rejection (not silenced); `error` is for a reactive
+    // UI that wants it. `finally` only flips `loading` (no `await`, which would
+    // mask the original error).
+    async #write(flag, op, after) {
+        this.loading[flag] = true;
+        for (const t of this.#syncTargets)
+            t.loading[flag] = true;
+        this.error = undefined;
+        try {
+            const res = await op();
+            await after();
+            return res;
+        }
+        catch (e) {
+            this.error = e instanceof Error ? e.message : String(e);
+            throw e;
+        }
+        finally {
+            this.loading[flag] = false;
+            for (const t of this.#syncTargets)
+                t.loading[flag] = false;
+        }
+    }
+    /** Save the current `item` (from `one` / `create()`). To save a specific row, use remult `repo(E).save(row)`. */
+    async save() {
+        const saved = await this.#write('saving', () => this.#repo.save(this.#requireItem()), () => this.#resync());
+        this.item = saved;
+        for (const t of this.#syncTargets)
+            t.reconcile(saved);
+        return saved;
+    }
+    /** Delete the current `item`. To delete a specific row/id, use remult `repo(E).delete(idOrRow)`. */
+    async delete() {
+        const target = this.#requireItem();
+        const res = await this.#write('deleting', () => this.#repo.delete(target), () => {
+            // live: liveQuery removes it. one: re-fetch (likely empty now).
+            // load/paginate: drop it locally (no refetch).
+            if (this.#mode === 'live')
+                return;
+            if (this.#mode === 'one')
+                return this.#resync();
+            this.#removeLocal(target);
+        });
+        for (const t of this.#syncTargets)
+            t.removeItem(target);
+        return res;
+    }
+    /**
+     * Save a specific `row` through this list handle's loading/error machinery (mirrors the
+     * argless `save()`), then reconcile the list (sorted upsert / paginate refresh). Used by
+     * `FF_ManyHandle.save(target)` so a targeted write flips `loading.saving` and fills `error`.
+     */
+    async saveRow(row) {
+        let saved;
+        await this.#write('saving', async () => (saved = await this.#repo.save(row)), () => this.reconcile(saved));
+        return saved;
+    }
+    /**
+     * Delete a specific `row` through this list handle's loading/error machinery (mirrors the
+     * argless `delete()`), then drop it from the list. Used by `FF_ManyHandle.remove(target)`.
+     */
+    async deleteRow(row) {
+        await this.#write('deleting', () => this.#repo.delete(row), () => this.removeItem(row));
+    }
+    /**
+     * Link this record handle (`one`) to one or more list handles. On `save()` /
+     * `delete()` the lists are reconciled (sorted upsert / remove) and share the
+     * write-loading flag, so the list area shows "busy" during the write too. A live
+     * list reconcile is a no-op (its liveQuery already syncs). Returns `this`.
+     */
+    syncs(...targets) {
+        this.#syncTargets = targets;
+        return this;
+    }
+    /** The current `item` (or throw) - backs the argless `save()`/`delete()`. */
+    #requireItem() {
+        if (this.item === undefined)
+            throw new Error('FF_Repo: no `item` to save/delete - load one first (`one` mode or `create()`), or write a specific row through remult `repo(E)`.');
+        return this.item;
+    }
+    // Client-side list reconcilers (no server I/O) - reflect a change you made
+    // elsewhere (e.g. via remult `repo(E)`) in the reactive `items`. `load`/`paginate` only;
+    // `listen` reconciles itself via the liveQuery. `add`/`remove` also adjust
+    // `aggregates.$count` (not the other aggregates). For authoritative state, call
+    // `refresh()` (it re-pulls and, for paginate, resets to the first page).
+    /** Insert into `items` at `top` (default) / `bottom` / an index (`-1` = last). +1 to `$count`. */
+    addItem(item, options) {
+        const at = options?.at ?? 'top';
+        const list = this.items;
+        const idx = at === 'top'
+            ? 0
+            : at === 'bottom'
+                ? list.length
+                : at < 0
+                    ? Math.max(0, list.length + at + 1)
+                    : Math.min(at, list.length);
+        this.items = [...list.slice(0, idx), item, ...list.slice(idx)];
+        if (this.aggregates)
+            this.aggregates.$count += 1;
+    }
+    /** Replace the row whose id matches `item`'s id (no `$count` change). */
+    updateItem(item) {
+        const id = this.#repo.metadata.idMetadata.getId(item);
+        this.items = this.items.map((x) => (this.#repo.metadata.idMetadata.getId(x) === id ? item : x));
+    }
+    /** Drop the matching row (pass an id or the item). -1 to `$count`. */
+    removeItem(idOrItem) {
+        if (this.#mode === 'live')
+            return;
+        this.#removeLocal(idOrItem);
+    }
+    /**
+     * Insert-or-update `item` at its SORTED position (load mode), recomputing the index
+     * from this handle's `orderBy` plus the entity id as tiebreak. Paginate re-fetches
+     * (a row may belong to an unloaded page); live is a no-op (the liveQuery syncs).
+     */
+    reconcile(item) {
+        if (this.#mode === 'live')
+            return;
+        if (this.#mode === 'paginate') {
+            void this.refresh();
+            return;
+        }
+        const id = this.#repo.metadata.idMetadata.getId(item);
+        const without = this.items.filter((x) => this.#repo.metadata.idMetadata.getId(x) !== id);
+        const cmp = this.#comparator(this.#resolve().orderBy);
+        let idx = without.findIndex((x) => cmp(item, x) < 0);
+        if (idx < 0)
+            idx = without.length;
+        this.items = [...without.slice(0, idx), item, ...without.slice(idx)];
+    }
+    // A comparator from an EntityOrderBy, with the entity id appended as a stable
+    // tiebreak (remult does the same so keyset paging is deterministic).
+    #comparator(orderBy) {
+        const entries = Object.entries(orderBy ?? {});
+        const idOf = (e) => this.#repo.metadata.idMetadata.getId(e);
+        return (a, b) => {
+            for (const [field, dir] of entries) {
+                const av = a[field];
+                const bv = b[field];
+                if (av < bv)
+                    return dir === 'desc' ? 1 : -1;
+                if (av > bv)
+                    return dir === 'desc' ? -1 : 1;
+            }
+            const ai = idOf(a);
+            const bi = idOf(b);
+            return ai < bi ? -1 : ai > bi ? 1 : 0;
+        };
+    }
+    #removeLocal(idOrItem) {
+        const id = idOrItem != null && typeof idOrItem === 'object'
+            ? this.#repo.metadata.idMetadata.getId(idOrItem)
+            : idOrItem;
+        this.items = this.items.filter((i) => this.#repo.metadata.idMetadata.getId(i) !== id);
+        if (this.aggregates)
+            this.aggregates.$count = Math.max(0, this.aggregates.$count - 1);
+    }
+    /** After insert/update (or a `one` delete) in a non-live mode, re-fetch keeping the current count. */
+    async #resync() {
+        if (this.#mode === 'live')
+            return;
+        const keepCount = this.#mode === 'paginate' ? this.items.length || undefined : undefined;
+        await this.#load(this.#resolve(), ++this.#seq, keepCount);
+    }
+    /**
+     * 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() {
+        return this.#repo.metadata;
+    }
+    /** Escape hatch to the underlying repo (count, findId, upsert, projections, ...). */
+    get repo() {
+        return this.#repo;
+    }
+}
+/**
+ * Style 1 - unified composite. One handle owning a list (load/listen/paginate) AND
+ * the current editing `draft`, pre-wired: the draft handle `.syncs(list)`, so saving
+ * or deleting reconciles the list (sorted upsert / remove) and loading/error are
+ * merged across both. Proves the styles share internals: this is just a list handle
+ * plus a `.syncs()`-linked `one` handle.
+ *
+ *   const t = ff(Task).many(() => ({ where }), 'load')
+ *   t.edit(row) / t.create() / t.save() / t.remove(row) / t.cancel()
+ *   markup reads t.items, t.draft, t.loading, t.isBusy, t.error
+ */
+class FF_ManyHandle {
+    #repo;
+    #idKey;
+    #list;
+    #editor;
+    #editingId = $state(null);
+    constructor(r, opts, strategy) {
+        this.#repo = r;
+        this.#idKey = r.metadata.idMetadata.field.key;
+        this.#list = new FF_RepoHandle(r, opts, strategy === 'listen' ? 'live' : strategy);
+        this.#editor = new FF_RepoHandle(r, (() => ({
+            where: { [this.#idKey]: this.#editingId ?? '' },
+            enabled: this.#editingId !== null,
+        })), 'one');
+        this.#editor.syncs(this.#list);
+    }
+    get items() {
+        return this.#list.items;
+    }
+    get draft() {
+        return this.#editor.item;
+    }
+    set draft(v) {
+        this.#editor.item = v;
+    }
+    get error() {
+        return this.#editor.error ?? this.#list.error;
+    }
+    get hasNextPage() {
+        return this.#list.hasNextPage;
+    }
+    get aggregates() {
+        return this.#list.aggregates;
+    }
+    /** Merged loading: list reads + draft writes. */
+    get loading() {
+        const l = this.#list.loading;
+        const e = this.#editor.loading;
+        return {
+            init: l.init,
+            fetching: l.fetching || e.fetching,
+            more: l.more,
+            // Targeted writes (`save(row)`/`remove(row)`) flip the list flags; argless draft
+            // writes flip the editor flags (and propagate to the list via `.syncs`). Merge both.
+            saving: e.saving || l.saving,
+            deleting: e.deleting || l.deleting,
+        };
+    }
+    get isBusy() {
+        const l = this.loading;
+        return l.init || l.fetching || l.more || l.saving || l.deleting;
+    }
+    get isWriting() {
+        return this.loading.saving || this.loading.deleting;
+    }
+    /**
+     * Load `row` into `draft` for editing. Pass the row itself (works with any PK,
+     * single or composite - the id is read off it).
+     *
+     * Default (no fetch): edits an isolated **clone** of `row` - instant, no flicker,
+     * and saving updates the original (the clone keeps remult's existing-row state).
+     * Cancelling just drops the clone, so the list row is untouched until save.
+     *
+     * `{ refetch: true }`: optimistic - put `row`'s structure into `draft` **immediately**
+     * (so a form renders at full size, no open-then-grow flicker), then re-read the row
+     * fresh from the data source and swap it in. The optimistic draft is marked as an
+     * **existing** row (rebuilt via json), so it works whether `row` is a tracked entity,
+     * a plain spread/`$state` object, or an id-only stub - and saving updates, never inserts.
+     * Use it when the list row may be stale or you only hold its id.
+     */
+    edit(row, opts) {
+        if (opts?.refetch) {
+            this.#editor.item = this.#repo.fromJson(this.#repo.toJson(this.#repo.create(row)), false);
+            this.#editingId = this.#repo.metadata.idMetadata.getId(row);
+        }
+        else {
+            this.#editingId = null; // keep the editor's query disabled; the clone is the draft
+            this.#editor.item = this.#repo.getEntityRef(row).clone();
+        }
+    }
+    /** Start a blank `draft` (insert). */
+    create(...args) {
+        this.#editingId = null;
+        return this.#editor.create(...args);
+    }
+    /** Drop the draft / stop editing, and clear any pending error. */
+    cancel() {
+        this.#editingId = null;
+        this.#editor.item = undefined;
+        this.#editor.error = undefined;
+    }
+    /** Save `target` (any row) or, argless, the current `draft`; reconciles the list. */
+    async save(target) {
+        if (target !== undefined) {
+            // Route through the list handle's loading/error machinery (same as the argless path),
+            // then reconcile - so a targeted save flips `loading.saving` and fills/clears `error`.
+            return this.#list.saveRow(target);
+        }
+        const saved = await this.#editor.save();
+        this.cancel();
+        return saved;
+    }
+    /** Delete `target` (any row) or, argless, the current `draft`; reconciles the list. */
+    async remove(target) {
+        if (target !== undefined) {
+            // Route through the list handle's loading/error machinery (same as the argless path),
+            // then drop the row - so a targeted remove flips `loading.deleting` and fills/clears `error`.
+            await this.#list.deleteRow(target);
+            return;
+        }
+        await this.#editor.delete();
+        this.cancel();
+    }
+    /**
+     * Confirm, then remove `row`. Resolves `{ ok: true }` when removed, `{ ok: false }` when the
+     * user cancels OR the delete fails (a failure also fills `error` and, unless `toast: false`,
+     * shows `toast.fromError`). Never re-throws - safe for `onclick={() => list.confirmRemove(row)}`.
+     */
+    async confirmRemove(row, opts) {
+        const c = await dialog.confirm(opts?.message ?? 'Delete this item?', {
+            title: opts?.title,
+            confirmLabel: opts?.confirmLabel,
+            cancelLabel: opts?.cancelLabel,
+            danger: opts?.danger ?? true,
+        });
+        if (!c.ok)
+            return { ok: false };
+        try {
+            await this.remove(row);
+            return { ok: true, data: undefined };
+        }
+        catch (e) {
+            if (opts?.toast !== false) {
+                // Lazy import keeps `ff` users who never toast from pulling svelte-sonner.
+                const { toast } = await import('./toast.js');
+                toast.fromError(e);
+            }
+            return { ok: false };
+        }
+    }
+    /**
+     * Edit `row` in a dialog: seed `draft` (a clone, or `{ refetch: true }` to re-read fresh),
+     * open `body`, and always `cancel()` on close. The `body` snippet binds `draft` and calls
+     * `save()` itself (so a failed/validation save keeps the dialog open via `error`); this method
+     * owns only the seed + cleanup. Resolves the dialog's `DialogResult`.
+     */
+    async editInDialog(row, body, opts) {
+        this.edit(row, { refetch: opts?.refetch });
+        try {
+            return await dialog.show(body, opts);
+        }
+        finally {
+            this.cancel();
+        }
+    }
+    /**
+     * Create in a dialog: start a blank `draft` (optionally seeded with `defaults`), open `body`,
+     * and always `cancel()` on close. The `body` binds `draft` and calls `save()` itself.
+     */
+    async createInDialog(body, opts) {
+        this.create(opts?.defaults);
+        try {
+            return await dialog.show(body, opts);
+        }
+        finally {
+            this.cancel();
+        }
+    }
+    more() {
+        return this.#list.more();
+    }
+    refresh() {
+        return this.#list.refresh();
+    }
+    /**
+     * Seed editable state once, from the latest row (`items[0]`), the first time one
+     * lands - then never again, so a later live tick can't clobber an in-progress edit.
+     * Use it when the seed must become independently editable (a separate `$state` /
+     * `$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) {
+        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;
+    }
+    get repo() {
+        return this.#repo;
+    }
+}
+/**
+ * `ff(E)` - the firstly reactive layer. `ff(E).many(getter, strategy?)` for a list+edit
+ * composite, `ff(E).one(getter)` for a single record. Everything imperative stays on
+ * remult's `repo(E)`.
+ */
+export function ff(entity) {
+    const r = remultRepo(entity);
+    return {
+        many(o, strategy) {
+            return new FF_ManyHandle(r, o, strategy ?? 'paginate');
+        },
+        one(o) {
+            return new FF_RepoHandle(r, o, 'one');
+        },
+        get meta() {
+            return r.metadata;
+        },
+    };
+}