@navette-js/database 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 Data adapters (Objection/Knex) for Navette panels.
 
-Part of [Navette](https://github.com/NavetteJS/navette), a Node.js port of [Filament](https://filamentphp.com). Install the whole framework with `npm install @navette-js/panels`.
+Part of [Navette](https://github.com/NavetteJS/navette), admin panels for Node.js. Start a project with `npm create navette@latest`, or install the framework with `npm install @navette-js/panels`.
 
 **Beta:** the API may still change between beta releases.
 

package/lib/index.d.ts

@@ -4,23 +4,23 @@ export { Model };
 export type { Knex };
 export type SortDirection = 'asc' | 'desc';
 export type ListQuery = {
-    /** Recherche globale : chaque mot doit apparaître dans au moins une des colonnes cherchables. */
+    /** Global search: every word must appear in at least one of the searchable columns. */
     search?: string | null;
     searchColumns?: string[];
-    /** Recherche par colonne : toutes les conditions doivent être vraies. */
+    /** Per-column search: all conditions must match. */
     columnSearches?: Record<string, string>;
-    /** Enregistrements supprimés (suppression douce) : exclus par défaut, inclus, ou seuls. */
+    /** Soft-deleted records: excluded by default, included, or only those. */
     trashed?: 'without' | 'with' | 'only';
     sort?: {
         column: string;
         direction: SortDirection;
     } | null;
-    /** Regroupement de table : ce tri passe avant `sort`. */
+    /** Table grouping: this sort is applied before `sort`. */
     groupSort?: {
         column: string;
         direction: SortDirection;
     } | null;
-    /** Conditions supplémentaires posées par le serveur (onglet de liste, filtre sur mesure) : jamais construites à partir de données du navigateur non validées. */
+    /** Extra server-side conditions (list tab, custom filter); never built from unvalidated browser input. */
     modifiers?: ((query: any) => void)[];
     page: number;
     perPage: number;
@@ -34,13 +34,13 @@ export type Page<T> = {
     from: number | null;
     to: number | null;
 };
-/** Ce dont le framework a besoin pour lister, lire et écrire des enregistrements, sans connaître l'ORM. */
+/** What the framework needs to list, read and write records, independently of the ORM. */
 export interface DataAdapter<T = any> {
     getKey(record: T): string;
-    /** Filtre des clés reçues du navigateur : seules celles de la portée de l'adaptateur sont rendues. */
+    /** Filters keys received from the browser: only those within the adapter's scope are returned. */
     keysInScope(keys: (string | number)[]): Promise<string[]>;
     sum(query: Omit<ListQuery, 'page' | 'perPage'>, columns: string[]): Promise<Record<string, number>>;
-    /** Agrégats sur les enregistrements d'une requête de liste : nombre, sommes et moyennes de colonnes. */
+    /** Aggregates over the records of a list query: count, and column sums, averages, minimums and maximums. */
     aggregate(query: Omit<ListQuery, 'page' | 'perPage'>, columns?: {
         sum?: string[];
         avg?: string[];
@@ -60,27 +60,29 @@ export interface DataAdapter<T = any> {
     create(data: Record<string, unknown>): Promise<T>;
     update(key: string | number, data: Record<string, unknown>): Promise<T | null>;
     delete(key: string | number): Promise<boolean>;
-    /** Suppression douce : prise en charge, état d'un enregistrement, restauration, suppression définitive. */
+    /** Soft deletes: support, record state, restore, permanent delete. */
     supportsSoftDeletes(): boolean;
     isTrashed(record: T): boolean;
     restore(key: string | number): Promise<boolean>;
     forceDelete(key: string | number): Promise<boolean>;
-    /** Clés de tous les enregistrements correspondant à la requête (sans pagination), pour « tout sélectionner ». */
+    /** Keys of every record matching the query (unpaginated), for "select all". */
     listKeys(query: Omit<ListQuery, 'page' | 'perPage'>): Promise<string[]>;
     deleteMany(keys: (string | number)[]): Promise<number>;
-    /** Vrai si un autre enregistrement a déjà cette valeur (règle `unique`). */
+    /** True if another record already has this value (`unique` rule). */
     exists(column: string, value: unknown, exceptKey?: string | number | null): Promise<boolean>;
 }
 export declare function createConnection(config: Knex.Config): Knex;
-/** Connexion SQLite (pilote better-sqlite3), pour le développement et la démo. */
+/** SQLite connection (better-sqlite3 driver), for development and demos. */
 export declare function sqlite(filename: string): Knex;
 export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M> {
     private model;
     private modify;
     private softDeletes;
     private findsTrashed;
-    /** `softDeletes` : colonne d'horodatage de suppression (équivalent du trait SoftDeletes). `findsTrashed` : `find()` voit aussi les supprimés
-     *  (équivalent de `getRecordRouteBindingEloquentQuery()->withoutGlobalScopes([SoftDeletingScope::class])`). */
+    /**
+     * `modify`: base query constraints applied to every read. `softDeletes`: deletion timestamp column.
+     * `findsTrashed`: `find()` also returns soft-deleted records.
+     */
     constructor(model: ModelClass<M>, options?: {
         modify?: (query: QueryBuilder<M, M[]>) => void;
         softDeletes?: string;
@@ -88,8 +90,8 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
     });
     private tenantScope;
     /**
-     * Cloisonne l'adaptateur par locataire : toute lecture filtre sur `column`, toute création la renseigne,
-     * avec la clé rendue par `key()` (celle du locataire de la requête ; `null` : pas de filtre). Posé par le panel (`panel.tenant()`).
+     * Scopes the adapter to a tenant: every read filters on `column` and every create fills it, with the key returned by `key()`
+     * (the request's tenant; `null` means no filter). Set by the panel (`panel.tenant()`).
      */
     scopeToTenant(column: string, key: () => string | number | null): this;
     private base;
@@ -100,11 +102,11 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
     count(): Promise<number>;
     listKeys(query: Omit<ListQuery, 'page' | 'perPage'>): Promise<string[]>;
     /**
-     * Parmi des clés reçues du navigateur, celles qui appartiennent à la portée de l'adaptateur (`modify`, suppression douce comprise).
-     * Une sélection forgée ne peut ainsi pas viser un enregistrement que la table n'affiche pas.
+     * Keeps the browser-supplied keys that fall within the adapter's scope (`modify` and tenant; trashed records included),
+     * so a forged selection cannot target a record the table does not show.
      */
     keysInScope(keys: (string | number)[]): Promise<string[]>;
-    /** Somme de colonnes sur tous les enregistrements de la requête (pour les lignes de totaux). */
+    /** Count and column aggregates over every record of the query (for summary rows). */
     aggregate(query: Omit<ListQuery, 'page' | 'perPage'>, columns?: {
         sum?: string[];
         avg?: string[];
@@ -118,9 +120,8 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
         max: Record<string, unknown>;
     }>;
     /**
-     * Tendance mensuelle sur la requête filtrée (équivalent de `Trend::query(...)->between()->perMonth()->count()` ou `->average()`
-     * de flowframe/laravel-trend) : une valeur par mois de `start` à `end`, 0 pour un mois sans enregistrement.
-     * SQL de date écrit pour SQLite ; dates en UTC, au format `Y-m-d H:i:s`.
+     * Monthly trend over the filtered query (count, or average of `average`): one value per month from `start` to `end`,
+     * 0 for months without records. The date SQL targets SQLite; dates are UTC, formatted `Y-m-d H:i:s`.
      */
     trendPerMonth(query: Omit<ListQuery, 'page' | 'perPage'>, options: {
         start: Date;
@@ -132,13 +133,13 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
     sum(query: Omit<ListQuery, 'page' | 'perPage'>, columns: string[]): Promise<Record<string, number>>;
     deleteMany(keys: (string | number)[]): Promise<number>;
     paginate(query: ListQuery): Promise<Page<M>>;
-    /** Requête de base avec recherche globale et recherches par colonne appliquées. */
+    /** Base query with modifiers, global search and per-column searches applied. */
     private filtered;
     private finishPagination;
     find(key: string | number): Promise<M | null>;
     create(data: Record<string, unknown>): Promise<M>;
     update(key: string | number, data: Record<string, unknown>): Promise<M | null>;
-    /** Avec suppression douce, l'enregistrement est horodaté, pas retiré. */
+    /** With soft deletes, the record is timestamped instead of removed. */
     delete(key: string | number): Promise<boolean>;
     supportsSoftDeletes(): boolean;
     isTrashed(record: M): boolean;

package/lib/index.js

@@ -1,4 +1,4 @@
-// @navette-js/database — contrat d'accès aux données (ADR 0005) et premier adaptateur : Knex + Objection.
+// @navette-js/database — data access contract and its Knex + Objection adapter.
 import knexFactory from 'knex';
 import { Model } from 'objection';
 export { Model };
@@ -7,7 +7,7 @@ export function createConnection(config) {
     Model.knex(knex);
     return knex;
 }
-/** Connexion SQLite (pilote better-sqlite3), pour le développement et la démo. */
+/** SQLite connection (better-sqlite3 driver), for development and demos. */
 export function sqlite(filename) {
     return createConnection({ client: 'better-sqlite3', connection: { filename }, useNullAsDefault: true });
 }
@@ -17,8 +17,10 @@ export class ObjectionAdapter {
     modify;
     softDeletes;
     findsTrashed;
-    /** `softDeletes` : colonne d'horodatage de suppression (équivalent du trait SoftDeletes). `findsTrashed` : `find()` voit aussi les supprimés
-     *  (équivalent de `getRecordRouteBindingEloquentQuery()->withoutGlobalScopes([SoftDeletingScope::class])`). */
+    /**
+     * `modify`: base query constraints applied to every read. `softDeletes`: deletion timestamp column.
+     * `findsTrashed`: `find()` also returns soft-deleted records.
+     */
     constructor(model, options = {}) {
         this.model = model;
         this.modify = options.modify ?? null;
@@ -27,8 +29,8 @@ export class ObjectionAdapter {
     }
     tenantScope = null;
     /**
-     * Cloisonne l'adaptateur par locataire : toute lecture filtre sur `column`, toute création la renseigne,
-     * avec la clé rendue par `key()` (celle du locataire de la requête ; `null` : pas de filtre). Posé par le panel (`panel.tenant()`).
+     * Scopes the adapter to a tenant: every read filters on `column` and every create fills it, with the key returned by `key()`
+     * (the request's tenant; `null` means no filter). Set by the panel (`panel.tenant()`).
      */
     scopeToTenant(column, key) { this.tenantScope = { column, key }; return this; }
     base(trashed = 'without') {
@@ -56,8 +58,8 @@ export class ObjectionAdapter {
         return rows.map((r) => this.getKey(r));
     }
     /**
-     * Parmi des clés reçues du navigateur, celles qui appartiennent à la portée de l'adaptateur (`modify`, suppression douce comprise).
-     * Une sélection forgée ne peut ainsi pas viser un enregistrement que la table n'affiche pas.
+     * Keeps the browser-supplied keys that fall within the adapter's scope (`modify` and tenant; trashed records included),
+     * so a forged selection cannot target a record the table does not show.
      */
     async keysInScope(keys) {
         if (!keys.length)
@@ -65,7 +67,7 @@ export class ObjectionAdapter {
         const rows = await this.base('with').whereIn(`${this.model.tableName}.${this.keyColumn}`, keys.map(String).slice(0, 10000));
         return rows.map((r) => this.getKey(r));
     }
-    /** Somme de colonnes sur tous les enregistrements de la requête (pour les lignes de totaux). */
+    /** Count and column aggregates over every record of the query (for summary rows). */
     async aggregate(query, columns = {}) {
         const q = this.model.knex().from(this.filtered(query).toKnexQuery().as('t')).count({ __count: '*' });
         for (const column of columns.sum ?? [])
@@ -86,9 +88,8 @@ export class ObjectionAdapter {
         };
     }
     /**
-     * Tendance mensuelle sur la requête filtrée (équivalent de `Trend::query(...)->between()->perMonth()->count()` ou `->average()`
-     * de flowframe/laravel-trend) : une valeur par mois de `start` à `end`, 0 pour un mois sans enregistrement.
-     * SQL de date écrit pour SQLite ; dates en UTC, au format `Y-m-d H:i:s`.
+     * Monthly trend over the filtered query (count, or average of `average`): one value per month from `start` to `end`,
+     * 0 for months without records. The date SQL targets SQLite; dates are UTC, formatted `Y-m-d H:i:s`.
      */
     async trendPerMonth(query, options) {
         const pad = (n) => String(n).padStart(2, '0');
@@ -102,7 +103,7 @@ export class ObjectionAdapter {
         options.modify?.(q);
         const rows = new Map((await q).map((row) => [row.month, Number(row.aggregate ?? 0)]));
         const values = [];
-        // Comme CarbonPeriod par pas d'un mois : même jour du mois que `start`, jusqu'à `end` compris.
+        // One step per calendar month from `start`, up to and including `end`.
         for (let i = 0;; i++) {
             const month = new Date(Date.UTC(options.start.getUTCFullYear(), options.start.getUTCMonth() + i, 1));
             if (month.getTime() > options.end.getTime())
@@ -114,7 +115,7 @@ export class ObjectionAdapter {
     async sum(query, columns) {
         if (!columns.length)
             return {};
-        // La requête filtrée sert de sous-requête : ses colonnes calculées (alias) restent utilisables par la recherche.
+        // The filtered query is used as a subquery so its computed (aliased) columns remain usable by the search.
         const q = this.model.knex().from(this.filtered(query).toKnexQuery().as('t'));
         for (const column of columns)
             q.sum({ [column]: `t.${column}` });
@@ -132,7 +133,7 @@ export class ObjectionAdapter {
     async paginate(query) {
         return this.finishPagination(this.filtered(query), query);
     }
-    /** Requête de base avec recherche globale et recherches par colonne appliquées. */
+    /** Base query with modifiers, global search and per-column searches applied. */
     filtered(query) {
         const q = this.base(query.trashed ?? 'without');
         for (const modifier of query.modifiers ?? [])
@@ -140,7 +141,7 @@ export class ObjectionAdapter {
         const words = (query.search ?? '').trim().split(/\s+/).filter(Boolean);
         const columns = query.searchColumns ?? [];
         if (words.length && columns.length) {
-            // Comme Filament : chaque mot doit correspondre à au moins une colonne, sans tenir compte de la casse.
+            // Each word must match at least one column, case-insensitively; LIKE wildcards in the input are escaped.
             for (const word of words) {
                 q.where((sub) => {
                     for (const column of columns)
@@ -173,7 +174,7 @@ export class ObjectionAdapter {
         return (await this.model.query().insertAndFetch((tenantKey !== null ? { ...data, [this.tenantScope.column]: tenantKey } : data)));
     }
     async update(key, data) {
-        // Un enregistrement hors du locataire courant n'est pas modifiable, et la colonne du locataire ne change pas.
+        // Records outside the current tenant cannot be updated, and the tenant column never changes.
         if (this.tenantScope && this.tenantScope.key() !== null) {
             if (!(await this.base('with').findById(key)))
                 return null;
@@ -181,7 +182,7 @@ export class ObjectionAdapter {
         }
         return (await this.model.query().patchAndFetchById(key, data)) ?? null;
     }
-    /** Avec suppression douce, l'enregistrement est horodaté, pas retiré. */
+    /** With soft deletes, the record is timestamped instead of removed. */
     async delete(key) {
         if (this.softDeletes)
             return (await this.model.query().findById(key).whereNull(this.softDeletes).patch({ [this.softDeletes]: this.now() })) > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navette-js/database",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Data adapters (Objection/Knex) for Navette panels.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,6 @@
   },
   "keywords": [
     "navette",
-    "filament",
     "admin",
     "panel",
     "livewire",