@edium/halifax 1.0.0 → 2.1.0

package/dist/adapters/http/UltimateExpressAdapter.js

@@ -0,0 +1,108 @@
+import ultimateExpress from 'ultimate-express';
+import { registerCrudApi } from '../../core/crudRouter.js';
+const { Router } = ultimateExpress;
+/** Maps a Halifax {@link HttpMethod} to the corresponding Ultimate Express registration method name. */
+const METHOD_TO_REGISTRAR = {
+    GET: 'get',
+    POST: 'post',
+    PUT: 'put',
+    PATCH: 'patch',
+    DELETE: 'delete'
+};
+/**
+ * Wraps an Ultimate Express request in Halifax's framework-agnostic {@link HttpRequest}.
+ * @param req - The Ultimate Express request to adapt.
+ * @returns A Halifax-compatible {@link HttpRequest} with the original request in `raw`.
+ */
+function adaptRequest(req) {
+    return {
+        method: req.method,
+        params: req.params,
+        query: req.query,
+        body: req.body,
+        headers: req.headers,
+        raw: req
+    };
+}
+/**
+ * Wraps an Ultimate Express response in Halifax's framework-agnostic {@link HttpResponse}.
+ * @param res - The Ultimate Express response to adapt.
+ * @returns A Halifax-compatible {@link HttpResponse} with the original response in `raw`.
+ */
+function adaptResponse(res) {
+    return {
+        raw: res,
+        status(code) {
+            res.status(code);
+            return this;
+        },
+        json(payload) {
+            res.json(payload);
+        },
+        send(payload) {
+            res.send(payload);
+        },
+        setHeader(name, value) {
+            res.setHeader(name, value);
+        }
+    };
+}
+/**
+ * Adapts an Ultimate Express `App` or `Router` to Halifax's {@link HttpServer} interface.
+ *
+ * Because Ultimate Express implements the Express API, this adapter is a near-identical
+ * twin of {@link ExpressHttpServer}: it uses the same route methods, `:id` named params
+ * (never `*` path wildcards), and request/response surface. The difference is purely the
+ * underlying transport (uWebSockets), which is faster but otherwise transparent.
+ */
+export class UltimateExpressHttpServer {
+    app;
+    /**
+     * @param app - Ultimate Express application or router to register routes on.
+     *   When an `App` is provided, `start()` will call `listen()`.
+     *   When a `Router` is provided, `start()` is a no-op.
+     */
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Registers a route on the app for the given method and path.
+     * @param method - HTTP method (or `'*'` to register a catch-all via `app.all`).
+     * @param path - Route path pattern (e.g. `'/users/:id'`).
+     * @param handler - Halifax route handler to invoke on matching requests.
+     */
+    registerRoute(method, path, handler) {
+        const cb = (req, res) => {
+            void Promise.resolve(handler(adaptRequest(req), adaptResponse(res)));
+        };
+        const register = method === '*' ? this.app.all : this.app[METHOD_TO_REGISTRAR[method]];
+        register.call(this.app, path, cb);
+    }
+    /**
+     * Starts the server. No-op when the underlying app does not expose a `listen` method
+     * (e.g. when `app` is a `Router` mounted on an existing app).
+     * @param port - TCP port number to bind to.
+     * @param host - Hostname or IP address to bind to (defaults to all interfaces when omitted).
+     */
+    async start(port, host) {
+        await new Promise((resolve) => {
+            if (typeof this.app.listen === 'function') {
+                this.app.listen(port, host, () => resolve());
+                return;
+            }
+            resolve();
+        });
+    }
+}
+/**
+ * Creates a fully-wired Ultimate Express `Router` with CRUD routes for every resource.
+ *
+ * @param resources - Resource definitions to register (use {@link createPrismaResources} to generate these).
+ * @param options - Auth strategy, query-builder path overrides, etc.
+ * @returns An Ultimate Express `Router` ready to mount with `app.use('/api', router)`.
+ */
+export function createUltimateExpressCrudRouter(resources, options = {}) {
+    const router = Router();
+    registerCrudApi(new UltimateExpressHttpServer(router), resources, options);
+    return router;
+}

package/dist/adapters/orm/prisma/PrismaAdapter.d.ts

@@ -1,35 +1,80 @@
 import type { IQueryOptions } from '../../../interfaces/IQueryOptions.js';
-import type { Repository, RepositoryCapabilities, DeleteManyResult, ListOptions, ListResult, NativeQueryResult, UpdateManyResult } from '../../../core/types.js';
+import type { Repository, RepositoryCapabilities, DeleteManyResult, ListOptions, ListResult, QueryResult, TenantScope, UpdateManyResult } from '../../../core/types.js';
 import type { FieldDefinition, RelationDefinition, ModelSchema } from '../../../core/types.js';
 import type { PrismaAdapterOptions } from './types.js';
 /**
- * PrismaAdapter is a generic repository implementation that uses Prisma delegates to perform database operations.
- * It supports basic CRUD operations and can be extended to support more complex queries.
- * The adapter can optionally use a Prisma client for executing raw SQL queries when needed.
- * It also extracts field and relation definitions from a provided Prisma model schema to enhance query capabilities.
+ * PrismaAdapter is a generic repository implementation that uses Prisma delegates to perform
+ * database operations. It handles CRUD plus the query-builder/bulk paths by compiling the
+ * query AST to portable Prisma Client calls (no raw SQL), so it works on every Prisma
+ * provider. It also extracts field and relation definitions from a provided model schema.
  */
 export declare class PrismaAdapter<TRecord = unknown, TCreate = Partial<TRecord>, TUpdate = Partial<TRecord>> implements Repository<TRecord, TCreate, TUpdate> {
-    /** Private properties to hold the Prisma delegate, client, and configuration options. */
+    /** Private properties to hold the Prisma delegate and configuration options. */
     private readonly delegate;
-    /**  Optional Prisma client for executing raw SQL queries, required for certain operations like updateMany and deleteMany. */
-    private readonly client?;
     /** The field name used for the primary key in the model. */
-    private readonly idField;
-    /** The name of the database table associated with the model. */
-    private readonly tableName?;
+    readonly idField: string;
     /** A flag indicating whether to return created records. */
     private readonly returnCreated;
+    /** The original construction options, used to build request-scoped clones. */
+    private readonly options;
+    /** Tenant constraint bound to this instance, or `undefined` for unscoped access. */
+    private readonly scope?;
     /** A set of capabilities that the repository supports. */
     readonly capabilities: RepositoryCapabilities;
-    /** An array of field definitions for the model. */
-    readonly fields: FieldDefinition[] | undefined;
-    /** An array of relation definitions for the model. */
-    readonly relations: RelationDefinition[] | undefined;
+    /** An array of field definitions for the model (present when built with a `model`). */
+    readonly fields?: FieldDefinition[];
+    /** An array of relation definitions for the model (present when built with a `model`). */
+    readonly relations?: RelationDefinition[];
     /**
      * Constructs a new instance of PrismaAdapter with the provided options.
-     * @param options - An object containing the Prisma delegate, optional client, and configuration settings for the adapter.
+     * @param options - The Prisma delegate plus optional id field, return-created flag, and model schema.
      */
     constructor(options: PrismaAdapterOptions);
+    /**
+     * Returns a request-scoped clone of this adapter bound to `scope`. Every read is
+     * filtered by the scope, every write is stamped with it, and every bulk/SQL operation
+     * has the scope AND-ed into its WHERE clause. The original instance is never mutated.
+     * @param scope - The resolved tenant constraint for the current request.
+     * @returns A new {@link PrismaAdapter} that enforces `scope` on all operations.
+     */
+    withScope(scope: TenantScope): PrismaAdapter<TRecord, TCreate, TUpdate>;
+    /**
+     * Merges the bound tenant constraint into a Prisma `where` object. The scope is spread
+     * last so it always wins over any caller-supplied value for the same key.
+     * @param where - The caller-derived where clause (may be undefined).
+     * @returns A where object with the tenant constraint applied, or `where` when unscoped.
+     */
+    private scopedWhere;
+    /**
+     * Removes the tenant field from a write payload so callers can never reassign a row
+     * to another tenant via create/update/upsert bodies. No-op when unscoped.
+     * @param data - The write payload to sanitise.
+     * @returns A copy of `data` without the tenant field, or `data` when unscoped.
+     */
+    private stripTenant;
+    /**
+     * Stamps the bound tenant value onto a create payload, overriding any caller-supplied
+     * value for the tenant field. No-op when unscoped.
+     * @param data - The create payload.
+     * @returns A copy of `data` with the tenant field forced to the scope value.
+     */
+    private stampTenant;
+    /**
+     * AND-s the bound tenant constraint into a query-builder WHERE clause. The caller's filters
+     * are nested as a child group beneath the tenant condition, so a caller-supplied `OR` can
+     * never break out of the tenant boundary once the AST is compiled to a Prisma `where`.
+     * @param where - The caller-supplied filter list (may be undefined/empty).
+     * @returns A new filter list with the tenant condition enforced, or `where` when unscoped.
+     */
+    private scopedFilters;
+    /**
+     * Resolves a query-builder AST for the tenant-scoped paths: applies the tenant constraint
+     * via {@link PrismaAdapter.scopedFilters}. The `where` key is only set when defined (to
+     * satisfy `exactOptionalPropertyTypes`).
+     * @param query - The incoming query AST.
+     * @returns A new AST with the tenant scope applied.
+     */
+    private resolveScopedQuery;
     /**
      * Extracts field definitions from a Prisma model schema.
      * @param model - The Prisma model schema.
@@ -81,21 +126,19 @@ export declare class PrismaAdapter<TRecord = unknown, TCreate = Partial<TRecord>
      */
     updateOne(id: string | number, data: TUpdate): Promise<TRecord | null>;
     /**
-     * Updates multiple records that match the provided query options with the given data.
-     * This method requires a Prisma client for executing raw SQL queries, as Prisma does not
-     * natively support bulk updates with return values. It first selects the IDs of the records
-     * to be updated based on the query options, then executes an update query, and finally returns
-     * the IDs of the updated records.
+     * Updates every record matching the query and returns the IDs of the affected rows.
      *
-     * **Note:** The SELECT and UPDATE are issued as two separate queries without a transaction.
-     * Under concurrent writes, rows inserted or deleted between the two queries may cause the
-     * returned `updated` IDs to differ from the rows actually modified.
+     * The query AST is compiled to a portable Prisma `where` (no raw SQL), so this works on
+     * every Prisma provider. Because Prisma's `updateMany` only returns a count, the matching
+     * IDs are selected first and then the bulk update is applied.
+     *
+     * **Note:** the SELECT and UPDATE are two separate statements without a transaction; under
+     * concurrent writes the returned `updated` IDs may differ from the rows actually modified.
      *
-     * @param query - An object containing query options to filter the records that should be updated, such as where conditions, sorting, and pagination.
-     * @param data - An object containing the data to update the matching records with.
-     * @returns A promise that resolves to an object containing an array of the IDs of the updated records.
-     * @throws NotImplementedError if the Prisma client or tableName is not provided, as they are required for executing raw SQL queries.
-     * @throws ServerError if the Prisma client does not support the required methods for executing raw SQL queries.
+     * @param query - Query AST describing which rows to update (filtered, tenant-scoped).
+     * @param data - Fields to apply to all matching rows (the tenant field is stripped).
+     * @returns The IDs of the updated rows.
+     * @throws NotImplementedError when the delegate does not support `updateMany`.
      */
     updateMany(query: IQueryOptions, data: TUpdate): Promise<UpdateManyResult<TRecord>>;
     /**
@@ -125,19 +168,25 @@ export declare class PrismaAdapter<TRecord = unknown, TCreate = Partial<TRecord>
      * Under concurrent writes, rows inserted or deleted between the two queries may cause the
      * returned `deleted` IDs to differ from the rows actually removed.
      *
-     * @param query - An object containing query options to filter the records that should be deleted, such as where conditions, sorting, and pagination.
-     * @returns A promise that resolves to an object containing an array of the IDs of the deleted records.
-     * @throws NotImplementedError if the Prisma client or tableName is not provided, as they are required for executing raw SQL queries.
-     * @throws ServerError if the Prisma client does not support the required methods for executing raw SQL queries.
+     * @param query - Query AST describing which rows to delete (filtered, tenant-scoped).
+     * @returns The IDs of the deleted rows.
+     * @throws NotImplementedError when the delegate does not support `deleteMany`.
      */
     deleteMany(query: IQueryOptions): Promise<DeleteManyResult>;
     /**
-     * Executes a query built using the QueryBuilder, which allows for complex filtering, sorting, pagination, and field selection. This method requires a Prisma client for executing raw SQL queries, as it relies on the QueryBuilder to generate SQL statements. It first builds a count query to get the total number of matching records and then builds a select query to retrieve the actual records based on the provided query options.
-     * @param query - An object containing query options such as filtering conditions, sorting, pagination, and field selection, which will be used to build the SQL queries.
-     * @returns A promise that resolves to an object containing the total count of matching records and an array of the retrieved records.
-     * @throws NotImplementedError if the Prisma client or tableName is not provided, as they are required for executing raw SQL queries.
-     * @throws ServerError if the Prisma client does not support the required methods for executing raw SQL queries.
+     * Executes a query-builder AST as a portable Prisma query: the WHERE tree is compiled to a
+     * Prisma `where`, and field projection, ordering, pagination, and `distinct` are mapped to
+     * `findMany` arguments. No raw SQL is generated, so the same query runs identically on every
+     * Prisma provider (PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB, MongoDB).
+     *
+     * Validation (field/comparison/depth checks → 4xx) happens in the router *before* this
+     * method, so malformed queries never reach Prisma.
+     *
+     * **Note:** the COUNT and SELECT are two separate statements without a transaction; under
+     * concurrent writes the returned `count` may differ from the number of rows in `results`.
+     *
+     * @param query - The validated query AST (filters, sort, pagination, projection, distinct).
+     * @returns A count-and-results envelope for the matching rows.
      */
-    executeQueryBuilder(query: IQueryOptions): Promise<NativeQueryResult<TRecord>>;
+    executeQuery(query: IQueryOptions): Promise<QueryResult<TRecord>>;
 }
-//# sourceMappingURL=PrismaAdapter.d.ts.map