firstly 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # firstly
 
+## 0.5.1
+
+### Patch Changes
+
+- [#282](https://github.com/jycouet/firstly/pull/282) [`a93d4c8`](https://github.com/jycouet/firstly/commit/a93d4c8815da30f2c4d701ddd7e3d8cdf39fd8f5) Thanks [@jycouet](https://github.com/jycouet)! - ffRepo (svelte): leaner surface. Rename `firstOnce` → `onFirst`; remove `draft`, `first`, `insert`, `update`, `deleteMany`. List handles (`load`/`listen`/`paginate`) are now read-only - write via `.repo` (+ `addItem`/`updateItem`/`removeItem` to reconcile). Editing lives on `one`/`create()` with argless `save()`/`delete()`.
+
+  New `DemoGrid` (from `firstly/svelte`): a generic inline-CRUD table over any entity - props `entity` + `fields`, headers/placeholders from each field's `caption`.
+
+## 0.5.0
+
+### Minor Changes
+
+- [#274](https://github.com/jycouet/firstly/pull/274) [`6114148`](https://github.com/jycouet/firstly/commit/61141482a06f0a006ae148f0645146c073a2fb3c) Thanks [@jycouet](https://github.com/jycouet)! - **BREAKING (svelte): `FF_Repo` class -> `ffRepo()` factory.** The reactive repo wrapper now takes a reactive options getter and a mode (`load` / `listen` / `paginate` / `one`), with built-in mutations (no-arg `save()`/`delete()` target the loaded `item`), client-side list reconcilers (`addItem`/`updateItem`/`removeItem`, with `addItem` positioning), `firstOnce`/`draft`, and permissions via `r.meta`. The old `new FF_Repo(E, { findOptions })` class is removed.
+
+  One rule: anything not under `.repo` is reactive; every imperative read/write lives on `.repo` (the plain remult repo). The builder no longer hoists `findFirst`/`findId`/`insert`/... - use `ffRepo(E).repo.*`.
+
+  Also new: `infiniteScroll` (svelte attachment, pairs with `paginate`), `stackHttpClient`/`withHeader` (core), `FF_Filter.containsWords` (multi-field search filter), `splitTrim` (formats), and exported types including the umbrella `FF_Repo` handle plus `FF_RepoBuilder`/`FF_RepoLoad`/`FF_RepoLive`/`FF_RepoPaginate`/`FF_RepoOne`/`QueryOptionsHelper`/`AggregateOptions`.
+
+  Migration (see `/docs/svelte/ff-repo`):
+  - `new FF_Repo(E, { findOptions: { where } })` -> `ffRepo(E).load(() => ({ where }))`
+  - `new FF_Repo(E, { queryOptions })` + `.query()/.queryMore()/.queryRefresh()` -> `ffRepo(E).paginate(() => ({ ... }))` + `.more()/.refresh()`
+  - `r.globalError` -> `r.error`
+  - `r.fields` -> `r.meta.fields`; `r.metadata.apiInsertAllowed()` -> `r.meta.apiInsertAllowed()`
+  - `repo(r.ent).update(...)` / `.insert(...)` -> `r.update(...)` / `r.insert(...)`
+  - `r.aggregates.$count` unchanged; `skipAutoFetch` -> `enabled: false`
+
 ## 0.4.5
 
 ### Patch Changes

package/esm/core/FF_Filter.d.ts

@@ -1,7 +1,9 @@
 /**
- * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ * Filter helpers that build a remult `EntityFilter`.
  *
- * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ * `owner` / `ownerOr` are prefilters (for `apiPrefilter`, `backendPrefilter`) -
+ * pair with `FF_Allow` (the equivalent for `allowApi*` row checks). `containsWords`
+ * is a search-box helper (pairs with `ffRepo(...).load/paginate`).
  *
  * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
  * autocompletion and type-safety on the column name. Without a generic the
@@ -52,4 +54,17 @@ export declare const FF_Filter: {
         col?: keyof T & string;
         roles: string[];
     }) => any;
+    /**
+     * Build a search filter where every word must match (AND) and each word may
+     * match any of the given fields (OR), case-insensitive `$contains`. Word order
+     * and which field holds which word don't matter - handy for "NOM Prénom" search.
+     *
+     * @example
+     * ```ts
+     * const r = ffRepo(User).load(() => ({
+     *   where: FF_Filter.containsWords([repo(User).fields.name, repo(User).fields.sesa], q),
+     * }))
+     * ```
+     */
+    containsWords: <Entity>(fields: import("remult").FieldMetadata<unknown, Entity>[], search: string) => import("remult").EntityFilter<Entity>;
 };

package/esm/core/FF_Filter.js

@@ -1,8 +1,11 @@
 import { remult } from 'remult';
+import { containsWords } from './containsWords.js';
 /**
- * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ * Filter helpers that build a remult `EntityFilter`.
  *
- * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ * `owner` / `ownerOr` are prefilters (for `apiPrefilter`, `backendPrefilter`) -
+ * pair with `FF_Allow` (the equivalent for `allowApi*` row checks). `containsWords`
+ * is a search-box helper (pairs with `ffRepo(...).load/paginate`).
  *
  * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
  * autocompletion and type-safety on the column name. Without a generic the
@@ -54,4 +57,17 @@ export const FF_Filter = {
             return {};
         return { [col]: [remult.user?.id] };
     },
+    /**
+     * Build a search filter where every word must match (AND) and each word may
+     * match any of the given fields (OR), case-insensitive `$contains`. Word order
+     * and which field holds which word don't matter - handy for "NOM Prénom" search.
+     *
+     * @example
+     * ```ts
+     * const r = ffRepo(User).load(() => ({
+     *   where: FF_Filter.containsWords([repo(User).fields.name, repo(User).fields.sesa], q),
+     * }))
+     * ```
+     */
+    containsWords,
 };

package/esm/core/containsWords.d.ts

@@ -0,0 +1,13 @@
+import type { EntityFilter, FieldMetadata } from 'remult';
+/**
+ * Builds a filter where every word in `search` must match (AND), and each word
+ * may match any of the given fields (OR), using case-insensitive `$contains`.
+ *
+ * E.g. "dupont marie" over [name, sesa] =>
+ *   (name~dupont OR sesa~dupont) AND (name~marie OR sesa~marie)
+ *
+ * So word order and which field holds which word don't matter - handy for
+ * "NOM Prénom" style search across several columns. Pairs with `ffRepo`:
+ * `ffRepo(User).load(() => ({ where: containsWords([f.name, f.sesa], q) }))`.
+ */
+export declare const containsWords: <Entity>(fields: FieldMetadata<unknown, Entity>[], search: string) => EntityFilter<Entity>;

package/esm/core/containsWords.js

@@ -0,0 +1,27 @@
+/**
+ * Builds a filter where every word in `search` must match (AND), and each word
+ * may match any of the given fields (OR), using case-insensitive `$contains`.
+ *
+ * E.g. "dupont marie" over [name, sesa] =>
+ *   (name~dupont OR sesa~dupont) AND (name~marie OR sesa~marie)
+ *
+ * So word order and which field holds which word don't matter - handy for
+ * "NOM Prénom" style search across several columns. Pairs with `ffRepo`:
+ * `ffRepo(User).load(() => ({ where: containsWords([f.name, f.sesa], q) }))`.
+ */
+export const containsWords = (fields, search) => {
+    const words = (search ?? '').split(' ').filter((s) => s.length > 0);
+    if (words.length === 0 || fields.length === 0) {
+        return {};
+    }
+    if (fields.length === 1) {
+        return {
+            $and: words.map((s) => ({ [fields[0].key]: { $contains: s } })),
+        };
+    }
+    return {
+        $and: words.map((s) => ({
+            $or: fields.map((f) => ({ [f.key]: { $contains: s } })),
+        })),
+    };
+};

package/esm/core/httpClientStack.d.ts

@@ -0,0 +1,18 @@
+export type HttpClientFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type HttpClientMiddleware = (next: HttpClientFetch) => HttpClientFetch;
+/**
+ * Compose `fetch` middlewares into a single `fetch`-shaped function. Middlewares
+ * run outermost-first (the first argument wraps the rest). Useful to inject auth
+ * headers, correlation ids, retries, logging, ... around a base `fetch`.
+ *
+ * ```ts
+ * const client = stackHttpClient(
+ *   withHeader('x-correlation-id', () => crypto.randomUUID()),
+ *   withHeader('authorization', () => `Bearer ${token}`),
+ * )
+ * await client('/api/...')
+ * ```
+ */
+export declare function stackHttpClient(...middlewares: HttpClientMiddleware[]): HttpClientFetch;
+/** Middleware that sets a request header from `getValue()` when it returns a value. */
+export declare function withHeader(name: string, getValue: () => string | undefined | null): HttpClientMiddleware;

package/esm/core/httpClientStack.js

@@ -0,0 +1,26 @@
+/**
+ * Compose `fetch` middlewares into a single `fetch`-shaped function. Middlewares
+ * run outermost-first (the first argument wraps the rest). Useful to inject auth
+ * headers, correlation ids, retries, logging, ... around a base `fetch`.
+ *
+ * ```ts
+ * const client = stackHttpClient(
+ *   withHeader('x-correlation-id', () => crypto.randomUUID()),
+ *   withHeader('authorization', () => `Bearer ${token}`),
+ * )
+ * await client('/api/...')
+ * ```
+ */
+export function stackHttpClient(...middlewares) {
+    return middlewares.reduceRight((next, mw) => mw(next), (input, init) => fetch(input, init));
+}
+/** Middleware that sets a request header from `getValue()` when it returns a value. */
+export function withHeader(name, getValue) {
+    return (next) => async (input, init) => {
+        const headers = new Headers(init?.headers);
+        const value = getValue();
+        if (value)
+            headers.set(name, value);
+        return next(input, { ...init, headers });
+    };
+}

package/esm/formats/index.d.ts

@@ -1,4 +1,4 @@
 export { displayCurrency, displayCurrencyK, displayPercent, displayCurrencyWOSuffix, } from './numbers.js';
-export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, } from './strings.js';
+export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, splitTrim, } from './strings.js';
 export { offsetedToPlainDate, plainDateCompare, isBetween, dateISOToPlainDate } from './dates.js';
 export type { KitPlainDateRange } from './dates.js';

package/esm/formats/index.js

@@ -1,3 +1,3 @@
 export { displayCurrency, displayCurrencyK, displayPercent, displayCurrencyWOSuffix, } from './numbers.js';
-export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, } from './strings.js';
+export { formatNumber, extractMailInfo, slugify, nameify, displayPhone, suffixWithS, arrToStr, mask, toTitleCase, splitTrim, } from './strings.js';
 export { offsetedToPlainDate, plainDateCompare, isBetween, dateISOToPlainDate } from './dates.js';

package/esm/formats/strings.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Split a string into a flat list of trimmed, non-empty tokens. The default
+ * separator handles comma- and newline-separated input.
+ *
+ * `"a, b\n,c"` -> `["a", "b", "c"]`
+ */
+export declare const splitTrim: (input?: string | null, separator?: string | RegExp) => string[];
 export declare const formatNumber: (number: number, digitNumber?: number) => string;
 export declare function displayPhone(_entity: any, value: string | undefined): string;
 export declare const arrToStr: (arr: string | undefined | (string | undefined)[]) => string;

package/esm/formats/strings.js

@@ -1,3 +1,15 @@
+/** Default separator for `splitTrim`: any run of commas and/or newlines. */
+const COMMA_OR_NEWLINE = /[,\n]+/;
+/**
+ * Split a string into a flat list of trimmed, non-empty tokens. The default
+ * separator handles comma- and newline-separated input.
+ *
+ * `"a, b\n,c"` -> `["a", "b", "c"]`
+ */
+export const splitTrim = (input, separator = COMMA_OR_NEWLINE) => (input ?? '')
+    .split(separator)
+    .map((s) => s.trim())
+    .filter(Boolean);
 export const formatNumber = (number, digitNumber = 2) => {
     if (number === undefined || number === null || isNaN(number)) {
         const value = 0;

package/esm/index.d.ts

@@ -15,6 +15,8 @@ export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export type { ResolvedType, UnArray, RecursivePartial } from './core/types.js';
 export { tw } from './core/tailwind.js';
+export { stackHttpClient, withHeader } from './core/httpClientStack.js';
+export type { HttpClientFetch, HttpClientMiddleware } from './core/httpClientStack.js';
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';
 export { UIEntity } from './virtual/UIEntity.js';

package/esm/index.js

@@ -15,6 +15,7 @@ export { FF_Validators, createValidators } from './core/FF_Validators.js';
 export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export { tw } from './core/tailwind.js';
+export { stackHttpClient, withHeader } from './core/httpClientStack.js';
 // Misc primitives still exposed from the root.
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';

package/esm/svelte/DemoGrid.svelte

@@ -0,0 +1,167 @@
+<script lang="ts" generics="T extends { id: string }">
+	import type { ClassType, EntityFilter, MembersOnly } from 'remult'
+
+	import { ffRepo } from './FF_Repo.svelte.js'
+
+	type Props = {
+		/** The remult entity class to CRUD. */
+		entity: ClassType<T>
+		/** Fields to show as columns / edit inputs. Headers come from each field's `caption`. */
+		fields: (keyof T & string)[]
+	}
+	let { entity, fields }: Props = $props()
+
+	// live list - any write re-emits it, so no reconcile code (entity is static config)
+	const list = ffRepo(entity).listen(() => ({}))
+
+	// the row being edited (by id), or a fresh draft for "new" - one reactive slot
+	let editingId = $state<string | null>(null)
+	const editor = ffRepo(entity).one(() => ({
+		where: { id: editingId ?? '' } as EntityFilter<T>,
+		enabled: !!editingId,
+	}))
+	const creating = $derived(!!editor.item && !editor.item.id)
+
+	// dynamic read/write of a field by key (v1: inputs are text)
+	const get = (row: T, f: keyof T & string) => (row as Record<string, unknown>)[f]
+	function setField(f: keyof T & string, value: string) {
+		if (editor.item) (editor.item as Record<string, unknown>)[f] = value
+	}
+
+	function edit(id: string) {
+		editingId = id // → editor.item loads that row
+	}
+	function add() {
+		editingId = null
+		editor.create() // blank draft into editor.item
+	}
+	function cancel() {
+		editingId = null
+		editor.item = undefined // drop the draft / stop editing
+	}
+	async function save() {
+		await editor.save() // insert (a draft) or update (the loaded row); the live list self-syncs
+		cancel()
+	}
+	async function remove(row: T) {
+		await list.repo.delete(row as Partial<MembersOnly<T>>) // raw delete via .repo; the live list drops the row
+	}
+</script>
+
+{#snippet editRow(draft: T)}
+	{#each fields as f (f)}
+		<td>
+			<input
+				placeholder={list.meta.fields.find(f)?.caption ?? f}
+				value={String(get(draft, f) ?? '')}
+				oninput={(e) => setField(f, e.currentTarget.value)}
+			/>
+		</td>
+	{/each}
+	<td class="actions">
+		<button disabled={editor.loading.saving} onclick={save}>Save</button>
+		<button onclick={cancel}>Cancel</button>
+	</td>
+{/snippet}
+
+<div class="crud">
+	<button class="new" onclick={add}>+ New</button>
+
+	<table>
+		<thead>
+			<tr>
+				{#each fields as f (f)}<th>{list.meta.fields.find(f)?.caption ?? f}</th>{/each}
+				<th></th>
+			</tr>
+		</thead>
+		<tbody>
+			{#if creating && editor.item}
+				<tr class="editing">{@render editRow(editor.item)}</tr>
+			{/if}
+			{#each list.items as row (row.id)}
+				<tr class:editing={editingId === row.id}>
+					{#if editingId === row.id && editor.item}
+						{@render editRow(editor.item)}
+					{:else}
+						{#each fields as f (f)}<td>{get(row, f)}</td>{/each}
+						<td class="actions">
+							<button onclick={() => edit(row.id)}>Edit</button>
+							<button onclick={() => remove(row)}>Delete</button>
+						</td>
+					{/if}
+				</tr>
+			{/each}
+		</tbody>
+	</table>
+
+	{#if list.loading.init}
+		<p class="muted">Loading…</p>
+	{:else if list.items.length === 0 && !creating}
+		<p class="muted">Nothing yet - hit “+ New”.</p>
+	{/if}
+</div>
+
+<style>
+	.crud {
+		font-size: 14px;
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+		align-items: start;
+	}
+	table {
+		border-collapse: collapse;
+		width: 100%;
+	}
+	th,
+	td {
+		border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+		padding: 7px 10px;
+		text-align: left;
+		vertical-align: middle;
+	}
+	th {
+		font-weight: 600;
+		background: color-mix(in srgb, currentColor 7%, transparent);
+	}
+	tr.editing {
+		background: color-mix(in srgb, currentColor 5%, transparent);
+	}
+	td.actions {
+		white-space: nowrap;
+		text-align: right;
+	}
+	td.actions button + button {
+		margin-left: 6px;
+	}
+	input {
+		width: 100%;
+		box-sizing: border-box;
+		padding: 5px 7px;
+		font: inherit;
+		color: inherit;
+		background: transparent;
+		border: 1px solid color-mix(in srgb, currentColor 30%, transparent);
+		border-radius: 6px;
+	}
+	button {
+		cursor: pointer;
+		font: inherit;
+		padding: 4px 11px;
+		color: inherit;
+		background: color-mix(in srgb, currentColor 6%, transparent);
+		border: 1px solid color-mix(in srgb, currentColor 22%, transparent);
+		border-radius: 6px;
+		transition: background 0.12s ease;
+	}
+	button:hover {
+		background: color-mix(in srgb, currentColor 14%, transparent);
+	}
+	button:disabled {
+		opacity: 0.45;
+		cursor: not-allowed;
+	}
+	.muted {
+		opacity: 0.6;
+	}
+</style>

package/esm/svelte/DemoGrid.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { ClassType } from 'remult';
+declare function $$render<T extends {
+    id: string;
+}>(): {
+    props: {
+        /** The remult entity class to CRUD. */
+        entity: ClassType<T>;
+        /** Fields to show as columns / edit inputs. Headers come from each field's `caption`. */
+        fields: (keyof T & string)[];
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends {
+    id: string;
+}> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends {
+        id: string;
+    }>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends {
+        id: string;
+    }>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DemoGrid: $$IsomorphicComponent;
+type DemoGrid<T extends {
+    id: string;
+}> = InstanceType<typeof DemoGrid<T>>;
+export default DemoGrid;