firstly 0.4.5 → 0.5.1

package/esm/svelte/FF_Repo.svelte.js

@@ -1,193 +1,305 @@
 import { repo as remultRepo, } from 'remult';
-import { Log } from '@kitql/helpers';
-import { tryCatch, tryCatchSync } from '../core/tryCatch.js';
-export class FF_Repo {
-    ent;
+/**
+ * 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.
+ */
+class FF_RepoHandle {
     #repo;
+    #opts;
+    #mode;
+    #defaultOrderBy;
     #paginator;
-    #findOptions;
-    #queryOptions;
-    fields;
-    metadata;
+    #seq = 0;
+    items = $state([]);
+    /** Single-record slot: the loaded row in `one` mode, or a create/edit draft (see `create`). */
+    item = $state(undefined);
     loading = $state({
-        init: false,
+        init: true,
         fetching: false,
         more: false,
         saving: false,
         deleting: false,
     });
-    items = $state(undefined);
+    error = $state(undefined);
+    hasNextPage = $state(false);
+    /** Aggregations for the whole query (paginate mode). `aggregates.$count` is the total row count. */
     aggregates = $state(undefined);
-    hasNextPage = $state(undefined);
-    item = $state(undefined);
-    // errors = $state<ErrorInfo<Entity> | undefined>(undefined)
-    globalError = $state(undefined);
-    loadingEnd = (toRet) => {
-        this.loading = {
-            init: false,
-            fetching: false,
-            more: false,
-            saving: false,
-            deleting: false,
-        };
-        return toRet;
-    };
-    constructor(ent, o) {
-        this.ent = ent;
-        this.#repo = remultRepo(ent);
-        this.fields = this.#repo.fields;
-        this.metadata = this.#repo.metadata;
-        this.#paginator = undefined;
-        this.#findOptions = o?.findOptions;
-        this.#queryOptions = o?.queryOptions;
-        this.item = o?.item;
-        if (o?.findOptions !== undefined && !o.findOptions.skipAutoFetch) {
-            this.loading.init = true;
-            this.find(o.findOptions);
-        }
-        else if (o?.queryOptions !== undefined && !o.queryOptions.skipAutoFetch) {
-            this.loading.init = true;
-            this.query(o.queryOptions);
-        }
-        else {
-            this.loadingEnd();
-        }
+    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;
+                    },
+                    error: (e) => {
+                        this.error = e instanceof Error ? e.message : String(e);
+                        this.loading.init = false;
+                    },
+                });
+                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 find(options) {
+    async #load(o, seq, keepCount) {
         this.loading.fetching = true;
-        const { data, error } = await tryCatch(this.#repo.find({
-            ...this.#findOptions,
-            ...options,
-        }));
-        if (error) {
-            this.globalError = error.message;
-            return this.loadingEnd();
+        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;
+            }
+            else if (this.#mode === 'one') {
+                const found = 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] : [];
+            }
+            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.items = data;
-        return this.loadingEnd(data);
-    }
-    async query(options) {
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            init: this.items === undefined,
-        };
-        // REMULT P1: add test for dynamic orderBy in remult
-        //            Looks like only the default orderby of the entity is working
-        const { data: queryResult, error: queryResultError } = tryCatchSync(() => this.#repo.query({
-            pageSize: 2,
-            ...this.#queryOptions,
-            ...options,
-            // Yes, we always want to aggregate to get at least the $count!
-            // And empty object is giving us that
-            aggregate: {
-                ...this.#queryOptions?.aggregate,
-            },
-        }));
-        if (queryResultError) {
-            this.globalError = queryResultError.message;
-            return this.loadingEnd();
+        catch (e) {
+            if (seq === this.#seq)
+                this.error = e instanceof Error ? e.message : String(e);
         }
-        const { data: paginator, error: paginatorError } = await tryCatch(queryResult.paginator());
-        if (paginatorError) {
-            this.globalError = paginatorError.message;
-            return this.loadingEnd();
+        finally {
+            if (seq === this.#seq) {
+                this.loading.init = false;
+                this.loading.fetching = false;
+            }
         }
-        this.#paginator = paginator;
-        this.items = this.#paginator.items;
-        // @ts-expect-error - We know the structure will match due to how we define the types
-        this.aggregates = this.#paginator.aggregates;
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
-        });
     }
-    async queryMore() {
-        if (this.#paginator === undefined) {
-            new Log('FF_Repo').error('No paginator found');
-            return undefined;
-        }
-        if (this.loading.more) {
-            // already in progress...
-            return undefined;
+    /** 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;
+        this.loading.more = true;
+        try {
+            const next = await this.#paginator.nextPage();
+            this.#paginator = next;
+            this.items = [...this.items, ...next.items];
+            this.hasNextPage = next.hasNextPage;
         }
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            more: true,
-        };
-        const { data: nextPage, error: nextPageError } = await tryCatch(this.#paginator.nextPage());
-        if (nextPageError) {
-            this.globalError = nextPageError.message;
-            return this.loadingEnd();
+        finally {
+            this.loading.more = false;
         }
-        this.#paginator = nextPage;
-        this.items?.push(...nextPage.items);
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
-        });
     }
     /**
-     * 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
+     * ```
      */
-    async queryRefresh(options) {
-        const currentCount = this.items?.length ?? this.#queryOptions?.pageSize ?? 25;
-        this.loading = {
-            ...this.loading,
-            fetching: true,
-            init: this.items === undefined,
-        };
-        const { data: queryResult, error: queryResultError } = tryCatchSync(() => this.#repo.query({
-            ...this.#queryOptions,
-            ...options,
-            pageSize: currentCount,
-            aggregate: {
-                ...this.#queryOptions?.aggregate,
-            },
-        }));
-        if (queryResultError) {
-            this.globalError = queryResultError.message;
-            return this.loadingEnd();
-        }
-        const { data: paginator, error: paginatorError } = await tryCatch(queryResult.paginator());
-        if (paginatorError) {
-            this.globalError = paginatorError.message;
-            return this.loadingEnd();
-        }
-        this.#paginator = paginator;
-        this.items = this.#paginator.items;
-        // @ts-expect-error - We know the structure will match due to how we define the types
-        this.aggregates = this.#paginator.aggregates;
-        this.hasNextPage = this.#paginator.hasNextPage && this.aggregates.$count > this.items.length;
-        return this.loadingEnd({
-            items: this.items,
-            aggregates: this.aggregates,
-            hasNextPage: this.hasNextPage,
+    onFirst(fn) {
+        let done = false;
+        $effect(() => {
+            if (done)
+                return;
+            const latest = this.items[0];
+            if (latest == null)
+                return;
+            fn(latest);
+            done = true;
         });
     }
+    /** Create a new unsaved entity into the `item` slot (for an edit form). */
     create(...args) {
         this.item = this.#repo.create(...args);
         return this.item;
     }
-    async delete(...args) {
-        this.loading.deleting = true;
-        await this.#repo.delete(...args);
-        // REMULT P4: return the deleted item ?
-        if (typeof args[0] === 'string') {
-            this.items = this.items?.filter((i) => this.metadata.idMetadata.getId(i) !== args[0]);
+    // 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;
+        this.error = undefined;
+        try {
+            const res = await op();
+            await after();
+            return res;
         }
-        else {
-            this.items = this.items?.filter((i) => this.metadata.idMetadata.getId(i) !== this.metadata.idMetadata.getId(args[0]));
+        catch (e) {
+            this.error = e instanceof Error ? e.message : String(e);
+            throw e;
         }
-        if (this.aggregates) {
-            this.aggregates.$count = this.aggregates.$count - 1;
+        finally {
+            this.loading[flag] = false;
         }
-        return this.loadingEnd();
     }
+    /** Save the current `item` (from `one` / `create()`). To save a specific row, use `.repo.save(row)`. */
+    save() {
+        return this.#write('saving', () => this.#repo.save(this.#requireItem()), () => this.#resync());
+    }
+    /** Delete the current `item`. To delete a specific row/id, use `.repo.delete(idOrRow)`. */
+    delete() {
+        const target = this.#requireItem();
+        return 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);
+        });
+    }
+    /** 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 `.repo`.');
+        return this.item;
+    }
+    // Client-side list reconcilers (no server I/O) - reflect a change you made
+    // elsewhere (e.g. via `.repo`) 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) {
+        this.#removeLocal(idOrItem);
+    }
+    #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;
+    }
+}
+export function ffRepo(entity) {
+    const r = remultRepo(entity);
+    const builder = {
+        load(o) {
+            return new FF_RepoHandle(r, o, 'load');
+        },
+        listen(o) {
+            return new FF_RepoHandle(r, o, 'live');
+        },
+        paginate(o) {
+            return new FF_RepoHandle(r, o, 'paginate');
+        },
+        one(o) {
+            return new FF_RepoHandle(r, o, 'one');
+        },
+        get meta() {
+            return r.metadata;
+        },
+        repo: r,
+    };
+    return builder;
 }

package/esm/svelte/index.d.ts

@@ -1,6 +1,10 @@
-export { FF_Repo } from './FF_Repo.svelte.js';
+export { ffRepo } from './FF_Repo.svelte.js';
+export type { FF_Repo, FF_RepoOptions, FF_RepoLoading, FF_RepoLoad, FF_RepoLive, FF_RepoPaginate, FF_RepoOne, FF_RepoBuilder, AggregateOptions, QueryOptionsHelper, } from './FF_Repo.svelte.js';
+export { infiniteScroll } from './infiniteScroll.js';
+export type { InfiniteScrollOptions } from './infiniteScroll.js';
 export { SP } from './class/SP.svelte';
 export type { ParamDefinition } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';
+export { default as DemoGrid } from './DemoGrid.svelte';
 export { default as Icon } from './ui/Icon.svelte';
 export { LibIcon_Empty, LibIcon_Forbidden, LibIcon_ChevronDown, LibIcon_ChevronUp, LibIcon_ChevronLeft, LibIcon_ChevronRight, LibIcon_Search, LibIcon_Check, LibIcon_MultiCheck, LibIcon_Add, LibIcon_MultiAdd, LibIcon_Edit, LibIcon_Eye, LibIcon_EyeOff, LibIcon_Delete, LibIcon_Cross, LibIcon_Save, LibIcon_Man, LibIcon_Woman, LibIcon_Send, LibIcon_Load, LibIcon_Settings, LibIcon_Sort, LibIcon_SortAsc, LibIcon_SortDesc, } from './ui/LibIcon.js';

package/esm/svelte/index.js

@@ -1,5 +1,7 @@
-export { FF_Repo } from './FF_Repo.svelte.js';
+export { ffRepo } from './FF_Repo.svelte.js';
+export { infiniteScroll } from './infiniteScroll.js';
 export { SP } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';
+export { default as DemoGrid } from './DemoGrid.svelte';
 export { default as Icon } from './ui/Icon.svelte';
 export { LibIcon_Empty, LibIcon_Forbidden, LibIcon_ChevronDown, LibIcon_ChevronUp, LibIcon_ChevronLeft, LibIcon_ChevronRight, LibIcon_Search, LibIcon_Check, LibIcon_MultiCheck, LibIcon_Add, LibIcon_MultiAdd, LibIcon_Edit, LibIcon_Eye, LibIcon_EyeOff, LibIcon_Delete, LibIcon_Cross, LibIcon_Save, LibIcon_Man, LibIcon_Woman, LibIcon_Send, LibIcon_Load, LibIcon_Settings, LibIcon_Sort, LibIcon_SortAsc, LibIcon_SortDesc, } from './ui/LibIcon.js';

package/esm/svelte/infiniteScroll.d.ts

@@ -0,0 +1,31 @@
+import type { Attachment } from 'svelte/attachments';
+export type InfiniteScrollOptions = {
+    /** Are there more pages to load? */
+    hasMore: () => boolean;
+    /** Is a load already in flight? */
+    loading: () => boolean;
+    /** Load the next page. */
+    onMore: () => void;
+    /** Preload distance below the scroll viewport, in px (default 1200). */
+    rootMarginPx?: number;
+};
+/**
+ * Infinite-scroll attachment: put it on a bottom sentinel element and it calls
+ * `onMore()` when the sentinel nears the scroll container. The observer is rooted
+ * on the nearest scrollable ancestor, so it works when the app scrolls inside an
+ * inner div (not the window), and a `rootMarginPx` margin streams the next page in
+ * just before the sentinel shows. Guarded by `hasMore()`/`loading()`. Because it
+ * observes geometry it never misfires on mount: a full first page leaves the
+ * sentinel far below the root.
+ *
+ * Pairs with `ffRepo(E).paginate(...)`:
+ *
+ * ```svelte
+ * <div {@attach infiniteScroll({
+ *   hasMore: () => r.hasNextPage,
+ *   loading: () => r.loading.more,
+ *   onMore: () => r.more(),
+ * })}></div>
+ * ```
+ */
+export declare function infiniteScroll(opts: InfiniteScrollOptions): Attachment;

package/esm/svelte/infiniteScroll.js

@@ -0,0 +1,40 @@
+/** Nearest scrollable ancestor, or null (the document/window scrolls). */
+function scrollParent(el) {
+    let p = el.parentElement;
+    while (p && p !== document.body) {
+        const oy = getComputedStyle(p).overflowY;
+        if (oy === 'auto' || oy === 'scroll')
+            return p;
+        p = p.parentElement;
+    }
+    return null;
+}
+/**
+ * Infinite-scroll attachment: put it on a bottom sentinel element and it calls
+ * `onMore()` when the sentinel nears the scroll container. The observer is rooted
+ * on the nearest scrollable ancestor, so it works when the app scrolls inside an
+ * inner div (not the window), and a `rootMarginPx` margin streams the next page in
+ * just before the sentinel shows. Guarded by `hasMore()`/`loading()`. Because it
+ * observes geometry it never misfires on mount: a full first page leaves the
+ * sentinel far below the root.
+ *
+ * Pairs with `ffRepo(E).paginate(...)`:
+ *
+ * ```svelte
+ * <div {@attach infiniteScroll({
+ *   hasMore: () => r.hasNextPage,
+ *   loading: () => r.loading.more,
+ *   onMore: () => r.more(),
+ * })}></div>
+ * ```
+ */
+export function infiniteScroll(opts) {
+    return (node) => {
+        const io = new IntersectionObserver((entries) => {
+            if (entries[0]?.isIntersecting && opts.hasMore() && !opts.loading())
+                opts.onMore();
+        }, { root: scrollParent(node), rootMargin: `${opts.rootMarginPx ?? 1200}px 0px` });
+        io.observe(node);
+        return () => io.disconnect();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",
@@ -40,8 +40,8 @@
     "nodemailer": "8.0.5",
     "tailwind-merge": "3.5.0",
     "tailwindcss": "4.2.2",
-    "vite-plugin-kit-routes": "1.0.5",
-    "vite-plugin-stripper": "0.10.3"
+    "vite-plugin-kit-routes": "1.0.6",
+    "vite-plugin-stripper": "0.10.4"
   },
   "sideEffects": false,
   "exports": {