@rawsql-ts/sql-contract 0.1.0 → 0.2.0

package/dist/catalog/index.js

@@ -0,0 +1,377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogExecutionError = exports.ContractViolationError = exports.BinderError = exports.RewriterError = exports.SQLLoaderError = exports.CatalogError = void 0;
+exports.createCatalogExecutor = createCatalogExecutor;
+const mapper_1 = require("../mapper");
+let execIdCounter = 0;
+function createExecId() {
+    execIdCounter += 1;
+    return `catalog-exec-${Date.now()}-${execIdCounter}`;
+}
+/**
+ * Root error class for catalog execution failures.
+ */
+class CatalogError extends Error {
+    constructor(message, specId, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        this.specId = specId;
+        this.cause = cause;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.CatalogError = CatalogError;
+/** Wraps failures encountered while loading catalog SQL assets. */
+class SQLLoaderError extends CatalogError {
+}
+exports.SQLLoaderError = SQLLoaderError;
+/** Wraps failures thrown by catalog rewriters. */
+class RewriterError extends CatalogError {
+}
+exports.RewriterError = RewriterError;
+/** Wraps binder failures or invalid binder output. */
+class BinderError extends CatalogError {
+}
+exports.BinderError = BinderError;
+/** Captures violations of the declared query/catalog contract before hitting the executor. */
+class ContractViolationError extends CatalogError {
+}
+exports.ContractViolationError = ContractViolationError;
+/** Wraps failures from the query executor or result shaping.
+ * Contract violations must throw `ContractViolationError` instead so observability
+ * can consistently classify them as `contract`.
+ */
+class CatalogExecutionError extends CatalogError {
+}
+exports.CatalogExecutionError = CatalogExecutionError;
+function assertPositionalParams(specId, params) {
+    if (!Array.isArray(params)) {
+        throw new ContractViolationError(`Spec "${specId}" expects positional parameters.`, specId);
+    }
+    return params;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    // Accept `{}`-like objects and those created via Object.create(null).
+    return proto === Object.prototype || proto === null;
+}
+function assertNamedParams(specId, params) {
+    if (!isPlainObject(params)) {
+        throw new ContractViolationError(`Spec "${specId}" expects named parameters.`, specId);
+    }
+    return params;
+}
+function assertParamsShape(specId, expectedShape, params) {
+    if (expectedShape === 'positional') {
+        return assertPositionalParams(specId, params);
+    }
+    return assertNamedParams(specId, params);
+}
+/**
+ * Creates a CatalogExecutor that enforces the QuerySpec contract and applies
+ * optional rewriters and binders before delegating to the target query executor.
+ */
+function createCatalogExecutor(options) {
+    var _a, _b, _c, _d, _e;
+    const cache = (_a = options.sqlCache) !== null && _a !== void 0 ? _a : new Map();
+    const rewriters = (_b = options.rewriters) !== null && _b !== void 0 ? _b : [];
+    const binders = (_c = options.binders) !== null && _c !== void 0 ? _c : [];
+    const allowNamedWithoutBinder = (_d = options.allowNamedParamsWithoutBinder) !== null && _d !== void 0 ? _d : false;
+    const extensions = (_e = options.extensions) !== null && _e !== void 0 ? _e : [];
+    const sink = options.observabilitySink;
+    async function loadSql(spec) {
+        const cached = cache.get(spec.sqlFile);
+        if (cached !== undefined) {
+            return cached;
+        }
+        try {
+            const sql = await options.loader.load(spec.sqlFile);
+            cache.set(spec.sqlFile, sql);
+            return sql;
+        }
+        catch (cause) {
+            throw new SQLLoaderError(`Failed to load SQL file "${spec.sqlFile}".`, spec.id, cause);
+        }
+    }
+    function normalizeToQueryParams(value, specId) {
+        if (Array.isArray(value)) {
+            return value;
+        }
+        if (isPlainObject(value)) {
+            return value;
+        }
+        throw new ContractViolationError(`Parameters must be positional or named (array or record).`, specId);
+    }
+    function applyRewriters(spec, sql, params, options) {
+        let currentSql = sql;
+        let currentParams = params;
+        for (const rewriter of rewriters) {
+            try {
+                const rewritten = rewriter.rewrite({
+                    specId: spec.id,
+                    spec,
+                    sql: currentSql,
+                    params: currentParams,
+                    options,
+                });
+                currentSql = rewritten.sql;
+                currentParams = rewritten.params;
+            }
+            catch (cause) {
+                throw new RewriterError(`Rewriter "${rewriter.name}" failed for spec "${spec.id}".`, spec.id, cause);
+            }
+        }
+        return {
+            sql: currentSql,
+            params: currentParams,
+        };
+    }
+    function applyBinders(spec, sql, params) {
+        if (binders.length === 0) {
+            return { binderUsed: false, sql, params };
+        }
+        let currentSql = sql;
+        let currentParams = params;
+        for (const binder of binders) {
+            try {
+                const bound = binder.bind({
+                    specId: spec.id,
+                    sql: currentSql,
+                    params: normalizeToQueryParams(currentParams, spec.id),
+                });
+                if (!Array.isArray(bound.params)) {
+                    throw new BinderError(`Binder "${binder.name}" returned invalid params for spec "${spec.id}".`, spec.id);
+                }
+                currentSql = bound.sql;
+                currentParams = bound.params;
+            }
+            catch (cause) {
+                if (cause instanceof CatalogError) {
+                    throw cause;
+                }
+                throw new BinderError(`Binder "${binder.name}" failed for spec "${spec.id}".`, spec.id, cause);
+            }
+        }
+        if (!Array.isArray(currentParams)) {
+            throw new BinderError(`Binder chain did not produce positional params for spec "${spec.id}".`, spec.id);
+        }
+        return {
+            binderUsed: true,
+            sql: currentSql,
+            params: currentParams,
+        };
+    }
+    function describeParamsShape(params) {
+        if (Array.isArray(params)) {
+            return 'positional';
+        }
+        if (isPlainObject(params)) {
+            return 'named';
+        }
+        return 'unknown';
+    }
+    function createSqlPreview(sql) {
+        const maxLength = 2048;
+        return sql.length <= maxLength ? sql : sql.slice(0, maxLength);
+    }
+    function getErrorKind(error) {
+        if (error instanceof CatalogExecutionError) {
+            return 'db';
+        }
+        if (error instanceof CatalogError) {
+            return 'contract';
+        }
+        return 'unknown';
+    }
+    function emitQueryStartEvent(spec, execId, attempt, snapshot) {
+        if (!sink) {
+            return;
+        }
+        sink.emit({
+            kind: 'query_start',
+            specId: spec.id,
+            sqlFile: spec.sqlFile,
+            execId,
+            attempt,
+            timeMs: snapshot.startTime,
+            attributes: spec.tags,
+            sqlPreview: createSqlPreview(snapshot.sql),
+            paramsShape: snapshot.paramsShape,
+        });
+    }
+    function emitQueryEndEvent(spec, execId, attempt, baseStartTime, rowCount) {
+        if (!sink) {
+            return;
+        }
+        const now = Date.now();
+        sink.emit({
+            kind: 'query_end',
+            specId: spec.id,
+            sqlFile: spec.sqlFile,
+            execId,
+            attempt,
+            timeMs: now,
+            attributes: spec.tags,
+            durationMs: Math.max(now - baseStartTime, 0),
+            rowCount,
+        });
+    }
+    function emitQueryErrorEvent(spec, execId, attempt, baseStartTime, error) {
+        if (!sink) {
+            return;
+        }
+        const now = Date.now();
+        sink.emit({
+            kind: 'query_error',
+            specId: spec.id,
+            sqlFile: spec.sqlFile,
+            execId,
+            attempt,
+            timeMs: now,
+            attributes: spec.tags,
+            durationMs: Math.max(now - baseStartTime, 0),
+            errorKind: getErrorKind(error),
+            errorMessage: error instanceof Error ? error.message : String(error !== null && error !== void 0 ? error : 'unknown'),
+        });
+    }
+    async function executeRows(spec, params, executionOptions, execId, attempt) {
+        const validatedParams = assertParamsShape(spec.id, spec.params.shape, params);
+        const sql = await loadSql(spec);
+        const rewritten = applyRewriters(spec, sql, validatedParams, executionOptions);
+        const rewrittenParams = assertParamsShape(spec.id, spec.params.shape, rewritten.params);
+        assertNamedAllowed(spec, binders, allowNamedWithoutBinder);
+        const bound = applyBinders(spec, rewritten.sql, rewrittenParams);
+        const paramsShape = describeParamsShape(bound.params);
+        const snapshot = {
+            sql: bound.sql,
+            params: bound.params,
+            paramsShape,
+            startTime: Date.now(),
+        };
+        emitQueryStartEvent(spec, execId, attempt, snapshot);
+        try {
+            const rows = await options.executor(bound.sql, bound.params);
+            return { rows, snapshot };
+        }
+        catch (cause) {
+            throw new CatalogExecutionError(`Query executor failed while processing catalog spec "${spec.id}".`, spec.id, cause);
+        }
+    }
+    function createPipelineExec(spec, finalize) {
+        return async (input) => {
+            var _a, _b;
+            const invocationStart = Date.now();
+            let snapshot;
+            try {
+                const { rows, snapshot: rowSnapshot } = await executeRows(spec, input.params, input.options, input.execId, input.attempt);
+                snapshot = rowSnapshot;
+                const value = finalize(rows);
+                const durationBase = (_a = snapshot === null || snapshot === void 0 ? void 0 : snapshot.startTime) !== null && _a !== void 0 ? _a : invocationStart;
+                // durationMs reflects the executor round-trip after loading/rewriting/binding SQL.
+                emitQueryEndEvent(spec, input.execId, input.attempt, durationBase, rows.length);
+                return { value, rowCount: rows.length };
+            }
+            catch (error) {
+                const durationBase = (_b = snapshot === null || snapshot === void 0 ? void 0 : snapshot.startTime) !== null && _b !== void 0 ? _b : invocationStart;
+                emitQueryErrorEvent(spec, input.execId, input.attempt, durationBase, error);
+                throw error;
+            }
+        };
+    }
+    function wrapWithExtensions(core) {
+        return extensions.reduceRight((next, extension) => extension.wrap(next), core);
+    }
+    function applyOutputTransformation(spec, rows) {
+        const mappedRows = spec.output.mapping
+            ? (0, mapper_1.mapRows)(rows, spec.output.mapping)
+            : rows;
+        const decode = spec.output.validate;
+        if (!decode) {
+            return mappedRows;
+        }
+        // The decoder/validator runs after mapping so it receives the mapped DTO.
+        return mappedRows.map((value) => decode(value));
+    }
+    function expectExactlyOneRow(rows, specId) {
+        if (rows.length === 0) {
+            throw new ContractViolationError('Expected exactly one row but received none.', specId);
+        }
+        if (rows.length > 1) {
+            throw new ContractViolationError(`Expected exactly one row but received ${rows.length}.`, specId);
+        }
+        return rows[0];
+    }
+    function extractScalar(rows, specId) {
+        const row = expectExactlyOneRow(rows, specId);
+        const columns = Object.keys(row);
+        if (columns.length !== 1) {
+            throw new ContractViolationError(`Expected exactly one column but received ${columns.length}.`, specId);
+        }
+        return row[columns[0]];
+    }
+    function applyScalarResult(spec, value) {
+        const decode = spec.output.validate;
+        if (decode) {
+            // The decoder/validator runs against the extracted scalar value.
+            return decode(value);
+        }
+        return value;
+    }
+    return {
+        async list(spec, params, options) {
+            const exec = wrapWithExtensions(createPipelineExec(spec, (rows) => applyOutputTransformation(spec, rows)));
+            const execId = createExecId();
+            const attempt = 1;
+            const result = await exec({
+                specId: spec.id,
+                sqlFile: spec.sqlFile,
+                params,
+                options,
+                execId,
+                attempt,
+            });
+            return result.value;
+        },
+        async one(spec, params, options) {
+            const exec = wrapWithExtensions(createPipelineExec(spec, (rows) => expectExactlyOneRow(applyOutputTransformation(spec, rows), spec.id)));
+            const execId = createExecId();
+            const attempt = 1;
+            const result = await exec({
+                specId: spec.id,
+                sqlFile: spec.sqlFile,
+                params,
+                options,
+                execId,
+                attempt,
+            });
+            return result.value;
+        },
+        async scalar(spec, params, options) {
+            const exec = wrapWithExtensions(createPipelineExec(spec, (rows) => {
+                const value = extractScalar(rows, spec.id);
+                return applyScalarResult(spec, value);
+            }));
+            const execId = createExecId();
+            const attempt = 1;
+            const result = await exec({
+                specId: spec.id,
+                sqlFile: spec.sqlFile,
+                params,
+                options,
+                execId,
+                attempt,
+            });
+            return result.value;
+        },
+    };
+}
+/** Named parameters are forbidden unless a binder is configured or explicit allowance is granted. */
+function assertNamedAllowed(spec, binders, allow) {
+    if (spec.params.shape === 'named' && binders.length === 0 && !allow) {
+        throw new ContractViolationError(`Spec "${spec.id}" declares named parameters without a binder; enable allowNamedParamsWithoutBinder or add a binder.`, spec.id);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/catalog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
+export * from './catalog';
 export * from './mapper';
 export * from './writer';
+export * from './utils/coercions';

package/dist/index.js

@@ -14,6 +14,8 @@ 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("./catalog"), exports);
 __exportStar(require("./mapper"), exports);
 __exportStar(require("./writer"), exports);
+__exportStar(require("./utils/coercions"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAwB;AACxB,2CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAAyB;AACzB,2CAAwB;AACxB,2CAAwB;AACxB,oDAAiC"}

package/dist/mapper/index.d.ts

@@ -1,4 +1,5 @@
 import type { QueryParams } from '../query-params';
+import { normalizeKeyFromRow, normalizeKeyValue } from './internal';
 export type { QueryParams } from '../query-params';
 /**
  * A single database row returned by a SQL driver.
@@ -15,7 +16,7 @@ export type QueryExecutor = (sql: string, params: QueryParams) => Promise<Row[]>
 /**
  * Defines how a column prefix, key, and optional overrides describe a row mapping.
  */
-export interface RowMappingOptions<T, K extends Extract<keyof T, string>> {
+export interface RowMappingOptions<T, K extends RowMappingKey<T> = RowMappingKey<T>> {
     name: string;
     key: K;
     prefix?: string;
@@ -60,13 +61,52 @@ export interface MapperOptions {
         value: unknown;
     }) => unknown;
 }
+/** Primitive types that can appear in row keys. */
+export type KeyPrimitive = string | number | bigint;
+/** A key value: either a single primitive or an ordered list for composites. */
+export type KeyValue = KeyPrimitive | readonly KeyPrimitive[];
+/** Extracts a key value from a row. */
+export type KeyExtractor<T> = (row: T) => KeyValue;
+/**
+ * Describes how a row mapping derives its key.
+ * - A property name resolves via `resolveColumnName`.
+ * - An array lists explicit column names for composites.
+ * - A key extractor derives the key from a row object.
+ */
+export type RowMappingKey<T> = Extract<keyof T, string> | readonly string[] | KeyExtractor<T>;
 /**
  * A mapping-bound reader that executes SQL and enforces row-count contracts.
  */
 export interface MapperReader<T> {
     list(sql: string, params?: QueryParams): Promise<T[]>;
     one(sql: string, params?: QueryParams): Promise<T>;
+    scalar(sql: string, params?: QueryParams): Promise<unknown>;
+    validator<U>(validator: ReaderValidatorInput<T, U>): MapperReader<U>;
 }
+/**
+ * Validates a mapped value and returns the validated output.
+ */
+export type ReaderValidator<T, U = T> = (value: T) => U;
+/**
+ * Minimal schema-like contract recognized by reader validators.
+ * Implementations expose either `parse(value)` or `assert(value)` to describe
+ * the validated output type `U`.
+ */
+type ReaderParseLike<U> = {
+    parse(value: unknown): U;
+};
+type ReaderAssertLike<U> = {
+    assert(value: unknown): U;
+} | {
+    assert(value: unknown): asserts value is U;
+};
+export type ReaderSchemaLike<U = unknown> = ReaderParseLike<U> | ReaderAssertLike<U>;
+/**
+ * Input accepted by `MapperReader.validator`. The value may be a plain validator function,
+ * or any schema-like object that implements `parse(value): U`. `T` is the row-mapped input type
+ * and `U` is the validated output emitted by the reader.
+ */
+export type ReaderValidatorInput<T, U = T> = ReaderValidator<T, U> | ReaderSchemaLike<U>;
 /**
  * Named presets for simple mapping that avoid implicit inference.
  */
@@ -84,10 +124,7 @@ type RowContext = {
     row: Row;
     normalizedColumns: Map<string, string>;
 };
-/**
- * Builds a row mapping that can be consumed by {@link Mapper#query} or {@link mapRows}.
- */
-export declare class RowMapping<T, K extends Extract<keyof T, string> = Extract<keyof T, string>> {
+export declare class RowMapping<T, K extends RowMappingKey<T> = RowMappingKey<T>> {
     readonly name: string;
     readonly key: K;
     readonly prefix: string;
@@ -98,6 +135,9 @@ export declare class RowMapping<T, K extends Extract<keyof T, string> = Extract<
     private readonly prefixLength;
     private readonly shouldCoerce;
     private readonly coerceFn;
+    private readonly keyDescriptor;
+    private readonly keyExtractor;
+    private readonly keyColumns?;
     constructor(options: RowMappingOptions<T, K>);
     /**
      * Registers a parent relationship that will be attached after the current row is mapped.
@@ -113,19 +153,28 @@ export declare class RowMapping<T, K extends Extract<keyof T, string> = Extract<
     belongsToOptional<P, PK extends Extract<keyof P, string>>(propertyName: Extract<keyof T, string>, parent: RowMapping<P, PK>, localKey?: Extract<keyof T, string>): this;
     matchColumn(columnName: string): string | undefined;
     resolveColumnName(propertyName: string): string;
-    readKeyValue(ctx: RowContext): unknown;
+    readKeyValue(ctx: RowContext): KeyValue | undefined;
+    /**
+     * Returns a human-readable description of the key for error reporting.
+     */
+    get keyDescription(): string;
+    /**
+     * Lists the resolved key column names, if the key is not derived.
+     */
+    get keyColumnNames(): readonly string[] | undefined;
     assignFields(target: Record<string, unknown>, ctx: RowContext): void;
     private normalizeColumnValue;
+    private buildMappedRowForKey;
 }
 export { RowMapping as EntityMapping };
 /**
  * Creates a new row mapping from the provided options.
  */
-export declare function rowMapping<T, K extends Extract<keyof T, string> = Extract<keyof T, string>>(options: RowMappingOptions<T, K>): RowMapping<T, K>;
+export declare function rowMapping<T, K extends RowMappingKey<T> = RowMappingKey<T>>(options: RowMappingOptions<T, K>): RowMapping<T, K>;
 /**
  * @deprecated Use {@link rowMapping} instead.
  */
-export declare function entity<T, K extends Extract<keyof T, string> = Extract<keyof T, string>>(options: RowMappingOptions<T, K>): RowMapping<T, K>;
+export declare function entity<T, K extends RowMappingKey<T> = RowMappingKey<T>>(options: RowMappingOptions<T, K>): RowMapping<T, K>;
 /**
  * Builds a column map by prefixing each property with the provided prefix and
  * converting property names to snake_case.
@@ -190,3 +239,7 @@ export declare function mapRows<T>(rows: Row[], mapping: RowMapping<T>): T[];
  * @returns An array of `T` instances synthesized from `rows`.
  */
 export declare function mapSimpleRows<T>(rows: Row[], options?: MapperOptions): T[];
+export declare const __internal: {
+    normalizeKeyValue: typeof normalizeKeyValue;
+    normalizeKeyFromRow: typeof normalizeKeyFromRow;
+};