nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/types/IPage.d.ts

@@ -0,0 +1,119 @@
+/**
+ * **LE contrat de pagination unique de Nodefony.** Tous les stores, toutes les API
+ * (présents et futurs) paginent avec ce type — c'est un standard de développement,
+ * jamais une pagination maison au cas par cas.
+ *
+ * Une requête HTTP se traduit en `IPageQuery` par `parsePageQuery(source)` — une
+ * fonction **pure**, agnostique de la provenance (query string aujourd'hui, corps
+ * d'une requête `QUERY` demain). C'est le seul traducteur : un data plane qui
+ * relit `request.query` lui-même refabrique un dialecte.
+ *
+ * Deux modes, **un seul vocabulaire** :
+ * - **offset** (`offset`) — navigation par page directe, pour les backends qui la
+ *   font nativement (SQL `LIMIT/OFFSET`, Mongo `skip/limit`, fichier, mémoire).
+ * - **curseur** (`cursor`) — navigation « après ce jeton », pour les backends sans
+ *   offset fiable (Redis `SCAN`) ou les flux ordonnés (journal d'audit). Un seul des
+ *   deux est utilisé selon ce que le store sait faire ; le store le déclare.
+ *
+ * Les **filtres spécifiques** à un store (rôle, catégorie d'audit, critère ORM…) ne
+ * vivent pas ici : chaque store **étend** ce type (`interface XQuery extends
+ * IPageQuery { … }`), pour que le socle reste un contrat pur et partagé.
+ */
+export interface IPageQuery {
+    /** Taille de page — obligatoire (jamais « tout »). */
+    limit: number;
+    /**
+     * Décalage depuis le début de la collection filtrée (mode **offset**). Défaut `0`.
+     * Mutuellement exclusif avec {@link IPageQuery.cursor} : un backend n'expose qu'un mode.
+     */
+    offset?: number;
+    /**
+     * Jeton de page (mode **curseur**) : ne renvoyer que les éléments situés « après »
+     * lui dans l'ordre du store. Obtenu du {@link IPage.nextCursor} de la page précédente.
+     */
+    cursor?: string;
+    /**
+     * Tri : couples `[champ, sens]`. Format **tableau** (une clé d'objet inconnue serait
+     * silencieusement ignorée). Champs autorisés = définis par le store.
+     */
+    order?: Array<[string, "ASC" | "DESC"]>;
+    /**
+     * Renvoyer le total exact ({@link IPage.total}) ou non. `true` par défaut.
+     * `false` = mode « Slice » : on saute le `COUNT` coûteux, {@link IPage.hasNext} suffit.
+     */
+    withTotal?: boolean;
+    /**
+     * Recherche plein-texte best-effort — le **champ** ciblé et la sémantique (préfixe /
+     * sous-chaîne / casse) sont définis par chaque store et documentés côté store.
+     */
+    q?: string;
+    /**
+     * **RÉSERVÉ multi-tenant** — slot du contrat pour le scoping par tenant, appliqué
+     * **au niveau du store** le jour du chantier tenant.
+     *
+     * @remarks ⚠️ **Non appliqué aujourd'hui** : le passer n'a aucun effet de filtrage.
+     *   Présent dès maintenant pour ne pas re-changer la signature d'un contrat public
+     *   propagé à tous les stores plus tard.
+     */
+    tenantId?: string | null;
+}
+/**
+ * **Une capacité de tri se DÉCLARE** — le socle commun à tout ce qui rend des
+ * pages triables (stores de sessions, de jetons, d'endpoints, dépôts
+ * d'utilisateurs…).
+ *
+ * Cette interface existe pour qu'il n'y ait **qu'une** forme à connaître : le
+ * nom de la propriété, sa nullabilité et sa sémantique sont écrits ici une fois,
+ * au lieu d'être redéclarés — et de diverger — dans chaque contrat de store.
+ *
+ * Le mécanisme, identique pour toutes les ressources :
+ * 1. le store **déclare** ce qu'il sait trier, en vocabulaire public ;
+ * 2. le data plane le **demande** et le passe en allowlist à `parsePageQuery` ;
+ * 3. tout `?order=` hors de cette liste est refusé en **400** — jamais accepté
+ *    puis ignoré en silence.
+ *
+ * D'où la conséquence utile : **le refus est gratuit**. Un backend qui ne sait
+ * pas trier (un `SCAN` Redis n'a aucun ordre global) laisse simplement la
+ * propriété absente, et rien de plus n'est à écrire pour que le tri y soit
+ * refusé. Les capacités PEUVENT donc être inégales d'un backend à l'autre —
+ * elles sont alors annoncées, jamais simulées.
+ *
+ * ⚠️ Là où un backend compose du SQL à la main, cette liste est **aussi une
+ * garde de sécurité** : un nom de colonne ne se lie pas en paramètre, il se
+ * concatène. Voir `pickOrder`, qui l'applique.
+ */
+export interface ISortableSource {
+    /**
+     * Champs triables, en **noms publics** (ceux de l'URL), ou absent si ce
+     * backend ne sait pas trier.
+     */
+    readonly sortableFields?: readonly string[];
+}
+/**
+ * Une **page** de résultats — la sortie unique de toute pagination Nodefony.
+ *
+ * `total` présent = mode **Page** (on a compté) ; absent = mode **Slice**. `hasNext`
+ * est fiable dans les deux cas. `nextCursor` n'est posé que par les backends **curseur**.
+ *
+ * @typeParam T - type des éléments de la page.
+ */
+export interface IPage<T> {
+    /** Les éléments de la page (au plus `limit`). */
+    items: T[];
+    /**
+     * Total exact de la collection filtrée — présent si {@link IPageQuery.withTotal}
+     * n'est pas `false` **et** que le backend sait compter à coût raisonnable.
+     */
+    total?: number;
+    /** Taille de page demandée (écho de {@link IPageQuery.limit}). */
+    limit: number;
+    /** Décalage de cette page (mode offset ; absent en mode curseur). */
+    offset?: number;
+    /** `true` s'il existe au moins un élément au-delà de cette page. */
+    hasNext: boolean;
+    /**
+     * Jeton de la page suivante (mode **curseur**) — à repasser en
+     * {@link IPageQuery.cursor}. `null` = fin. Absent = pagination par offset.
+     */
+    nextCursor?: string | null;
+}

package/dist/client/types/src/types/IService.d.ts

@@ -0,0 +1,62 @@
+import type { IContainer } from "./IContainer.js";
+import type { DynamicParam } from "../Container.js";
+import type Event from "../Event.js";
+import type { EventDefaultInterface } from "../Event.js";
+import type Pdu from "../syslog/Pdu.js";
+import type { Severity, Msgid, Message, Pci } from "../syslog/Pdu.js";
+import type Syslog from "../syslog/Syslog.js";
+import type { SyslogDefaultSettings, conditionsInterface } from "../syslog/Syslog.js";
+import type { IKernel } from "./IKernel.js";
+import type { DebugType, EnvironmentType } from "./globals.js";
+export type EventListener = (...args: any[]) => void;
+export interface DefaultOptionsService extends EventDefaultInterface {
+    events?: {
+        nbListeners: number;
+    };
+    syslog?: SyslogDefaultSettings;
+}
+/**
+ * Contrat public de tout service nodefony.
+ * Kernel, Module, Controller, adapters ORM — tous implémentent IService.
+ */
+export interface IService {
+    readonly name: string;
+    readonly options: DefaultOptionsService;
+    readonly container: IContainer | null;
+    readonly kernel: IKernel | null;
+    readonly syslog: Syslog | null;
+    /** undefined si notificationsCenter=false passé au constructeur, ou après clean() */
+    readonly notificationsCenter: Event | undefined;
+    getName(): string;
+    initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): ReturnType<Syslog["init"]> | null;
+    clean(syslog?: boolean): void;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    logger(pci: Pci, ...args: unknown[]): void;
+    trace(pci: Pci, ...args: unknown[]): void;
+    get<T>(name: string): T | null;
+    set<T>(name: string, obj: T): void;
+    remove(name: string): boolean;
+    has(name: string): boolean;
+    getParameters(name: string): DynamicParam | null;
+    setParameters<T>(name: string, ele: T): DynamicParam | null;
+    on(eventName: string | symbol, listener: EventListener): this;
+    once(eventName: string | symbol, listener: EventListener): this;
+    off(eventName: string | symbol, listener: EventListener): this;
+    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+    fire(eventName: string | symbol, ...args: unknown[]): boolean;
+    emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    addListener(eventName: string | symbol, listener: EventListener): this;
+    removeListener(eventName: string | symbol, listener: EventListener): this;
+    removeAllListeners(eventName?: string | symbol): this;
+    prependListener(eventName: string | symbol, listener: EventListener): this;
+    prependOnceListener(eventName: string | symbol, listener: EventListener): this;
+    listen(eventName: string | symbol, listener: EventListener): (...args: unknown[]) => boolean;
+    settingsToListen(localSettings: EventDefaultInterface, context: object): void;
+    eventNames(): (string | symbol)[];
+    listenerCount(eventName: string | symbol, listener?: EventListener): number;
+    listeners(eventName: string | symbol): EventListener[];
+    rawListeners(eventName: string | symbol): EventListener[];
+    getMaxListeners(): number;
+    setMaxListeners(n: number): this;
+}

package/dist/client/types/src/types/ISyslog.d.ts

@@ -0,0 +1,58 @@
+import type Pdu from "../syslog/Pdu.js";
+import type { Severity, Msgid, Message, Pci } from "../syslog/Pdu.js";
+import type { DebugType, EnvironmentType } from "./globals.js";
+import type { ITransport } from "./ITransport.js";
+import type { SyslogDefaultSettings, conditionsInterface, CallbackFunction, WrapperResult } from "../syslog/Syslog.js";
+export interface ISyslog {
+    settings: SyslogDefaultSettings;
+    readonly ringStack: Pdu[];
+    /** Capacité MAX du ring buffer (plafond `maxStack`). */
+    readonly bufferCapacity: number;
+    /** `true` si les Pdu sont stockés dans le ring (relecture mémoire active). */
+    readonly ringEnabled: boolean;
+    /** Active/désactive le stockage mémoire (ring) à chaud — outil avancé. */
+    setRingEnabled(enabled: boolean): boolean;
+    /** `true` si la diffusion temps réel (`nodefony:syslog`) est active. */
+    readonly streamEnabled: boolean;
+    /** Active/désactive la diffusion temps réel à chaud (onglet Live). */
+    setStreamEnabled(enabled: boolean): boolean;
+    burstPrinted: number;
+    missed: number;
+    invalid: number;
+    valid: number;
+    /** Cumul monotone des logs de sévérité 0–3 (ERROR/CRITIC/ALERT/EMERGENCY). */
+    errorTotal: number;
+    /** Sous-ensemble CRITIQUE (sévérité 0–2 : CRITIC/ALERT/EMERGENCY). */
+    criticTotal: number;
+    start: number;
+    async: boolean;
+    init(environment: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void;
+    clean(): this;
+    reset(): this;
+    clearLogStack(): void;
+    log(payload: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    error(data: Pci): Pdu;
+    warn(data: Pci): Pdu;
+    info(data: Pci): Pdu;
+    debug(data: Pci): Pdu;
+    trace(data: Pci, ...args: unknown[]): Pdu;
+    print(...args: Pci[]): Pdu;
+    logMultiple(severity: Severity, ...args: Pci[]): Pdu;
+    pushStack(pdu: Pdu): number;
+    getLogStack(start?: number, end?: number, condition?: conditionsInterface): Pdu[] | Pdu;
+    getLogs(conditions: conditionsInterface, stack?: Pdu[] | null): Pdu[];
+    logToJson(conditions: conditionsInterface, stack?: Pdu[] | null): string;
+    loadStack(stack: Pdu[] | string, doEvent?: boolean, beforeConditions?: ((pdu: Pdu, stackItem: Pdu) => void) | null): Pdu[];
+    filter(conditions: conditionsInterface, callback: CallbackFunction): void;
+    listenWithConditions(conditions: conditionsInterface, callback: CallbackFunction): void;
+    addTransport(transport: ITransport): this;
+    removeTransport(transport: ITransport): this;
+    /** Liste polymorphe des transports d'écriture (axe WRITE) + état `enabled`. */
+    listTransports(): {
+        name: string;
+        enabled: boolean;
+    }[];
+    /** Active/désactive un transport d'écriture à chaud, par nom (dev/diagnostic). */
+    setTransportEnabled(name: string, enabled: boolean): boolean;
+}
+export type { WrapperResult };

package/dist/client/types/src/types/ITransport.d.ts

@@ -0,0 +1,5 @@
+import type Pdu from "../syslog/Pdu.js";
+export interface ITransport {
+    readonly name: string;
+    send(pdu: Pdu): Promise<void>;
+}

package/dist/client/types/src/types/globals.d.ts

@@ -0,0 +1,47 @@
+export interface nodefonyOptions {
+    [key: string]: any;
+}
+declare global {
+    interface Error {
+        /**
+         * Sérialisation JSON d'une erreur — POSÉE AU RUNTIME par `Error.ts` sur
+         * `Error.prototype`, donc présente sur toute erreur qui traverse Nodefony.
+         *
+         * Déclarée **optionnelle**, et c'est délibéré : la rendre obligatoire
+         * augmente le type standard `Error` de tout le graphe, et rend alors
+         * **incompilable toute classe tierce qui écrit `implements Error`** — elle
+         * n'a aucune raison de connaître une méthode de Nodefony. Constaté sur
+         * `HttpErrorResponse` d'`@angular/common` (TS2420), qui suffisait à rendre
+         * `@angular/*` inutilisable dans un graphe de types Nodefony. Le seul
+         * appelant du dépôt passe déjà par `nodefonyError`, qui la déclare en
+         * propre : l'obligation ne servait personne et coûtait l'interopérabilité.
+         */
+        toJSON?(): Record<string, any>;
+    }
+}
+/**
+ * Modes MOTEUR du kernel — l'axe qui pilote l'optimisation du runtime.
+ *
+ * `staging` n'en fait pas partie : un staging tourne « comme la production »
+ * (mêmes optimisations) et se distingue par son axe de DÉPLOIEMENT, pas par son
+ * moteur. Cet axe-là est `APP_ENV`/`NF_ENV` (string libre : `staging`,
+ * `canary`, `prod-eu`…), lu par `loadEnv` (→ `.env.staging`) et exposé par
+ * `ConfigContext.appEnv` — il reste entier.
+ *
+ * `test` n'en fait pas partie non plus : c'est une valeur de `NODE_ENV` que le
+ * kernel normalise en `runtimeEnv` (→ `ConfigContext.isTest`), jamais un mode moteur.
+ */
+declare enum environment {
+    dev,
+    development,
+    prod,
+    production
+}
+export type EnvironmentType = keyof typeof environment;
+export type DebugType = boolean | string | string[];
+type JSONArray = Array<JSONValue>;
+type JSONValue = string | number | boolean | JSONObject | JSONArray;
+export interface JSONObject {
+    [x: string]: JSONValue;
+}
+export {};