@venizia/ignis-kernel 0.4.3 → 0.4.5

package/dist/cjs/base/controllers/rest/base.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../../src/base/controllers/rest/base.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Hook, OpenAPIHono } from '@hono/zod-openapi';\nimport { buildDataRange } from '@/base/repositories/common/types';\nimport type { TDataRange } from '@/base/repositories/common/types';\nimport type { AnyType, TNullable, ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { HTTP } from '@venizia/ignis-helpers/common';\nimport { executeWithPerformanceMeasure, toBoolean } from '@venizia/ignis-helpers/core';\nimport type { Env, Schema } from 'hono';\nimport { ResponseFormats } from '../common/constants';\nimport type { TResponseFormat } from '../common/constants';\nimport type {\n  IAuthRouteConfig,\n  IBindRouteOptions,\n  IDefineRouteOptions,\n  TRouteContext,\n  TRouteHandler,\n} from '../common/types';\nimport { AbstractRestController } from './abstract';\nimport type { IRequestedExtra, TResponseExtra } from './extras';\nimport { ResponseExtras } from './extras';\n\n/** `Content-Range` of a page: inclusive `end`, and `records * /<total>` (no space) when the page is empty. Exported so a route that writes the header itself uses the one formatter. */\nexport const toContentRange = (opts: { range: TDataRange; count: number }): string => {\n  const { range, count } = opts;\n  const { start, end, total } = range;\n  return count > 0 ? `records ${start}-${end}/${total}` : `records */${total}`;\n};\n\n/** Recommended base class for REST controllers with concrete bindRoute and defineRoute implementations. */\nexport abstract class BaseRestController<\n  RouteEnv extends Env = Env,\n  RouteSchema extends Schema = {},\n  BasePath extends string = '/',\n  ConfigurableOptions extends object = {},\n  Definitions extends Record<string, IAuthRouteConfig> = Record<string, IAuthRouteConfig>,\n> extends AbstractRestController<\n  RouteEnv,\n  RouteSchema,\n  BasePath,\n  ConfigurableOptions,\n  Definitions\n> {\n  /** Runs a handler task under performance measurement (fixed logger/level/description). */\n  measure<R>(opts: { scope: string; args: unknown; task: () => Promise<R> }) {\n    return executeWithPerformanceMeasure({\n      logger: this.logger,\n      level: 'debug',\n      scope: opts.scope,\n      description: `execute ${opts.scope}`,\n      args: opts.args,\n      task: opts.task,\n    });\n  }\n\n  /** Returns the full `{ count, data }` envelope, or just `data` when the client sent `x-request-count: false`; `X-Response-Count` is set either way. */\n  normalizeCountData<\n    ResponseSchema extends AnyType,\n    RequestContext extends TRouteContext<RouteEnv> = TRouteContext<RouteEnv>,\n    ResponseData extends {\n      count: number;\n      data?: TNullable<ResponseSchema>;\n    } = { count: number; data?: TNullable<ResponseSchema> },\n  >(opts: { context: RequestContext; payload: ResponseData }) {\n    const { context, payload } = opts;\n    const requestCountData = context.req.header(HTTP.Headers.REQUEST_COUNT_DATA) ?? 'true';\n    const useCountData = toBoolean(requestCountData);\n\n    context.header(HTTP.Headers.RESPONSE_COUNT_DATA, payload.count.toString());\n\n    if (useCountData) {\n      return payload;\n    }\n\n    return payload.data;\n  }\n\n  /** `x-request-extra`, parsed: `name`, `-name` (a default switched off) and `name(key,key)`. */\n  getRequestedExtras(opts: { context: TRouteContext<RouteEnv> }): Array<IRequestedExtra> {\n    return ResponseExtras.parse({ header: opts.context.req.header(HTTP.Headers.REQUEST_EXTRA) });\n  }\n\n  /**\n   * The one response call. Sets `X-Response-Format`, and with `range` (a list) also `Content-Range` -\n   * `payload.count` is the rows of THIS response, never the total - then normalizes count/data per\n   * the request-count header.\n   *\n   * `extra` offers figures beside the rows (see {@link TResponseExtra}): each runs when the client\n   * names it in `x-request-extra`, or always when it is a default. When any runs, the body is\n   * `{ data, extra }` (with `count` when it is requested); when none does, nothing is computed and the\n   * body is what it would be without `extra`. A name the route does not offer is a 400 listing the\n   * ones it does.\n   */\n  respond<R>(opts: {\n    context: TRouteContext<RouteEnv>;\n    format: TResponseFormat;\n    payload: { count: number; data?: TNullable<R> };\n    range?: TDataRange;\n    extra?: never;\n  }): R | { count: number; data?: TNullable<R> } | null | undefined;\n  respond<R, Extra extends Record<string, TResponseExtra>>(opts: {\n    context: TRouteContext<RouteEnv>;\n    format: TResponseFormat;\n    payload: { count: number; data?: TNullable<R> };\n    range?: TDataRange;\n    extra: Extra;\n  }): Promise<\n    | R\n    | { count: number; data?: TNullable<R> }\n    | {\n        count?: number;\n        data?: TNullable<R>;\n        extra: Partial<Record<keyof Extra, unknown>>;\n      }\n    | null\n    | undefined\n  >;\n  respond<R>(opts: {\n    context: TRouteContext<RouteEnv>;\n    format: TResponseFormat;\n    payload: { count: number; data?: TNullable<R> };\n    range?: TDataRange;\n    extra?: Record<string, TResponseExtra>;\n  }): ValueOrPromise<\n    R | { count?: number; data?: TNullable<R>; extra?: Record<string, unknown> } | null | undefined\n  >;\n  respond<R>(opts: {\n    context: TRouteContext<RouteEnv>;\n    format: TResponseFormat;\n    payload: { count: number; data?: TNullable<R> };\n    range?: TDataRange;\n    extra?: Record<string, TResponseExtra>;\n  }) {\n    const { context, format, payload, range, extra } = opts;\n\n    if (range) {\n      context.header(HTTP.Headers.CONTENT_RANGE, toContentRange({ range, count: payload.count }));\n    }\n    context.header(HTTP.Headers.RESPONSE_FORMAT, format);\n\n    if (!extra) {\n      return this.normalizeCountData<R>({ context, payload });\n    }\n\n    return this.respondWithExtra<R>({ context, payload, extra });\n  }\n\n  /** The `extra` half of `respond`: resolves what was asked against what is offered, runs it in parallel. */\n  async respondWithExtra<R>(opts: {\n    context: TRouteContext<RouteEnv>;\n    payload: { count: number; data?: TNullable<R> };\n    extra: Record<string, TResponseExtra>;\n  }) {\n    const { context, payload, extra } = opts;\n    const plan = ResponseExtras.resolve({\n      requested: this.getRequestedExtras({ context }),\n      offered: extra,\n    });\n\n    if (plan.size === 0) {\n      return this.normalizeCountData<R>({ context, payload });\n    }\n\n    const computed = await ResponseExtras.compute({ plan, offered: extra });\n\n    // Rows still counted in the header; the body is an object, since an array cannot carry extras.\n    // `x-response-extra` marks it, so a client unwraps `{ data, extra }` only when the server says so.\n    context.header(HTTP.Headers.RESPONSE_COUNT_DATA, payload.count.toString());\n    context.header(HTTP.Headers.RESPONSE_EXTRA, Object.keys(computed).join(','));\n    const useCountData = toBoolean(context.req.header(HTTP.Headers.REQUEST_COUNT_DATA) ?? 'true');\n\n    return useCountData\n      ? { count: payload.count, data: payload.data, extra: computed }\n      : { data: payload.data, extra: computed };\n  }\n\n  /** The list headers without the body, for a list whose body is not a `{ count, data }` envelope: `Content-Range`, `X-Response-Count` = rows in THIS response, `X-Response-Format: array`. Pass a `range`, or `offset` + `total` for an engine that reports those (a search page): the range is derived with the same inclusive-end rule. */\n  setListHeaders(\n    opts: { context: TRouteContext<RouteEnv>; count: number } & (\n      | { range: TDataRange }\n      | { offset: number; total: number }\n    ),\n  ) {\n    const { context, count } = opts;\n    const range =\n      'range' in opts\n        ? opts.range\n        : buildDataRange({ offset: opts.offset, dataLength: count, total: opts.total });\n\n    context.header(HTTP.Headers.CONTENT_RANGE, toContentRange({ range, count }));\n    context.header(HTTP.Headers.RESPONSE_COUNT_DATA, count.toString());\n    context.header(HTTP.Headers.RESPONSE_FORMAT, ResponseFormats.ARRAY);\n  }\n\n  /** TRouteHandler's TRouteContext is a lightweight custom shape (different `json`/`req.valid` signatures) built on Hono's real Context, not a subtype of the RouteHandler `.openapi()` expects - genuinely different handler types bridged here. */\n  toHonoHandler<ResponseType = unknown>(opts: { handler: TRouteHandler<ResponseType, RouteEnv> }) {\n    return opts.handler as Parameters<OpenAPIHono<RouteEnv>['openapi']>[1];\n  }\n\n  /** Creates a fluent binding for registering a route (call .to() to attach handler). */\n  bindRoute<RouteConfig extends IAuthRouteConfig>(opts: {\n    configs: RouteConfig;\n  }): IBindRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath> {\n    const routeConfigs = this.getRouteConfigs<RouteConfig>({ configs: opts.configs });\n\n    return {\n      configs: routeConfigs,\n      to: ({ handler }) => {\n        return {\n          configs: routeConfigs,\n          route: this.router.openapi(routeConfigs, this.toHonoHandler({ handler })),\n        };\n      },\n    };\n  }\n\n  /** Defines and registers a route with its handler in a single call. */\n  defineRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opts: {\n    configs: RouteConfig;\n    handler: TRouteHandler<ResponseType, RouteEnv>;\n    hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;\n  }): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath> {\n    const routeConfigs = this.getRouteConfigs<RouteConfig>({ configs: opts.configs });\n\n    return {\n      configs: routeConfigs,\n      route: this.router.openapi(\n        routeConfigs,\n        this.toHonoHandler<ResponseType>({ handler: opts.handler }),\n        opts.hook,\n      ),\n    };\n  }\n\n  /** Defines a JSX route that renders server-side HTML via c.html(). */\n  defineJSXRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opts: {\n    configs: RouteConfig;\n    handler: TRouteHandler<ResponseType, RouteEnv>;\n    hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;\n  }): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath> {\n    const routeConfigs = this.getJSXRouteConfigs<RouteConfig>({ configs: opts.configs });\n\n    return {\n      configs: routeConfigs,\n      route: this.router.openapi(\n        routeConfigs,\n        this.toHonoHandler<ResponseType>({ handler: opts.handler }),\n        opts.hook,\n      ),\n    };\n  }\n}\n"]}

package/dist/cjs/base/controllers/rest/extras.d.ts

@@ -1,49 +0,0 @@
-import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
-/**
- * A figure a list route offers beside its rows:
- * - a function runs when the client names it;
- * - `{ isDefault: true, compute }` always runs, unless the client switches it off with `-name`;
- * - `{ keys, compute }` is a group - the client names the keys it wants (`facets(status,tag)`), and
- *   `compute` receives exactly those, so one aggregate pass serves them all.
- */
-export type TResponseExtra = (() => ValueOrPromise<unknown>) | {
-    isDefault: boolean;
-    compute: () => ValueOrPromise<unknown>;
-    keys?: never;
-} | {
-    keys: ReadonlyArray<string>;
-    compute: (opts: {
-        keys: Array<string>;
-    }) => ValueOrPromise<unknown>;
-    isDefault?: never;
-};
-/** One entry of `x-request-extra`: `name`, `-name` (a default switched off), `-*` (every default off) or `name(key,key)`. */
-export interface IRequestedExtra {
-    name: string;
-    isExcluded: boolean;
-    keys?: Array<string>;
-}
-/** Parses `x-request-extra` and resolves it against what a route offers. */
-export declare class ResponseExtras {
-    /** The entries of the header, in the order written. Malformed input is a 400 naming it. */
-    static parse(opts: {
-        header?: string | null;
-    }): Array<IRequestedExtra>;
-    /**
-     * What to compute: the asked-for extras and the defaults, minus the ones switched off - each with the
-     * keys asked for, de-duplicated in the order asked. Every name and key is checked against `offered`.
-     */
-    static resolve(opts: {
-        requested: Array<IRequestedExtra>;
-        offered: Record<string, TResponseExtra>;
-    }): Map<string, Array<string> | undefined>;
-    /** Runs the plan in parallel; each value under its name. */
-    static compute(opts: {
-        plan: Map<string, Array<string> | undefined>;
-        offered: Record<string, TResponseExtra>;
-    }): Promise<Record<string, unknown>>;
-    /** Commas inside `( )` belong to the keys, not to the list of extras. */
-    private static splitTopLevel;
-    private static badRequest;
-}
-//# sourceMappingURL=extras.d.ts.map

package/dist/cjs/base/controllers/rest/extras.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extras.d.ts","sourceRoot":"","sources":["../../../../../src/base/controllers/rest/extras.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAIpE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB,CAAC,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC,GAC/B;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC5E;IACE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,KAAK,cAAc,CAAC,OAAO,CAAC,CAAC;IACpE,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB,CAAC;AAEN,6HAA6H;AAC7H,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AASD,4EAA4E;AAC5E,qBAAa,cAAc;IACzB,2FAA2F;IAC3F,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,KAAK,CAAC,eAAe,CAAC;IAmCtE;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;QACnB,SAAS,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;QAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;KACzC,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IA6E1C,4DAA4D;WAC/C,OAAO,CAAC,IAAI,EAAE;QACzB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;KACzC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAyBpC,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,aAAa;IAyB5B,OAAO,CAAC,MAAM,CAAC,UAAU;CAM1B"}

package/dist/cjs/base/controllers/rest/extras.js

@@ -1,153 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResponseExtras = void 0;
-const common_1 = require("@venizia/ignis-helpers/common");
-const core_1 = require("@venizia/ignis-helpers/core");
-/** A name or a key: letters, digits, `_`, `.` and `-` inside. Anything else is refused, never evaluated. */
-const IDENTIFIER = /^[A-Za-z_][\w.-]*$/;
-const ENTRY = /^(-?)([^()\s]+)(?:\(([^()]*)\))?$/;
-/** `-*`: every default off - for a read that wants the rows alone. */
-const ALL_DEFAULTS = '*';
-/** Parses `x-request-extra` and resolves it against what a route offers. */
-class ResponseExtras {
-    /** The entries of the header, in the order written. Malformed input is a 400 naming it. */
-    static parse(opts) {
-        const header = opts.header?.trim() ?? '';
-        if (header === '') {
-            return [];
-        }
-        const entries = [];
-        for (const raw of ResponseExtras.splitTopLevel({ header })) {
-            const match = raw.trim().match(ENTRY);
-            const name = match?.[2];
-            const isAllDefaultsOff = match?.[1] === '-' && name === ALL_DEFAULTS && match[3] === undefined;
-            if (!match || !name || (!isAllDefaultsOff && !IDENTIFIER.test(name))) {
-                throw ResponseExtras.badRequest({ message: `Malformed extra '${raw.trim()}'` });
-            }
-            const keys = match[3] === undefined
-                ? undefined
-                : match[3]
-                    .split(',')
-                    .map((key) => key.trim())
-                    .filter((key) => key.length > 0);
-            if (keys?.some((key) => !IDENTIFIER.test(key))) {
-                throw ResponseExtras.badRequest({ message: `Malformed key in extra '${raw.trim()}'` });
-            }
-            entries.push({ name, isExcluded: match[1] === '-', keys });
-        }
-        return entries;
-    }
-    /**
-     * What to compute: the asked-for extras and the defaults, minus the ones switched off - each with the
-     * keys asked for, de-duplicated in the order asked. Every name and key is checked against `offered`.
-     */
-    static resolve(opts) {
-        const { requested, offered } = opts;
-        const offeredNames = Object.keys(offered).join(', ') || 'none';
-        const plan = new Map();
-        const excluded = new Set();
-        let isEveryDefaultOff = false;
-        for (const entry of requested) {
-            if (entry.isExcluded && entry.name === ALL_DEFAULTS) {
-                isEveryDefaultOff = true;
-                continue;
-            }
-            if (!Object.hasOwn(offered, entry.name)) {
-                throw ResponseExtras.badRequest({
-                    message: `Unknown extra requested: ${entry.name} | This route offers: ${offeredNames}`,
-                });
-            }
-            if (entry.isExcluded) {
-                if (entry.keys !== undefined) {
-                    throw ResponseExtras.badRequest({
-                        message: `Switching '${entry.name}' off takes no keys`,
-                    });
-                }
-                excluded.add(entry.name);
-                continue;
-            }
-            const definition = offered[entry.name];
-            const isGroup = typeof definition !== 'function' && definition.keys !== undefined;
-            if (!isGroup) {
-                if (entry.keys !== undefined) {
-                    throw ResponseExtras.badRequest({ message: `Extra '${entry.name}' takes no keys` });
-                }
-                plan.set(entry.name, undefined);
-                continue;
-            }
-            if (!entry.keys?.length) {
-                throw ResponseExtras.badRequest({
-                    message: `Extra '${entry.name}' needs keys: ${definition.keys.join(', ')} | Name them as ${entry.name}(key,key)`,
-                });
-            }
-            const unknown = entry.keys.filter((key) => !definition.keys.includes(key));
-            if (unknown.length > 0) {
-                throw ResponseExtras.badRequest({
-                    message: `Unknown key for extra '${entry.name}': ${unknown.join(', ')} | It offers: ${definition.keys.join(', ')}`,
-                });
-            }
-            plan.set(entry.name, [...new Set([...(plan.get(entry.name) ?? []), ...entry.keys])]);
-        }
-        for (const [name, definition] of Object.entries(offered)) {
-            // A group needs keys, so it never runs unasked, whatever its declaration claims.
-            const isDefault = typeof definition !== 'function' &&
-                definition.keys === undefined &&
-                definition.isDefault === true;
-            if (isDefault && !isEveryDefaultOff && !plan.has(name)) {
-                plan.set(name, undefined);
-            }
-        }
-        for (const name of excluded) {
-            plan.delete(name);
-        }
-        return plan;
-    }
-    /** Runs the plan in parallel; each value under its name. */
-    static async compute(opts) {
-        const { plan, offered } = opts;
-        const names = [...plan.keys()];
-        // Async, so an extra that throws synchronously becomes a rejection Promise.all owns, never an
-        // unhandled one left behind by a sibling already running.
-        const values = await Promise.all(names.map(async (name) => {
-            const definition = offered[name];
-            if (typeof definition === 'function') {
-                return definition();
-            }
-            if (definition.keys !== undefined) {
-                return definition.compute({ keys: plan.get(name) ?? [] });
-            }
-            return definition.compute();
-        }));
-        return Object.fromEntries(names.map((name, index) => [name, values[index]]));
-    }
-    /** Commas inside `( )` belong to the keys, not to the list of extras. */
-    static splitTopLevel(opts) {
-        const parts = [];
-        let depth = 0;
-        let current = '';
-        for (const character of opts.header) {
-            if (character === '(') {
-                depth++;
-            }
-            else if (character === ')') {
-                depth--;
-            }
-            if (character === ',' && depth === 0) {
-                parts.push(current);
-                current = '';
-                continue;
-            }
-            current += character;
-        }
-        parts.push(current);
-        return parts.filter((part) => part.trim().length > 0);
-    }
-    static badRequest(opts) {
-        return (0, core_1.getError)({
-            statusCode: common_1.HTTP.ResultCodes.RS_4.BadRequest,
-            message: `[x-request-extra] ${opts.message}`,
-        });
-    }
-}
-exports.ResponseExtras = ResponseExtras;
-//# sourceMappingURL=extras.js.map

package/dist/cjs/base/controllers/rest/extras.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"extras.js","sourceRoot":"","sources":["../../../../../src/base/controllers/rest/extras.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { HTTP } from '@venizia/ignis-helpers/common';\nimport { getError } from '@venizia/ignis-helpers/core';\n\n/**\n * A figure a list route offers beside its rows:\n * - a function runs when the client names it;\n * - `{ isDefault: true, compute }` always runs, unless the client switches it off with `-name`;\n * - `{ keys, compute }` is a group - the client names the keys it wants (`facets(status,tag)`), and\n *   `compute` receives exactly those, so one aggregate pass serves them all.\n */\nexport type TResponseExtra =\n  | (() => ValueOrPromise<unknown>)\n  | { isDefault: boolean; compute: () => ValueOrPromise<unknown>; keys?: never }\n  | {\n      keys: ReadonlyArray<string>;\n      compute: (opts: { keys: Array<string> }) => ValueOrPromise<unknown>;\n      isDefault?: never;\n    };\n\n/** One entry of `x-request-extra`: `name`, `-name` (a default switched off), `-*` (every default off) or `name(key,key)`. */\nexport interface IRequestedExtra {\n  name: string;\n  isExcluded: boolean;\n  keys?: Array<string>;\n}\n\n/** A name or a key: letters, digits, `_`, `.` and `-` inside. Anything else is refused, never evaluated. */\nconst IDENTIFIER = /^[A-Za-z_][\\w.-]*$/;\nconst ENTRY = /^(-?)([^()\\s]+)(?:\\(([^()]*)\\))?$/;\n\n/** `-*`: every default off - for a read that wants the rows alone. */\nconst ALL_DEFAULTS = '*';\n\n/** Parses `x-request-extra` and resolves it against what a route offers. */\nexport class ResponseExtras {\n  /** The entries of the header, in the order written. Malformed input is a 400 naming it. */\n  static parse(opts: { header?: string | null }): Array<IRequestedExtra> {\n    const header = opts.header?.trim() ?? '';\n    if (header === '') {\n      return [];\n    }\n\n    const entries: Array<IRequestedExtra> = [];\n    for (const raw of ResponseExtras.splitTopLevel({ header })) {\n      const match = raw.trim().match(ENTRY);\n      const name = match?.[2];\n\n      const isAllDefaultsOff =\n        match?.[1] === '-' && name === ALL_DEFAULTS && match[3] === undefined;\n      if (!match || !name || (!isAllDefaultsOff && !IDENTIFIER.test(name))) {\n        throw ResponseExtras.badRequest({ message: `Malformed extra '${raw.trim()}'` });\n      }\n\n      const keys =\n        match[3] === undefined\n          ? undefined\n          : match[3]\n              .split(',')\n              .map((key) => key.trim())\n              .filter((key) => key.length > 0);\n\n      if (keys?.some((key) => !IDENTIFIER.test(key))) {\n        throw ResponseExtras.badRequest({ message: `Malformed key in extra '${raw.trim()}'` });\n      }\n\n      entries.push({ name, isExcluded: match[1] === '-', keys });\n    }\n\n    return entries;\n  }\n\n  /**\n   * What to compute: the asked-for extras and the defaults, minus the ones switched off - each with the\n   * keys asked for, de-duplicated in the order asked. Every name and key is checked against `offered`.\n   */\n  static resolve(opts: {\n    requested: Array<IRequestedExtra>;\n    offered: Record<string, TResponseExtra>;\n  }): Map<string, Array<string> | undefined> {\n    const { requested, offered } = opts;\n    const offeredNames = Object.keys(offered).join(', ') || 'none';\n    const plan = new Map<string, Array<string> | undefined>();\n    const excluded = new Set<string>();\n\n    let isEveryDefaultOff = false;\n\n    for (const entry of requested) {\n      if (entry.isExcluded && entry.name === ALL_DEFAULTS) {\n        isEveryDefaultOff = true;\n        continue;\n      }\n\n      if (!Object.hasOwn(offered, entry.name)) {\n        throw ResponseExtras.badRequest({\n          message: `Unknown extra requested: ${entry.name} | This route offers: ${offeredNames}`,\n        });\n      }\n\n      if (entry.isExcluded) {\n        if (entry.keys !== undefined) {\n          throw ResponseExtras.badRequest({\n            message: `Switching '${entry.name}' off takes no keys`,\n          });\n        }\n\n        excluded.add(entry.name);\n        continue;\n      }\n\n      const definition = offered[entry.name];\n      const isGroup = typeof definition !== 'function' && definition.keys !== undefined;\n\n      if (!isGroup) {\n        if (entry.keys !== undefined) {\n          throw ResponseExtras.badRequest({ message: `Extra '${entry.name}' takes no keys` });\n        }\n\n        plan.set(entry.name, undefined);\n        continue;\n      }\n\n      if (!entry.keys?.length) {\n        throw ResponseExtras.badRequest({\n          message: `Extra '${entry.name}' needs keys: ${definition.keys.join(', ')} | Name them as ${entry.name}(key,key)`,\n        });\n      }\n\n      const unknown = entry.keys.filter((key) => !definition.keys.includes(key));\n      if (unknown.length > 0) {\n        throw ResponseExtras.badRequest({\n          message: `Unknown key for extra '${entry.name}': ${unknown.join(', ')} | It offers: ${definition.keys.join(', ')}`,\n        });\n      }\n\n      plan.set(entry.name, [...new Set([...(plan.get(entry.name) ?? []), ...entry.keys])]);\n    }\n\n    for (const [name, definition] of Object.entries(offered)) {\n      // A group needs keys, so it never runs unasked, whatever its declaration claims.\n      const isDefault =\n        typeof definition !== 'function' &&\n        definition.keys === undefined &&\n        definition.isDefault === true;\n      if (isDefault && !isEveryDefaultOff && !plan.has(name)) {\n        plan.set(name, undefined);\n      }\n    }\n\n    for (const name of excluded) {\n      plan.delete(name);\n    }\n\n    return plan;\n  }\n\n  /** Runs the plan in parallel; each value under its name. */\n  static async compute(opts: {\n    plan: Map<string, Array<string> | undefined>;\n    offered: Record<string, TResponseExtra>;\n  }): Promise<Record<string, unknown>> {\n    const { plan, offered } = opts;\n    const names = [...plan.keys()];\n\n    // Async, so an extra that throws synchronously becomes a rejection Promise.all owns, never an\n    // unhandled one left behind by a sibling already running.\n    const values = await Promise.all(\n      names.map(async (name) => {\n        const definition = offered[name];\n\n        if (typeof definition === 'function') {\n          return definition();\n        }\n\n        if (definition.keys !== undefined) {\n          return definition.compute({ keys: plan.get(name) ?? [] });\n        }\n\n        return definition.compute();\n      }),\n    );\n\n    return Object.fromEntries(names.map((name, index) => [name, values[index]]));\n  }\n\n  /** Commas inside `( )` belong to the keys, not to the list of extras. */\n  private static splitTopLevel(opts: { header: string }): Array<string> {\n    const parts: Array<string> = [];\n    let depth = 0;\n    let current = '';\n\n    for (const character of opts.header) {\n      if (character === '(') {\n        depth++;\n      } else if (character === ')') {\n        depth--;\n      }\n\n      if (character === ',' && depth === 0) {\n        parts.push(current);\n        current = '';\n        continue;\n      }\n\n      current += character;\n    }\n\n    parts.push(current);\n    return parts.filter((part) => part.trim().length > 0);\n  }\n\n  private static badRequest(opts: { message: string }) {\n    return getError({\n      statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n      message: `[x-request-extra] ${opts.message}`,\n    });\n  }\n}\n"]}

package/dist/cjs/base/controllers/rest/index.d.ts

@@ -1,4 +0,0 @@
-export * from './abstract';
-export * from './base';
-export * from './extras';
-//# sourceMappingURL=index.d.ts.map

package/dist/cjs/base/controllers/rest/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/base/controllers/rest/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/dist/cjs/base/controllers/rest/index.js

@@ -1,20 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./abstract"), exports);
-__exportStar(require("./base"), exports);
-__exportStar(require("./extras"), exports);
-//# sourceMappingURL=index.js.map

package/dist/cjs/base/controllers/rest/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/base/controllers/rest/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB","sourcesContent":["export * from './abstract';\nexport * from './base';\nexport * from './extras';\n"]}

package/dist/cjs/base/datasources/abstract.d.ts

@@ -1,41 +0,0 @@
-import type { AnyType, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
-import { BaseHelper } from '@venizia/ignis-helpers/core';
-import type { IDataSource, IDataSourceCapabilities, ITransaction, ITransactionOptions, TAnyDataSourceSchema } from './common';
-/**
- * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.
- *
- * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is
- * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is
- * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every
- * subclass however deep.
- */
-export declare const DATA_SOURCE_BRAND: unique symbol;
-/** True for `AbstractDataSource` itself and for any class extending it, across package copies. */
-export declare const isDataSourceClass: (value: unknown) => value is TClass<AnyType>;
-/** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */
-export declare abstract class AbstractDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}> extends BaseHelper implements IDataSource<Settings, Schema, ConfigurableOptions> {
-    /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */
-    static readonly [DATA_SOURCE_BRAND] = true;
-    name: string;
-    settings: Settings;
-    schema: Schema;
-    abstract configure(opts?: ConfigurableOptions): ValueOrPromise<void>;
-    getSettings(): Settings;
-    getSchema(): Schema;
-    /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */
-    getCapabilities(): IDataSourceCapabilities;
-    /** Nothing to release at this root; a family that holds a connection overrides it. */
-    close(): Promise<void>;
-    /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */
-    beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction>;
-    /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */
-    protected getBoundModelClasses(): Array<TClass<unknown>>;
-    /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */
-    protected discoverDefinitions<TDefinition extends {
-        name: string;
-    }>(opts: {
-        read: (modelClass: TClass<unknown>) => TDefinition | undefined;
-        kind: string;
-    }): Record<string, TDefinition>;
-}
-//# sourceMappingURL=abstract.d.ts.map

package/dist/cjs/base/datasources/abstract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract.d.ts","sourceRoot":"","sources":["../../../../src/base/datasources/abstract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACrF,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,eAA2D,CAAC;AAE1F,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,OAAO,CAEzE,CAAC;AAEF,4FAA4F;AAC5F,8BAAsB,kBAAkB,CACtC,QAAQ,SAAS,MAAM,GAAG,EAAE,EAC5B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,mBAAmB,SAAS,MAAM,GAAG,EAAE,CAEvC,SAAQ,UACR,YAAW,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAAC;IAE7D,gFAAgF;IAChF,MAAM,CAAC,QAAQ,CAAC,CAAC,iBAAiB,CAAC,QAAQ;IAE3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAAC,IAAI,CAAC;IAEpE,WAAW;IAIX,SAAS,IAAI,MAAM;IASnB,mHAAmH;IACnH,eAAe,IAAI,uBAAuB;IAI1C,sFAAsF;IACtF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,8LAA8L;IACxL,gBAAgB,CAAC,KAAK,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ1E,yHAAyH;IACzH,SAAS,CAAC,oBAAoB,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAMxD,yNAAyN;IACzN,SAAS,CAAC,mBAAmB,CAAC,WAAW,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,IAAI,EAAE;QACxE,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,WAAW,GAAG,SAAS,CAAC;QAC/D,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;CAmDhC"}

package/dist/cjs/base/datasources/abstract.js

@@ -1,94 +0,0 @@
-"use strict";
-var _a;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AbstractDataSource = exports.isDataSourceClass = exports.DATA_SOURCE_BRAND = void 0;
-const inversion_1 = require("../../helpers/inversion");
-const utilities_1 = require("../../utilities");
-const core_1 = require("@venizia/ignis-helpers/core");
-/**
- * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.
- *
- * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is
- * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is
- * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every
- * subclass however deep.
- */
-exports.DATA_SOURCE_BRAND = Symbol.for('@venizia/ignis-kernel:abstract-data-source');
-/** True for `AbstractDataSource` itself and for any class extending it, across package copies. */
-const isDataSourceClass = (value) => {
-    return typeof value === 'function' && exports.DATA_SOURCE_BRAND in value;
-};
-exports.isDataSourceClass = isDataSourceClass;
-/** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */
-class AbstractDataSource extends core_1.BaseHelper {
-    static { _a = exports.DATA_SOURCE_BRAND; }
-    /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */
-    static { this[_a] = true; }
-    getSettings() {
-        return this.settings;
-    }
-    getSchema() {
-        if (!this.schema) {
-            throw (0, core_1.getError)({
-                message: `[${this.constructor.name}] Schema not initialized. Override getSchema() or provide schema in constructor.`,
-            });
-        }
-        return this.schema;
-    }
-    /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */
-    getCapabilities() {
-        return { transactions: false };
-    }
-    /** Nothing to release at this root; a family that holds a connection overrides it. */
-    close() {
-        return Promise.resolve();
-    }
-    /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */
-    async beginTransaction(_opts) {
-        return (0, utilities_1.throwNotSupported)({
-            scope: this.constructor.name,
-            feature: 'Transactions',
-            logger: this.logger,
-        });
-    }
-    /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */
-    getBoundModelClasses() {
-        return inversion_1.MetadataRegistry.getInstance().getModelClasses({
-            dataSource: this.constructor,
-        });
-    }
-    /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */
-    discoverDefinitions(opts) {
-        const { read, kind } = opts;
-        const logger = this.logger.for(this.discoverDefinitions.name);
-        const registry = inversion_1.MetadataRegistry.getInstance();
-        const metadata = registry.getDataSourceMetadata({ target: this.constructor });
-        if (metadata?.autoDiscovery === false) {
-            logger.debug('Auto-discovery disabled for %s', this.name);
-            return {};
-        }
-        const modelClasses = this.getBoundModelClasses();
-        const definitions = {};
-        const definitionOwners = new Map();
-        for (const modelClass of modelClasses) {
-            const definition = read(modelClass);
-            if (!definition) {
-                logger.warn('Model has no %s definition | Skipping | Name: %s | Model: %s', kind, this.name, modelClass.name);
-                continue;
-            }
-            const existingOwner = definitionOwners.get(definition.name);
-            if (existingOwner !== undefined && existingOwner !== modelClass.name) {
-                throw (0, core_1.getError)({
-                    message: `[${this.constructor.name}][discoverDefinitions] Duplicate ${kind} name '${definition.name}' | Name: ${this.name} | Classes: ${existingOwner}, ${modelClass.name}`,
-                });
-            }
-            definitionOwners.set(definition.name, modelClass.name);
-            definitions[definition.name] = definition;
-        }
-        const names = Object.keys(definitions);
-        logger.debug('Detected %s(s) | Name: %s | Count: %s | Names: %j', kind, this.name, names.length, names);
-        return definitions;
-    }
-}
-exports.AbstractDataSource = AbstractDataSource;
-//# sourceMappingURL=abstract.js.map

package/dist/cjs/base/datasources/abstract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract.js","sourceRoot":"","sources":["../../../../src/base/datasources/abstract.ts"],"names":[],"mappings":"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","sourcesContent":["import { MetadataRegistry } from '@/helpers/inversion';\nimport { throwNotSupported } from '@/utilities';\nimport type { AnyType, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { BaseHelper, getError } from '@venizia/ignis-helpers/core';\nimport type {\n  IDataSource,\n  IDataSourceCapabilities,\n  ITransaction,\n  ITransactionOptions,\n  TAnyDataSourceSchema,\n} from './common';\n\n/**\n * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.\n *\n * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is\n * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is\n * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every\n * subclass however deep.\n */\nexport const DATA_SOURCE_BRAND = Symbol.for('@venizia/ignis-kernel:abstract-data-source');\n\n/** True for `AbstractDataSource` itself and for any class extending it, across package copies. */\nexport const isDataSourceClass = (value: unknown): value is TClass<AnyType> => {\n  return typeof value === 'function' && DATA_SOURCE_BRAND in value;\n};\n\n/** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */\nexport abstract class AbstractDataSource<\n  Settings extends object = {},\n  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n  ConfigurableOptions extends object = {},\n>\n  extends BaseHelper\n  implements IDataSource<Settings, Schema, ConfigurableOptions>\n{\n  /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */\n  static readonly [DATA_SOURCE_BRAND] = true;\n\n  name: string;\n  settings: Settings;\n  schema: Schema;\n\n  abstract configure(opts?: ConfigurableOptions): ValueOrPromise<void>;\n\n  getSettings() {\n    return this.settings;\n  }\n\n  getSchema(): Schema {\n    if (!this.schema) {\n      throw getError({\n        message: `[${this.constructor.name}] Schema not initialized. Override getSchema() or provide schema in constructor.`,\n      });\n    }\n    return this.schema;\n  }\n\n  /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */\n  getCapabilities(): IDataSourceCapabilities {\n    return { transactions: false };\n  }\n\n  /** Nothing to release at this root; a family that holds a connection overrides it. */\n  close(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */\n  async beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction> {\n    return throwNotSupported({\n      scope: this.constructor.name,\n      feature: 'Transactions',\n      logger: this.logger,\n    });\n  }\n\n  /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */\n  protected getBoundModelClasses(): Array<TClass<unknown>> {\n    return MetadataRegistry.getInstance().getModelClasses({\n      dataSource: this.constructor as TClass<IDataSource>,\n    });\n  }\n\n  /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */\n  protected discoverDefinitions<TDefinition extends { name: string }>(opts: {\n    read: (modelClass: TClass<unknown>) => TDefinition | undefined;\n    kind: string;\n  }): Record<string, TDefinition> {\n    const { read, kind } = opts;\n    const logger = this.logger.for(this.discoverDefinitions.name);\n    const registry = MetadataRegistry.getInstance();\n\n    const metadata = registry.getDataSourceMetadata({ target: this.constructor });\n    if (metadata?.autoDiscovery === false) {\n      logger.debug('Auto-discovery disabled for %s', this.name);\n      return {};\n    }\n\n    const modelClasses = this.getBoundModelClasses();\n\n    const definitions: Record<string, TDefinition> = {};\n    const definitionOwners = new Map<string, string>();\n\n    for (const modelClass of modelClasses) {\n      const definition = read(modelClass);\n\n      if (!definition) {\n        logger.warn(\n          'Model has no %s definition | Skipping | Name: %s | Model: %s',\n          kind,\n          this.name,\n          modelClass.name,\n        );\n        continue;\n      }\n\n      const existingOwner = definitionOwners.get(definition.name);\n      if (existingOwner !== undefined && existingOwner !== modelClass.name) {\n        throw getError({\n          message: `[${this.constructor.name}][discoverDefinitions] Duplicate ${kind} name '${definition.name}' | Name: ${this.name} | Classes: ${existingOwner}, ${modelClass.name}`,\n        });\n      }\n\n      definitionOwners.set(definition.name, modelClass.name);\n      definitions[definition.name] = definition;\n    }\n\n    const names = Object.keys(definitions);\n    logger.debug(\n      'Detected %s(s) | Name: %s | Count: %s | Names: %j',\n      kind,\n      this.name,\n      names.length,\n      names,\n    );\n\n    return definitions;\n  }\n}\n"]}

package/dist/cjs/base/datasources/common/index.d.ts

@@ -1,2 +0,0 @@
-export * from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/cjs/base/datasources/common/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/base/datasources/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

package/dist/cjs/base/datasources/common/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./types"), exports);
-//# sourceMappingURL=index.js.map

package/dist/cjs/base/datasources/common/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/base/datasources/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB","sourcesContent":["export * from './types';\n"]}

package/dist/cjs/base/datasources/common/types.d.ts

@@ -1,60 +0,0 @@
-import type { AnyType, IConfigurable, TClass, TConstValue } from '@venizia/ignis-helpers/common';
-export declare class DataSourceDrivers {
-    static readonly NODE_POSTGRES = "node-postgres";
-    static readonly POSTGRES_JS = "postgres-js";
-    static readonly PGLITE = "pglite";
-    static readonly LIBSQL = "libsql";
-    static readonly TYPESENSE = "typesense";
-    static readonly MEILISEARCH = "meilisearch";
-    static readonly RELATIONAL_SCHEME_SET: Set<string>;
-    static readonly SEARCH_SCHEME_SET: Set<string>;
-    static readonly SCHEME_SET: Set<string>;
-    static isValid(value: string): boolean;
-}
-export type TDataSourceDriver = TConstValue<typeof DataSourceDrivers> | (string & {});
-/**
- * A driver CLASS, named by `@datasource({ driver })`. The class reference is what pulls the peer
- * package into a bundle - a name string pulls nothing, and a bare side-effect import may be
- * dropped. Untyped because `IRelationalDriver` lives under `connectors/`, off-limits to `base/`.
- */
-export type TDataSourceDriverClass = TClass<AnyType>;
-export type TAnyDataSourceSchema = Record<string, any>;
-/** Engine-neutral datasource contract - the root every connector family implements. */
-export interface IDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}> extends IConfigurable<ConfigurableOptions> {
-    name: string;
-    settings: Settings;
-    schema: Schema;
-    getSettings(): Settings;
-    getSchema(): Schema;
-    /** Releases what `configure()` opened. `stop()` calls it on every datasource the boot configured. */
-    close?(): Promise<void>;
-}
-/**
- * Neutral transaction options - isolation levels are engine vocabulary, so `isolationLevel` stays
- * a loose string here and connectors narrow it in their own `ITransactionOptions` extension.
- */
-export interface ITransactionOptions {
-    isolationLevel?: string;
-}
-/** Neutral transaction handle - the minimum shape every connector's transaction satisfies. */
-export interface ITransaction {
-    isActive: boolean;
-    commit(): Promise<void>;
-    rollback(): Promise<void>;
-}
-export interface IDataSourceCapabilities {
-    transactions: boolean;
-}
-export interface ISearchableDataSourceCapabilities extends IDataSourceCapabilities {
-    search?: {
-        /** Vector / semantic / hybrid search (search engines). */
-        vector?: boolean;
-        /** Batched multi-query search across collections. */
-        multi?: boolean;
-        /** Merged (union) result set across a multi-search. */
-        union?: boolean;
-        /** Synonym sets (multi-way / one-way). */
-        synonyms?: boolean;
-    };
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/cjs/base/datasources/common/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/datasources/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjG,qBAAa,iBAAiB;IAE5B,MAAM,CAAC,QAAQ,CAAC,aAAa,mBAAmB;IAChD,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAC5C,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAClC,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAGlC,MAAM,CAAC,QAAQ,CAAC,SAAS,eAAe;IACxC,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAE5C,MAAM,CAAC,QAAQ,CAAC,qBAAqB,cAKlC;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,cAA+C;IAEhF,MAAM,CAAC,QAAQ,CAAC,UAAU,cAUvB;IAEH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGvC;AAID,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEtF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvD,uFAAuF;AACvF,MAAM,WAAW,WAAW,CAC1B,QAAQ,SAAS,MAAM,GAAG,EAAE,EAC5B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,mBAAmB,SAAS,MAAM,GAAG,EAAE,CACvC,SAAQ,aAAa,CAAC,mBAAmB,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,IAAI,QAAQ,CAAC;IACxB,SAAS,IAAI,MAAM,CAAC;IAEpB,qGAAqG;IACrG,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,iCAAkC,SAAQ,uBAAuB;IAChF,MAAM,CAAC,EAAE;QACP,0DAA0D;QAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;QAEjB,qDAAqD;QACrD,KAAK,CAAC,EAAE,OAAO,CAAC;QAEhB,uDAAuD;QACvD,KAAK,CAAC,EAAE,OAAO,CAAC;QAEhB,0CAA0C;QAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH"}

package/dist/cjs/base/datasources/common/types.js

@@ -1,35 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataSourceDrivers = void 0;
-class DataSourceDrivers {
-    // Relational - PGlite is a Postgres DRIVER (Postgres compiled to WASM), not a separate engine.
-    static { this.NODE_POSTGRES = 'node-postgres'; }
-    static { this.POSTGRES_JS = 'postgres-js'; }
-    static { this.PGLITE = 'pglite'; }
-    static { this.LIBSQL = 'libsql'; }
-    // Search
-    static { this.TYPESENSE = 'typesense'; }
-    static { this.MEILISEARCH = 'meilisearch'; }
-    static { this.RELATIONAL_SCHEME_SET = new Set([
-        this.NODE_POSTGRES,
-        this.POSTGRES_JS,
-        this.PGLITE,
-        this.LIBSQL,
-    ]); }
-    static { this.SEARCH_SCHEME_SET = new Set([this.TYPESENSE, this.MEILISEARCH]); }
-    static { this.SCHEME_SET = new Set([
-        // Relational
-        this.NODE_POSTGRES,
-        this.POSTGRES_JS,
-        this.PGLITE,
-        this.LIBSQL,
-        // Search
-        this.TYPESENSE,
-        this.MEILISEARCH,
-    ]); }
-    static isValid(value) {
-        return this.SCHEME_SET.has(value);
-    }
-}
-exports.DataSourceDrivers = DataSourceDrivers;
-//# sourceMappingURL=types.js.map

package/dist/cjs/base/datasources/common/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/datasources/common/types.ts"],"names":[],"mappings":";;;AAEA,MAAa,iBAAiB;IAC5B,+FAA+F;aAC/E,kBAAa,GAAG,eAAe,CAAC;aAChC,gBAAW,GAAG,aAAa,CAAC;aAC5B,WAAM,GAAG,QAAQ,CAAC;aAClB,WAAM,GAAG,QAAQ,CAAC;IAElC,SAAS;aACO,cAAS,GAAG,WAAW,CAAC;aACxB,gBAAW,GAAG,aAAa,CAAC;aAE5B,0BAAqB,GAAG,IAAI,GAAG,CAAC;QAC9C,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;KACZ,CAAC,CAAC;aACa,sBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;aAEhE,eAAU,GAAG,IAAI,GAAG,CAAC;QACnC,aAAa;QACb,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;QAEX,SAAS;QACT,IAAI,CAAC,SAAS;QACd,IAAI,CAAC,WAAW;KACjB,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAjCH,8CAkCC","sourcesContent":["import type { AnyType, IConfigurable, TClass, TConstValue } from '@venizia/ignis-helpers/common';\n\nexport class DataSourceDrivers {\n  // Relational - PGlite is a Postgres DRIVER (Postgres compiled to WASM), not a separate engine.\n  static readonly NODE_POSTGRES = 'node-postgres';\n  static readonly POSTGRES_JS = 'postgres-js';\n  static readonly PGLITE = 'pglite';\n  static readonly LIBSQL = 'libsql';\n\n  // Search\n  static readonly TYPESENSE = 'typesense';\n  static readonly MEILISEARCH = 'meilisearch';\n\n  static readonly RELATIONAL_SCHEME_SET = new Set([\n    this.NODE_POSTGRES,\n    this.POSTGRES_JS,\n    this.PGLITE,\n    this.LIBSQL,\n  ]);\n  static readonly SEARCH_SCHEME_SET = new Set([this.TYPESENSE, this.MEILISEARCH]);\n\n  static readonly SCHEME_SET = new Set([\n    // Relational\n    this.NODE_POSTGRES,\n    this.POSTGRES_JS,\n    this.PGLITE,\n    this.LIBSQL,\n\n    // Search\n    this.TYPESENSE,\n    this.MEILISEARCH,\n  ]);\n\n  static isValid(value: string): boolean {\n    return this.SCHEME_SET.has(value);\n  }\n}\n\n// `(string & {})` keeps autocomplete for the known values\n// while still accepting any other engine-driver string.\nexport type TDataSourceDriver = TConstValue<typeof DataSourceDrivers> | (string & {});\n\n/**\n * A driver CLASS, named by `@datasource({ driver })`. The class reference is what pulls the peer\n * package into a bundle - a name string pulls nothing, and a bare side-effect import may be\n * dropped. Untyped because `IRelationalDriver` lives under `connectors/`, off-limits to `base/`.\n */\nexport type TDataSourceDriverClass = TClass<AnyType>;\n\nexport type TAnyDataSourceSchema = Record<string, any>;\n\n/** Engine-neutral datasource contract - the root every connector family implements. */\nexport interface IDataSource<\n  Settings extends object = {},\n  Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n  ConfigurableOptions extends object = {},\n> extends IConfigurable<ConfigurableOptions> {\n  name: string;\n  settings: Settings;\n  schema: Schema;\n\n  getSettings(): Settings;\n  getSchema(): Schema;\n\n  /** Releases what `configure()` opened. `stop()` calls it on every datasource the boot configured. */\n  close?(): Promise<void>;\n}\n\n/**\n * Neutral transaction options - isolation levels are engine vocabulary, so `isolationLevel` stays\n * a loose string here and connectors narrow it in their own `ITransactionOptions` extension.\n */\nexport interface ITransactionOptions {\n  isolationLevel?: string;\n}\n\n/** Neutral transaction handle - the minimum shape every connector's transaction satisfies. */\nexport interface ITransaction {\n  isActive: boolean;\n  commit(): Promise<void>;\n  rollback(): Promise<void>;\n}\n\nexport interface IDataSourceCapabilities {\n  transactions: boolean;\n}\n\nexport interface ISearchableDataSourceCapabilities extends IDataSourceCapabilities {\n  search?: {\n    /** Vector / semantic / hybrid search (search engines). */\n    vector?: boolean;\n\n    /** Batched multi-query search across collections. */\n    multi?: boolean;\n\n    /** Merged (union) result set across a multi-search. */\n    union?: boolean;\n\n    /** Synonym sets (multi-way / one-way). */\n    synonyms?: boolean;\n  };\n}\n"]}

package/dist/cjs/base/datasources/index.d.ts

@@ -1,3 +0,0 @@
-export * from './abstract';
-export * from './common';
-//# sourceMappingURL=index.d.ts.map

package/dist/cjs/base/datasources/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/datasources/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}