firstly 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # firstly
 
+## 0.4.1
+
+### Patch Changes
+
+- [#250](https://github.com/jycouet/firstly/pull/250) [`53916ad`](https://github.com/jycouet/firstly/commit/53916ad519835a47e3598afb68ce6d84356af944) Thanks [@jycouet](https://github.com/jycouet)! - Add `firstly/sqlAdmin` module: a drop-in `<SqlAdmin />` Svelte component plus a `BackendMethod` controller gated by `Roles_SqlAdmin.SqlAdmin_Admin` (or `FF_Role.FF_Role_Admin`). The component ships with prefilled queries (DB size, table sizes, indexes) and logs results as `for AI: <rows>` to the browser console for chrome-devtools / AI-agent inspection. `sqlAdmin({ path })` logs an AI hint on server start pointing to the page (default `/sql/admin`).
+
+  Add `FF_Allow` and `FF_Filter` helpers (exported from `firstly`) for owner-only / admin-or-owner row checks and prefilters - usable in `allowApi*` and `apiPrefilter`. Both accept an entity generic (`FF_Allow.owner<Task>('userId')`) for type-safe column names; `col` defaults to `'userId'` if omitted. The `ownerOr<T>({ col?, roles })` variants are shortcuts for the "admin (or any role) OR owner" pattern.
+
 ## 0.4.0
 
 ### Minor Changes

package/esm/core/FF_Allow.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Row-level allow helpers (for `allowApiUpdate`, `allowApiDelete`, ...).
+ *
+ * Pair with `FF_Filter` (the equivalent for `apiPrefilter`).
+ *
+ * Pass the entity type as a generic (`FF_Allow.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export declare const FF_Allow: {
+    /**
+     * Allow only when the row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Owner-only update / delete (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.owner<Task>('userId'), // typed: 'userId' must be a key of Task
+     *   allowApiDelete: FF_Allow.owner<Task>(),        // defaults to 'userId'
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin OR owner", prefer `FF_Allow.ownerOr` instead of inlining the
+     * combination yourself.
+     */
+    owner: <T>(col?: keyof T & string) => (entity?: T) => boolean;
+    /**
+     * Allow when the current user has any of the given `roles`, OR when the
+     * row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin OR owner (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.ownerOr<Task>({ roles: [Roles.Admin] }),
+     *   allowApiDelete: FF_Allow.ownerOr<Task>({ col: 'createdBy', roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: <T>({ col, roles }: {
+        col?: keyof T & string;
+        roles: string[];
+    }) => (entity?: T) => boolean;
+};

package/esm/core/FF_Allow.js

@@ -0,0 +1,54 @@
+import { remult } from 'remult';
+/**
+ * Row-level allow helpers (for `allowApiUpdate`, `allowApiDelete`, ...).
+ *
+ * Pair with `FF_Filter` (the equivalent for `apiPrefilter`).
+ *
+ * Pass the entity type as a generic (`FF_Allow.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export const FF_Allow = {
+    /**
+     * Allow only when the row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Owner-only update / delete (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.owner<Task>('userId'), // typed: 'userId' must be a key of Task
+     *   allowApiDelete: FF_Allow.owner<Task>(),        // defaults to 'userId'
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin OR owner", prefer `FF_Allow.ownerOr` instead of inlining the
+     * combination yourself.
+     */
+    owner: (col = 'userId') => (entity) => !!remult.user?.id && entity?.[col] === remult.user.id,
+    /**
+     * Allow when the current user has any of the given `roles`, OR when the
+     * row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin OR owner (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.ownerOr<Task>({ roles: [Roles.Admin] }),
+     *   allowApiDelete: FF_Allow.ownerOr<Task>({ col: 'createdBy', roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: ({ col = 'userId', roles }) => (entity) => roles.some((r) => remult.isAllowed(r)) ||
+        (!!remult.user?.id && entity?.[col] === remult.user.id),
+};

package/esm/core/FF_Filter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ *
+ * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ *
+ * 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
+ * column is just a `string`.
+ */
+export declare const FF_Filter: {
+    /**
+     * Prefilter rows where `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted. When anonymous, yields
+     * `IN (NULL)` which matches nothing.
+     *
+     * @example
+     * Owner-only prefilter (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.owner<Task>('userId'),
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin sees all, others see only their own", prefer
+     * `FF_Filter.ownerOr` instead of inlining the combination yourself.
+     */
+    owner: <T>(col?: keyof T & string) => any;
+    /**
+     * Prefilter that returns `{}` (no filter) when the current user has any of
+     * the given `roles`, otherwise restricts to rows where `col` equals the
+     * current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin sees all, others only their own (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.ownerOr<Task>({ roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: <T>({ col, roles, }: {
+        col?: keyof T & string;
+        roles: string[];
+    }) => any;
+};

package/esm/core/FF_Filter.js

@@ -0,0 +1,57 @@
+import { remult } from 'remult';
+/**
+ * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ *
+ * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ *
+ * 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
+ * column is just a `string`.
+ */
+export const FF_Filter = {
+    /**
+     * Prefilter rows where `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted. When anonymous, yields
+     * `IN (NULL)` which matches nothing.
+     *
+     * @example
+     * Owner-only prefilter (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.owner<Task>('userId'),
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin sees all, others see only their own", prefer
+     * `FF_Filter.ownerOr` instead of inlining the combination yourself.
+     */
+    owner: (col = 'userId') => ({ [col]: [remult.user?.id] }),
+    /**
+     * Prefilter that returns `{}` (no filter) when the current user has any of
+     * the given `roles`, otherwise restricts to rows where `col` equals the
+     * current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin sees all, others only their own (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.ownerOr<Task>({ roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: ({ col = 'userId', roles, }) => {
+        if (roles.some((r) => remult.isAllowed(r)))
+            return {};
+        return { [col]: [remult.user?.id] };
+    },
+};

package/esm/index.d.ts

@@ -7,6 +7,8 @@ export { BaseEnum } from './core/BaseEnum.js';
 export type { BaseEnumOptions, BaseItem, BaseItemLight, FF_Icon } from './core/BaseEnum.js';
 export { FF_Entity } from './core/FF_Entity.js';
 export { FF_Role } from './core/common.js';
+export { FF_Allow } from './core/FF_Allow.js';
+export { FF_Filter } from './core/FF_Filter.js';
 export { isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export type { ResolvedType, UnArray, RecursivePartial } from './core/types.js';

package/esm/index.js

@@ -9,6 +9,8 @@ export const ff_Log = new h.Log('firstly');
 export { BaseEnum } from './core/BaseEnum.js';
 export { FF_Entity } from './core/FF_Entity.js';
 export { FF_Role } from './core/common.js';
+export { FF_Allow } from './core/FF_Allow.js';
+export { FF_Filter } from './core/FF_Filter.js';
 export { isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export { tw } from './core/tailwind.js';

package/esm/sqlAdmin/Roles_SqlAdmin.d.ts

@@ -0,0 +1,3 @@
+export declare const Roles_SqlAdmin: {
+    readonly SqlAdmin_Admin: "SqlAdmin.Admin";
+};

package/esm/sqlAdmin/Roles_SqlAdmin.js

@@ -0,0 +1,3 @@
+export const Roles_SqlAdmin = {
+    SqlAdmin_Admin: 'SqlAdmin.Admin',
+};

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -0,0 +1,9 @@
+import { SqlDatabase } from 'remult';
+export declare class SqlAdminController {
+    /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
+    static dp?: SqlDatabase;
+    static exec(cmd: string): Promise<{
+        r: import("remult").SqlResult;
+        took: number;
+    }>;
+}

package/esm/sqlAdmin/SqlAdminController.js

@@ -0,0 +1,23 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BackendMethod, SqlDatabase } from 'remult';
+import { FF_Role } from '../core/common';
+import { Roles_SqlAdmin } from './Roles_SqlAdmin';
+export class SqlAdminController {
+    /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
+    static dp;
+    static async exec(cmd) {
+        const db = SqlAdminController.dp ?? SqlDatabase.getDb();
+        const start = performance.now();
+        const r = await db.execute(cmd);
+        const took = performance.now() - start;
+        return { r, took };
+    }
+}
+__decorate([
+    BackendMethod({ allowed: [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin] })
+], SqlAdminController, "exec", null);

package/esm/sqlAdmin/index.d.ts

@@ -0,0 +1,6 @@
+import { Log } from '@kitql/helpers';
+export { Roles_SqlAdmin } from './Roles_SqlAdmin';
+export { SqlAdminController } from './SqlAdminController';
+export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export declare const key = "sqlAdmin";
+export declare const log: Log;

package/esm/sqlAdmin/index.js

@@ -0,0 +1,6 @@
+import { Log } from '@kitql/helpers';
+export { Roles_SqlAdmin } from './Roles_SqlAdmin';
+export { SqlAdminController } from './SqlAdminController';
+export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export const key = 'sqlAdmin';
+export const log = new Log(key);

package/esm/sqlAdmin/server/index.d.ts

@@ -0,0 +1,40 @@
+import type { SqlDatabase } from 'remult';
+import { Module } from 'remult/server';
+export type SqlAdminOptions = {
+    /**
+     * Override the SqlDatabase used to execute queries.
+     * Defaults to `SqlDatabase.getDb()` (the active Remult data provider).
+     */
+    dp?: () => SqlDatabase | Promise<SqlDatabase>;
+    /**
+     * The route where you mounted the `<SqlAdmin />` component.
+     * Used only for the AI hint logged on server start.
+     *
+     * @default '/sql/admin'
+     */
+    path?: string;
+};
+/**
+ * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).
+ *
+ * Gated by `Roles_SqlAdmin.SqlAdmin_Admin` (or the global `FF_Role.FF_Role_Admin`).
+ *
+ * @example
+ * ```ts
+ * import { remultApi } from 'remult/remult-sveltekit'
+ * import { sqlAdmin } from './'
+ *
+ * export const api = remultApi({
+ *   modules: [sqlAdmin()],
+ * })
+ * ```
+ *
+ * Then on any admin route:
+ * ```svelte
+ * <script>
+ *   import { SqlAdmin } from '..'
+ * </script>
+ * <SqlAdmin />
+ * ```
+ */
+export declare const sqlAdmin: (opts?: SqlAdminOptions) => Module<unknown>;

package/esm/sqlAdmin/server/index.js

@@ -0,0 +1,40 @@
+import { Module } from 'remult/server';
+import { yellow } from '@kitql/helpers';
+import { log } from '..';
+import { SqlAdminController } from '../SqlAdminController';
+/**
+ * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).
+ *
+ * Gated by `Roles_SqlAdmin.SqlAdmin_Admin` (or the global `FF_Role.FF_Role_Admin`).
+ *
+ * @example
+ * ```ts
+ * import { remultApi } from 'remult/remult-sveltekit'
+ * import { sqlAdmin } from './'
+ *
+ * export const api = remultApi({
+ *   modules: [sqlAdmin()],
+ * })
+ * ```
+ *
+ * Then on any admin route:
+ * ```svelte
+ * <script>
+ *   import { SqlAdmin } from '..'
+ * </script>
+ * <SqlAdmin />
+ * ```
+ */
+export const sqlAdmin = (opts) => {
+    const path = opts?.path ?? '/sql/admin';
+    return new Module({
+        key: 'sqlAdmin',
+        controllers: [SqlAdminController],
+        initApi: async () => {
+            if (opts?.dp) {
+                SqlAdminController.dp = await opts.dp();
+            }
+            log.info(`AI Hint: visit ${yellow(path)} to query raw SQL.`);
+        },
+    });
+};

package/esm/sqlAdmin/ui/SqlAdmin.svelte

@@ -0,0 +1,146 @@
+<script lang="ts">
+	/**
+	 * SQL Admin UI.
+	 *
+	 * Results are logged to the browser console as `for AI: <json rows>` after
+	 * each successful query - chrome-devtools / AI agents inspecting the page
+	 * can read them with `list_console_messages`.
+	 */
+	import { SqlAdminController } from '../SqlAdminController'
+
+	const defaultQuery = `SELECT *
+FROM "public"."users"
+LIMIT 10`
+
+	let sqlInput = $state(defaultQuery)
+	let result: any = $state()
+	let error = $state('')
+	let isLoading = $state(false)
+
+	const queries = {
+		default: { label: 'Default', sql: defaultQuery },
+		tables: {
+			label: 'Tables & Sizes',
+			sql: `SELECT
+  table_schema,
+  table_name,
+  pg_size_pretty(pg_total_relation_size(quote_ident(table_schema) || '.' || quote_ident(table_name))) as total_size,
+  pg_size_pretty(pg_table_size(quote_ident(table_schema) || '.' || quote_ident(table_name))) as data_size,
+  pg_size_pretty(pg_indexes_size(quote_ident(table_schema) || '.' || quote_ident(table_name))) as index_size
+FROM information_schema.tables
+WHERE table_schema IN ('public', 'ff_auth')
+ORDER BY pg_total_relation_size(quote_ident(table_schema) || '.' || quote_ident(table_name)) DESC;`,
+		},
+		indexes: {
+			label: 'Indexes',
+			sql: `SELECT *
+FROM pg_indexes
+WHERE schemaname = 'public'
+ORDER BY tablename, indexname`,
+		},
+		dbSize: {
+			label: 'Database Size',
+			sql: `SELECT
+  current_database() as database_name,
+  pg_size_pretty(pg_database_size(current_database())) as database_size`,
+		},
+	} as const
+
+	console.info(
+		'[firstly/SqlAdmin] AI Hint: results are also logged as "for AI:" JSON after each query.',
+	)
+
+	function setPresetQuery(queryId: keyof typeof queries) {
+		sqlInput = queries[queryId].sql
+	}
+
+	async function handleSubmit(e: Event) {
+		e.preventDefault()
+		try {
+			error = ''
+			isLoading = true
+			result = { ...(await SqlAdminController.exec(sqlInput)) }
+			console.info('for AI:', JSON.stringify(result.r.rows))
+			console.info('for humans:', result)
+		} catch (e) {
+			error = JSON.stringify(e, null, 2)
+		} finally {
+			isLoading = false
+		}
+	}
+
+	function getHeaders(rows: any[]): string[] {
+		if (!rows || rows.length === 0) return []
+		return Object.keys(rows[0])
+	}
+</script>
+
+<div class="flex flex-col gap-4">
+	<div class="flex flex-col gap-2">
+		<h2 class="text-2xl font-bold">SQL Admin</h2>
+		<p class="text-sm text-base-content/70">
+			Execute SQL queries directly on the database. Results are displayed below and also logged to the
+			browser console.
+		</p>
+	</div>
+	<div class="flex flex-wrap gap-2">
+		{#each Object.entries(queries) as [id, query] (id)}
+			<button class="btn btn-outline btn-sm" onclick={() => setPresetQuery(id as keyof typeof queries)}
+				>{query.label}</button
+			>
+		{/each}
+	</div>
+	<form onsubmit={handleSubmit} class="flex flex-col gap-4">
+		<fieldset class="fieldset">
+			<textarea
+				bind:value={sqlInput}
+				class="textarea h-52 w-full font-mono"
+				placeholder="Enter SQL command..."
+				disabled={isLoading}
+			></textarea>
+		</fieldset>
+		<div class="flex items-center gap-4">
+			<button type="submit" class="btn btn-primary" disabled={isLoading}>
+				{#if isLoading}<span class="loading loading-spinner"></span>{/if}
+				Execute SQL
+			</button>
+			{#if error}<pre class="alert flex-1 text-sm alert-error">{error.replaceAll(
+						'\\n',
+						'\n',
+					)}</pre>{/if}
+			{#if result}
+				<div class="alert flex flex-1 justify-between alert-success">
+					<span class="text-success-content">{result.took.toFixed(0)} ms</span>
+					<span class="text-success-content">{result.r.rowCount} rows</span>
+				</div>
+			{/if}
+		</div>
+	</form>
+	{#if result}
+		<div class="max-h-[600px] overflow-auto rounded-lg border border-base-300">
+			{#if result.r.rows && result.r.rows.length > 0}
+				<table class="table w-full table-zebra bg-base-200">
+					<thead class="sticky top-0 z-10 bg-base-300">
+						<tr
+							>{#each getHeaders(result.r.rows) as header, i (i)}<th>{header}</th>{/each}</tr
+						>
+					</thead>
+					<tbody>
+						{#each result.r.rows as row, r (r)}
+							<tr>
+								{#each Object.values(row) as cell, c (c)}
+									<td class="align-top">
+										{#if typeof cell === 'object'}<pre class="text-xs">{JSON.stringify(cell, null, 2)}</pre>
+										{:else}{cell === null ? 'null' : cell}{/if}
+									</td>
+								{/each}
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			{:else}
+				<div class="alert alert-info">No rows returned</div>
+			{/if}
+		</div>
+	{/if}
+</div>

package/esm/sqlAdmin/ui/SqlAdmin.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const SqlAdmin: import("svelte").Component<Record<string, never>, {}, "">;
+type SqlAdmin = ReturnType<typeof SqlAdmin>;
+export default SqlAdmin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",
@@ -98,6 +98,15 @@
     "./carbone/server": {
       "types": "./esm/carbone/server/index.d.ts",
       "default": "./esm/carbone/server/index.js"
+    },
+    "./sqlAdmin": {
+      "types": "./esm/sqlAdmin/index.d.ts",
+      "svelte": "./esm/sqlAdmin/index.js",
+      "default": "./esm/sqlAdmin/index.js"
+    },
+    "./sqlAdmin/server": {
+      "types": "./esm/sqlAdmin/server/index.d.ts",
+      "default": "./esm/sqlAdmin/server/index.js"
     }
   },
   "keywords": [