@sqlbraid/core 0.1.0-rc.0 → 1.0.0-rc.1

package/dist/index.js

@@ -1,16 +1,402 @@
+//#region src/authoring-modules.ts
+const AUTHORING_MODULE_CATALOG = Object.freeze([
+	{
+		moduleSpecifier: "@sqlbraid/template",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/postgres",
+		dialectId: "postgres",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/mysql",
+		dialectId: "mysql",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/mariadb",
+		dialectId: "mariadb",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/sqlite",
+		dialectId: "sqlite",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/oracle",
+		dialectId: "oracle",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "@sqlbraid/mssql",
+		dialectId: "mssql",
+		helperFamily: "template"
+	},
+	{
+		moduleSpecifier: "sqlbraid/pg",
+		dialectId: "postgres",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/mysql2",
+		dialectId: "mysql",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/mariadb",
+		dialectId: "mariadb",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/node-sqlite",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/better-sqlite3",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/libsql",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/sqlite-wasm",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/d1",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/oracledb",
+		dialectId: "oracle",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/tedious",
+		dialectId: "mssql",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/postgres",
+		dialectId: "postgres",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/mysql",
+		dialectId: "mysql",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/sqlite",
+		dialectId: "sqlite",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/oracle",
+		dialectId: "oracle",
+		helperFamily: "facade"
+	},
+	{
+		moduleSpecifier: "sqlbraid/mssql",
+		dialectId: "mssql",
+		helperFamily: "facade"
+	}
+].map((entry) => Object.freeze(entry)));
+
+//#endregion
 //#region src/index.ts
 const SQL_FRAGMENT = Symbol.for("sqlbraid.fragment");
 const SQL_BOUND_PARAMETER = Symbol.for("sqlbraid.bound-parameter");
 const knownBoundParameters = /* @__PURE__ */ new WeakSet();
 const SQL_ROUTINE_PARAMETER = Symbol.for("sqlbraid.routine-parameter");
 const knownRoutineParameters = /* @__PURE__ */ new WeakSet();
-var ResultExactnessError = class extends Error {
-	code = "BRAID_RESULT_EXACTNESS";
+var ResultExactnessError = class ResultExactnessError extends Error {
+	static {
+		this.code = "BRAID_RESULT_EXACTNESS";
+	}
 	constructor(message = "Result value does not have an exact representation.") {
 		super(message);
+		this.code = ResultExactnessError.code;
 		this.name = "ResultExactnessError";
 	}
 };
+/**
+* The intentionally small compatibility boundary for SQLBraid-owned errors.
+*
+* Keep this registry explicit.  In particular, a BRAID_ token in a driver
+* message or an internal compiler fallback is not public merely because it
+* happens to use the project prefix.
+*/
+const PUBLIC_ERROR_DEFINITIONS = Object.freeze([
+	{
+		code: "BRAID_RESULT_EXACTNESS",
+		category: "runtime",
+		owner: "ResultExactnessError"
+	},
+	{
+		code: "BRAID_CALL_MAP",
+		category: "runtime",
+		owner: "RoutineMappingError"
+	},
+	{
+		code: "BRAID_RESULT_KIND",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseResultKindError"
+	},
+	{
+		code: "BRAID_RESULT_VALIDATION",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseResultValidationError"
+	},
+	{
+		code: "BRAID_BATCH_ABORTED",
+		category: "runtime",
+		owner: "runtime batch lifecycle/synthetic observer error"
+	},
+	{
+		code: "BRAID_TX_SCOPE",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_TX_CLOSED",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_SESSION_SCOPE",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_SESSION_CLOSED",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_CONNECTION_POISONED",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_STREAM_SCOPE",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_REENTRY",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_TX_OPTIONS_NESTED",
+		category: "runtime",
+		owner: "@sqlbraid/runtime:DatabaseScopeError"
+	},
+	{
+		code: "BRAID_CALL_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_RESULT_SETS_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_STREAM_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CANCEL_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_SESSION_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_TX_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_TX_OPTIONS_INVALID",
+		category: "runtime",
+		owner: "TypeError with code"
+	},
+	{
+		code: "BRAID_TX_OPTION_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_RESULT_SETS",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_CURSOR_TX_REQUIRED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_OUT_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_RETURN_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_CURSOR_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_RESOURCE_CLEANUP",
+		category: "adapter",
+		owner: "adapter cleanup error with code"
+	},
+	{
+		code: "BRAID_BIND_HINT_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_BIND_VALUE_UNSUPPORTED",
+		category: "adapter",
+		owner: "AdapterError"
+	},
+	{
+		code: "BRAID_INTEGER_MODE_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_CALL_LOB_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_BULK_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_DIALECT_MISMATCH",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_RESULT_KIND_AMBIGUOUS",
+		category: "adapter",
+		owner: "UnsupportedFeatureError"
+	},
+	{
+		code: "BRAID_PREPARED_NAME",
+		category: "runtime",
+		owner: "prepared query validation"
+	},
+	{
+		code: "BRAID_PREPARED_SHAPE",
+		category: "runtime",
+		owner: "prepared query validation"
+	},
+	{
+		code: "BRAID_BIND_TYPE_REQUIRED",
+		category: "adapter",
+		owner: "AdapterError"
+	},
+	{
+		code: "BRAID_EMPTY_LIST",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_EMPTY_SET",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_DIALECT",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_ASYNC_CONTEXT",
+		category: "compiler",
+		owner: "compiler diagnostic"
+	},
+	{
+		code: "BRAID_DIRECTIVE_UNTERMINATED",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_DIRECTIVE",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_CONDITION",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_ATTRIBUTES",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_STRUCTURE",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_HOLE_CONTEXT",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_SQL_LEX",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_DEPTH",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_STRUCTURE_LIMIT",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_SQL_LIMIT",
+		category: "runtime",
+		owner: "SqlRenderError"
+	},
+	{
+		code: "BRAID_BIND_LIMIT",
+		category: "runtime",
+		owner: "SqlRenderError"
+	}
+]);
 function exactnessFailure(message) {
 	throw new ResultExactnessError(message);
 }
@@ -197,6 +583,23 @@ function copyRoutineProcedure(procedure) {
 		parameterNames: Object.freeze(parameterNames)
 	});
 }
+function copyNativeTemplate(value, segments) {
+	if (!Array.isArray(value) || value.length !== segments.length) throw new TypeError("RenderedStatement nativeTemplate must have one string per segment boundary.");
+	if (value.some((segment) => typeof segment !== "string")) throw new TypeError("RenderedStatement nativeTemplate must contain cooked strings.");
+	if (value.some((segment, index) => segment !== segments[index])) throw new TypeError("RenderedStatement nativeTemplate cooked strings must match logical segments.");
+	const raw = value.raw;
+	if (!Array.isArray(raw) || raw.length !== value.length || raw.some((segment) => typeof segment !== "string")) throw new TypeError("RenderedStatement nativeTemplate.raw must contain one raw string per segment boundary.");
+	if (Object.isFrozen(value) && Object.isFrozen(raw)) return value;
+	const cooked = [...value];
+	const frozenRaw = Object.freeze([...raw]);
+	Object.defineProperty(cooked, "raw", {
+		configurable: false,
+		enumerable: false,
+		value: frozenRaw,
+		writable: false
+	});
+	return Object.freeze(cooked);
+}
 function createRenderedStatement(statement) {
 	if (typeof statement !== "object" || statement === null) throw new TypeError("RenderedStatement must be an object.");
 	if (knownRenderedStatements.has(statement)) return statement;
@@ -207,6 +610,7 @@ function createRenderedStatement(statement) {
 	if (typeof statement.dialectId !== "string" || !statement.dialectId) throw new TypeError("RenderedStatement dialectId must be a non-empty string.");
 	const segments = Object.freeze([...statement.segments]);
 	if (segments.some((segment) => typeof segment !== "string")) throw new TypeError("RenderedStatement segments must be an array of strings.");
+	const nativeTemplate = statement.nativeTemplate === void 0 ? void 0 : copyNativeTemplate(statement.nativeTemplate, segments);
 	const parameters = Object.freeze(Array.from(statement.parameters, copyRenderedParameter));
 	if (parameters.some((parameter) => parameter.direction === "inout" && statement.resultKind !== "call")) throw new TypeError("INOUT parameters are only valid for call statements.");
 	if (parameters.some((parameter) => parameter.direction === "out" && statement.resultKind !== "call" && statement.resultKind !== "rows")) throw new TypeError("OUT parameters are only valid for call and rows statements.");
@@ -220,6 +624,7 @@ function createRenderedStatement(statement) {
 	const rendered = Object.freeze({
 		segments,
 		parameters,
+		...nativeTemplate === void 0 ? {} : { nativeTemplate },
 		dialectId: statement.dialectId,
 		resultKind: statement.resultKind,
 		...routineProcedure === void 0 ? {} : { routineProcedure },
@@ -443,8 +848,6 @@ function createBulkBindingDescription(bulk, context, options) {
 	return Object.freeze(description);
 }
 var UnsupportedFeatureError = class extends Error {
-	feature;
-	code;
 	constructor(feature, code, message, options) {
 		super(`${code}: ${message}`, options);
 		this.feature = feature;
@@ -452,17 +855,26 @@ var UnsupportedFeatureError = class extends Error {
 		this.name = "UnsupportedFeatureError";
 	}
 };
-var RoutineMappingError = class extends Error {
-	code = "BRAID_CALL_MAP";
-	location;
+/** An adapter-owned input/transport failure that retains TypeError semantics. */
+var AdapterError = class extends TypeError {
+	constructor(code, message, options) {
+		super(`${code}: ${message}`, options);
+		this.code = code;
+		this.name = "AdapterError";
+	}
+};
+var RoutineMappingError = class RoutineMappingError extends Error {
+	static {
+		this.code = "BRAID_CALL_MAP";
+	}
 	constructor(message, location, options) {
 		super(message, options);
+		this.code = RoutineMappingError.code;
 		this.name = "RoutineMappingError";
 		this.location = Object.freeze(location);
 	}
 };
 var SqlRenderError = class extends Error {
-	code;
 	constructor(code, message) {
 		super(message);
 		this.name = "SqlRenderError";
@@ -471,5 +883,5 @@ var SqlRenderError = class extends Error {
 };
 
 //#endregion
-export { ResultExactnessError, RoutineMappingError, SQL_FRAGMENT, SqlRenderError, UnsupportedFeatureError, createBoundParameter, createBulkBindingDescription, createParameterTypeHint, createRenderedBulk, createRenderedStatement, createRoutineInOutParameter, createRoutineOutParameter, createStatementBindingDescription, decodeExactDecimal, decodeExactInteger, isBoundParameter, isRoutineParameter, normalizeExactInteger, parameterizedSql, safeDatabaseCount };
+export { AUTHORING_MODULE_CATALOG, AdapterError, PUBLIC_ERROR_DEFINITIONS, ResultExactnessError, RoutineMappingError, SQL_FRAGMENT, SqlRenderError, UnsupportedFeatureError, createBoundParameter, createBulkBindingDescription, createParameterTypeHint, createRenderedBulk, createRenderedStatement, createRoutineInOutParameter, createRoutineOutParameter, createStatementBindingDescription, decodeExactDecimal, decodeExactInteger, isBoundParameter, isRoutineParameter, normalizeExactInteger, parameterizedSql, safeDatabaseCount };
 //# sourceMappingURL=index.js.map