firstly 0.10.8 → 0.12.0

package/esm/svelte/query/index.svelte.d.ts

@@ -0,0 +1,40 @@
+import { type ClassType, type EntityFilter, type FindOptions } from 'remult';
+import type { RemoteQuery, RemoteResource } from '$app/server';
+/** No `set` or `withOverride`: they would hold rows, not entities. */
+export type RepoQuery<T> = RemoteResource<T> & Pick<RemoteQuery<T>, 'refresh'>;
+/**
+ * `repo(E)` for reactive reads: SSR goes through the API (rules apply, as the
+ * current user) and hydration sends no query.
+ *
+ * ```svelte
+ * <script lang="ts">
+ * 	import { repo } from 'remult'
+ *
+ * 	import { queryRepo } from 'firstly/svelte/query'
+ *
+ * 	let { params } = $props()
+ *
+ * 	let tasks = $derived(await queryRepo(Task).find({ where: { slug: params.slug } }))
+ * </script>
+ *
+ * {#each tasks as task (task.id)}
+ * 	<button onclick={() => repo(Task).update(task.id, { done: true })}>{task.title}</button>
+ * {/each}
+ * ```
+ *
+ * Plain `repo(E)` writes in the browser refresh the queries of `E` on screen.
+ * To do so, importing this wraps `remult.dataProvider` in the browser. Call
+ * `.refresh()` for what it can't see: BackendMethods, `include`d entities and
+ * other users' writes.
+ *
+ * A failed refresh reaches the error page, like any `.refresh()` in Kit.
+ * Long filters can exceed the URL limit: arguments travel in a GET.
+ *
+ * @experimental Needs `experimental.remoteFunctions` and
+ * `compilerOptions.experimental.async`.
+ */
+export declare const queryRepo: <T>(entity: ClassType<T>) => {
+    find: (options?: FindOptions<T>) => RepoQuery<T[]>;
+    findFirst: (where?: EntityFilter<T>, options?: FindOptions<T>) => RepoQuery<T | undefined>;
+    count: (where?: EntityFilter<T>) => RepoQuery<number>;
+};

package/esm/svelte/query/index.svelte.js

@@ -0,0 +1,112 @@
+import { BROWSER } from 'esm-env';
+import { Filter, remult, repo, } from 'remult';
+import { read } from './read.remote.js';
+const WRITES = new Set([
+    'insert',
+    'update',
+    'delete',
+    'deleteMany',
+    'updateMany',
+    'upsertMany',
+]);
+/** Entity key -> args of the queries on screen. */
+const live = new Map();
+const track = (arg) => {
+    const id = JSON.stringify(arg);
+    try {
+        $effect.pre(() => {
+            const args = live.get(arg.key) ?? live.set(arg.key, new Map()).get(arg.key);
+            const entry = args.get(id) ?? args.set(id, { arg, count: 0 }).get(id);
+            entry.count++;
+            return () => {
+                if (--entry.count === 0)
+                    args.delete(id);
+            };
+        });
+    }
+    catch {
+        // not in a reactive context: nothing on screen to refresh
+    }
+};
+// allSettled: a failed refresh must not fail the write that triggered it
+const refreshLive = (key) => Promise.allSettled([...(live.get(key)?.values() ?? [])].map(({ arg }) => read(arg).refresh()));
+const withRefresh = (dp) => new Proxy(dp, {
+    get(t, p) {
+        if (p !== 'getEntityDataProvider')
+            return Reflect.get(t, p);
+        return (entity) => new Proxy(t.getEntityDataProvider(entity), {
+            get(edp, m) {
+                const v = Reflect.get(edp, m);
+                if (typeof v !== 'function')
+                    return v;
+                if (!WRITES.has(m))
+                    return v.bind(edp);
+                return async (...args) => {
+                    const result = await v.apply(edp, args);
+                    await refreshLive(entity.key);
+                    return result;
+                };
+            },
+        });
+    },
+});
+if (BROWSER)
+    remult.dataProvider = withRefresh(remult.dataProvider);
+const mapped = (inner, arg, map) => new Proxy(inner, {
+    get(t, p) {
+        if (p === 'then') {
+            track(arg);
+            // read now: Kit pins the query in the reactive context of this getter
+            const then = t.then;
+            return (ok, err) => then.call(t, map).then(ok, err);
+        }
+        if (p === 'current')
+            return t.current === undefined ? undefined : map(t.current);
+        const v = Reflect.get(t, p);
+        return typeof v === 'function' ? v.bind(t) : v;
+    },
+});
+/**
+ * `repo(E)` for reactive reads: SSR goes through the API (rules apply, as the
+ * current user) and hydration sends no query.
+ *
+ * ```svelte
+ * <script lang="ts">
+ * 	import { repo } from 'remult'
+ *
+ * 	import { queryRepo } from 'firstly/svelte/query'
+ *
+ * 	let { params } = $props()
+ *
+ * 	let tasks = $derived(await queryRepo(Task).find({ where: { slug: params.slug } }))
+ * </script>
+ *
+ * {#each tasks as task (task.id)}
+ * 	<button onclick={() => repo(Task).update(task.id, { done: true })}>{task.title}</button>
+ * {/each}
+ * ```
+ *
+ * Plain `repo(E)` writes in the browser refresh the queries of `E` on screen.
+ * To do so, importing this wraps `remult.dataProvider` in the browser. Call
+ * `.refresh()` for what it can't see: BackendMethods, `include`d entities and
+ * other users' writes.
+ *
+ * A failed refresh reaches the error page, like any `.refresh()` in Kit.
+ * Long filters can exceed the URL limit: arguments travel in a GET.
+ *
+ * @experimental Needs `experimental.remoteFunctions` and
+ * `compilerOptions.experimental.async`.
+ */
+export const queryRepo = (entity) => {
+    const r = repo(entity);
+    const run = (method, options, map) => {
+        const where = options?.where && Filter.entityFilterToJson(r.metadata, options.where);
+        const arg = { key: r.metadata.key, method, options: { ...options, where } };
+        return mapped(read(arg), arg, map);
+    };
+    return {
+        find: (options) => run('find', options, (rows) => r.fromJson(rows)),
+        findFirst: (where, options) => run('find', { ...options, where, limit: 1 }, (rows) => r.fromJson(rows)[0]),
+        count: (where) => run('count', { where }, (n) => n),
+    };
+};

package/esm/svelte/query/read.remote.d.ts

@@ -0,0 +1,7 @@
+import { type FindOptions } from 'remult';
+export type RepoRead = {
+    key: string;
+    method: 'find' | 'count';
+    options?: FindOptions<any>;
+};
+export declare const read: import("$app/server").RemoteQueryFunction<RepoRead, any, RepoRead>;

package/esm/svelte/query/read.remote.js

@@ -0,0 +1,27 @@
+import { error } from '@sveltejs/kit';
+import { Filter, repo } from 'remult';
+import { getRequestEvent, query } from '$app/server';
+import { repoFetch } from '../remultApiLoad.js';
+const READS = new Set(['find', 'count']);
+let byKey;
+// TODO(remult): needs a public way to resolve an entity by key
+const allEntities = () => globalThis[Symbol.for('remult-static1')]?.allEntities ?? [];
+export const read = query('unchecked', async ({ key, method, options }) => {
+    byKey ??= new Map(allEntities().map((e) => [repo(e).metadata.key, e]));
+    const entity = byKey.get(key);
+    // reachable by anyone: only known entities, only reads
+    if (!entity || !READS.has(method))
+        error(404);
+    // never `repo()`: on the server it reads the DB without API rules
+    const r = repoFetch(getRequestEvent().fetch)(entity);
+    const where = options?.where && Filter.entityFilterFromJson(r.metadata, options.where);
+    try {
+        if (method === 'count')
+            return await r.count(where);
+        // toJson keeps included relations as class instances
+        return JSON.parse(JSON.stringify(r.toJson(await r.find({ ...options, where }))));
+    }
+    catch (e) {
+        error(e?.status ?? e?.httpStatusCode ?? 500, e?.message ?? 'Error');
+    }
+});

package/esm/svelte/remultApiLoad.d.ts

@@ -10,8 +10,16 @@ export type Repo = typeof globalRepo;
  *
  * Name the result so the intent shows at every query:
  * ```ts
- * const repoClient = repoFetch(event.fetch)
- * await repoClient(Task).find()
+ * // +page.ts
+ * import { repoFetch } from 'firstly/svelte'
+ *
+ * import type { PageLoad } from './$types'
+ *
+ * export const load: PageLoad = async (event) => {
+ * 	const repoClient = repoFetch(event.fetch)
+ * 	const tasks = await repoClient(Task).find()
+ * 	return { tasks }
+ * }
  * ```
  *
  * TODO(remult): framework-agnostic (only needs a fetch) - candidate to live in
@@ -22,16 +30,20 @@ export declare function repoFetch(fetch: typeof globalThis.fetch, options?: {
 }): Repo;
 /**
  * Wrap a load: the callback receives a repo bound to `event.fetch`, then the event.
- * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads.
+ * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads:
+ * `satisfies` types the event, including `cookies` and `locals` in a server load.
  *
  * ```ts
- * export const load = loadRepo(async (repoClient, { params }) => ({
- * 	task: await repoClient(Task).findFirst({ id: params.id }),
- * })) satisfies PageLoad // or PageServerLoad
- * ```
+ * // +page.ts
+ * import { loadRepo } from 'firstly/svelte'
  *
- * For server-only event members (`cookies`, `locals`, ...) annotate the event:
- * `loadRepo(async (repoClient, event: ServerLoadEvent) => ...)`.
+ * import type { PageLoad } from './$types'
+ *
+ * export const load = loadRepo(async (repoClient, { params }) => {
+ * 	const task = await repoClient(Task).findFirst({ id: params.id })
+ * 	return { task }
+ * }) satisfies PageLoad // or PageServerLoad
+ * ```
  *
  * TODO(remult): candidate to live in remult - only the event default is
  * SvelteKit-specific, the constraint itself is structural (`{ fetch }`).

package/esm/svelte/remultApiLoad.js

@@ -8,8 +8,16 @@ import { repo as globalRepo, remult, RestDataProvider } from 'remult';
  *
  * Name the result so the intent shows at every query:
  * ```ts
- * const repoClient = repoFetch(event.fetch)
- * await repoClient(Task).find()
+ * // +page.ts
+ * import { repoFetch } from 'firstly/svelte'
+ *
+ * import type { PageLoad } from './$types'
+ *
+ * export const load: PageLoad = async (event) => {
+ * 	const repoClient = repoFetch(event.fetch)
+ * 	const tasks = await repoClient(Task).find()
+ * 	return { tasks }
+ * }
  * ```
  *
  * TODO(remult): framework-agnostic (only needs a fetch) - candidate to live in
@@ -25,16 +33,20 @@ export function repoFetch(fetch, options) {
 }
 /**
  * Wrap a load: the callback receives a repo bound to `event.fetch`, then the event.
- * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads.
+ * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads:
+ * `satisfies` types the event, including `cookies` and `locals` in a server load.
  *
  * ```ts
- * export const load = loadRepo(async (repoClient, { params }) => ({
- * 	task: await repoClient(Task).findFirst({ id: params.id }),
- * })) satisfies PageLoad // or PageServerLoad
- * ```
+ * // +page.ts
+ * import { loadRepo } from 'firstly/svelte'
  *
- * For server-only event members (`cookies`, `locals`, ...) annotate the event:
- * `loadRepo(async (repoClient, event: ServerLoadEvent) => ...)`.
+ * import type { PageLoad } from './$types'
+ *
+ * export const load = loadRepo(async (repoClient, { params }) => {
+ * 	const task = await repoClient(Task).findFirst({ id: params.id })
+ * 	return { task }
+ * }) satisfies PageLoad // or PageServerLoad
+ * ```
  *
  * TODO(remult): candidate to live in remult - only the event default is
  * SvelteKit-specific, the constraint itself is structural (`{ fetch }`).

package/esm/svelte/server/handleCaching.d.ts

@@ -1,4 +1,4 @@
-import type { Handle } from '@sveltejs/kit';
+import type { Handle } from '@sveltejs/kit/hooks';
 /**
  * `hooks.server.js` handle that sets `Cache-Control` so browsers and CDNs cache
  * correctly across deploys - the server-side twin of `withStaleDeployReload`.
@@ -16,7 +16,7 @@ import type { Handle } from '@sveltejs/kit';
  * ```js
  * // src/hooks.server.js
  * import { sequence } from '@sveltejs/kit/hooks'
- * import { handleCaching } from './'
+ * import { handleCaching } from 'firstly/svelte/server'
  *
  * export const handle = sequence(handleCaching, ...rest)
  * ```

package/esm/svelte/server/handleCaching.js

@@ -17,7 +17,7 @@ const STATIC_ASSET_RE = /\.(js|css|ico|png|jpg|jpeg|gif|svg|webp|avif|woff2?|ttf
  * ```js
  * // src/hooks.server.js
  * import { sequence } from '@sveltejs/kit/hooks'
- * import { handleCaching } from './'
+ * import { handleCaching } from 'firstly/svelte/server'
  *
  * export const handle = sequence(handleCaching, ...rest)
  * ```

package/esm/svelte/ui/Icon.svelte

@@ -2,7 +2,6 @@
 	import { BROWSER } from 'esm-env'
 
 	import './LibIcon'
-
 	import { LibIcon_Empty } from './LibIcon'
 
 	/**

package/esm/vite/index.js

@@ -25,6 +25,11 @@ export function firstly(options) {
     // 		})
     // 	},
     // })
+    p.push({
+        name: 'vite-plugin-firstly',
+        // Oxc leaves remult's decorators raw unless it finds experimentalDecorators in a tsconfig
+        config: () => ({ oxc: { decorator: { legacy: true } } }),
+    });
     p.push(kitRoutes({
         ...(options?.kitRoutes ?? {}),
         ...{
@@ -50,7 +55,12 @@ export function firstly(options) {
             },
         ],
         debug: options?.stripper?.debug ?? false,
-        nullify: options?.stripper?.nullify ?? ['$env/static/private', '$env/dynamic/private'],
+        nullify: options?.stripper?.nullify ?? [
+            '$app/env/private',
+            // deprecated by Kit 3, but still resolvable
+            '$env/static/private',
+            '$env/dynamic/private',
+        ],
     }));
     return p;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.10.8",
+  "version": "0.12.0",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "bin": {
@@ -15,10 +15,10 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.17"
   },
   "peerDependencies": {
-    "@sveltejs/kit": ">=1.0.0 <4.0.0 || ^3.0.0-next.0",
+    "@sveltejs/kit": "^3.0.0",
     "remult": ">=3.3.7",
     "svelte": ">=5"
   },
@@ -59,6 +59,11 @@
       "svelte": "./esm/svelte/index.js",
       "default": "./esm/svelte/index.js"
     },
+    "./svelte/query": {
+      "types": "./esm/svelte/query/index.svelte.d.ts",
+      "svelte": "./esm/svelte/query/index.svelte.js",
+      "default": "./esm/svelte/query/index.svelte.js"
+    },
     "./svelte/server": {
       "types": "./esm/svelte/server/index.d.ts",
       "default": "./esm/svelte/server/index.js"

package/bin/args.d.ts

@@ -1,13 +0,0 @@
-/**
- * @param {string[]} argv
- * @returns {{ help: boolean, json: boolean, raw: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
- */
-export function parseArgs(argv: string[]): {
-    help: boolean;
-    json: boolean;
-    raw: boolean;
-    origin?: string;
-    apiPath?: string;
-    sql: string;
-    error?: string;
-};