@sqlbraid/core 0.1.0-rc.1 → 1.0.0

package/dist/index.js

@@ -1,16 +1,668 @@
+//#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/capabilities.ts
+const definitions = [
+	{
+		id: "sql.native-transparency",
+		family: "support"
+	},
+	{
+		id: "sql.generated-structure",
+		family: "support"
+	},
+	{
+		id: "result.rows",
+		family: "support"
+	},
+	{
+		id: "result.command",
+		family: "support"
+	},
+	{
+		id: "result.multiple-sets",
+		family: "support"
+	},
+	{
+		id: "result.standard-schema",
+		family: "support"
+	},
+	{
+		id: "numeric.exact-integer",
+		family: "representation"
+	},
+	{
+		id: "numeric.exact-decimal",
+		family: "representation"
+	},
+	{
+		id: "numeric.approximate-float",
+		family: "representation"
+	},
+	{
+		id: "numeric.approximate-special",
+		family: "representation"
+	},
+	{
+		id: "numeric.bind-exact",
+		family: "representation"
+	},
+	{
+		id: "numeric.aggregate",
+		family: "representation"
+	},
+	{
+		id: "numeric.command-metadata",
+		family: "representation"
+	},
+	{
+		id: "numeric.special-values",
+		family: "representation"
+	},
+	{
+		id: "numeric.scale-greater-than-precision",
+		family: "representation"
+	},
+	{
+		id: "numeric.negative-scale",
+		family: "representation"
+	},
+	{
+		id: "data.json-parsed",
+		family: "representation"
+	},
+	{
+		id: "data.json-lossless-text",
+		family: "representation"
+	},
+	{
+		id: "data.sql-variant",
+		family: "representation"
+	},
+	{
+		id: "data.oracle-object",
+		family: "representation"
+	},
+	{
+		id: "data.oracle-collection",
+		family: "representation"
+	},
+	{
+		id: "data.vector",
+		family: "representation"
+	},
+	{
+		id: "data.binary",
+		family: "representation"
+	},
+	{
+		id: "data.uuid",
+		family: "representation"
+	},
+	{
+		id: "data.temporal-native",
+		family: "representation"
+	},
+	{
+		id: "data.temporal-lossless",
+		family: "representation"
+	},
+	{
+		id: "data.timezone",
+		family: "representation"
+	},
+	{
+		id: "metadata.command-safe",
+		family: "metadata"
+	},
+	{
+		id: "dml.insert-returning",
+		family: "support"
+	},
+	{
+		id: "dml.update-returning",
+		family: "support"
+	},
+	{
+		id: "dml.delete-returning",
+		family: "support"
+	},
+	{
+		id: "dml.merge-returning",
+		family: "support"
+	},
+	{
+		id: "dml.upsert-returning",
+		family: "support"
+	},
+	{
+		id: "session.pinned",
+		family: "support"
+	},
+	{
+		id: "statement.prepare",
+		family: "support"
+	},
+	{
+		id: "statement.cancel",
+		family: "support"
+	},
+	{
+		id: "statement.stream",
+		family: "support"
+	},
+	{
+		id: "statement.bulk",
+		family: "support"
+	},
+	{
+		id: "execution.bulk-fidelity",
+		family: "support"
+	},
+	{
+		id: "transaction",
+		family: "support"
+	},
+	{
+		id: "transaction.savepoint",
+		family: "support"
+	},
+	{
+		id: "transaction.read-only",
+		family: "support"
+	},
+	{
+		id: "transaction.isolation.read-uncommitted",
+		family: "support"
+	},
+	{
+		id: "transaction.isolation.read-committed",
+		family: "support"
+	},
+	{
+		id: "transaction.isolation.repeatable-read",
+		family: "support"
+	},
+	{
+		id: "transaction.isolation.serializable",
+		family: "support"
+	},
+	{
+		id: "routine.call",
+		family: "support"
+	},
+	{
+		id: "routine.out",
+		family: "support"
+	},
+	{
+		id: "routine.inout",
+		family: "support"
+	},
+	{
+		id: "routine.result-sets",
+		family: "support"
+	},
+	{
+		id: "routine.out-cursor",
+		family: "support"
+	},
+	{
+		id: "routine.return-value",
+		family: "support"
+	},
+	{
+		id: "metadata.identity",
+		family: "metadata"
+	},
+	{
+		id: "metadata.generated",
+		family: "metadata"
+	},
+	{
+		id: "metadata.routines",
+		family: "metadata"
+	},
+	{
+		id: "metadata.types",
+		family: "metadata"
+	}
+];
+const WELL_KNOWN_CAPABILITIES = Object.freeze(definitions.map((entry) => Object.freeze(entry)));
+const WELL_KNOWN_CAPABILITY_IDS = Object.freeze(definitions.map(({ id }) => id));
+const wellKnownCapabilityIds = new Set(WELL_KNOWN_CAPABILITY_IDS);
+function isWellKnownCapabilityId(value) {
+	return wellKnownCapabilityIds.has(value);
+}
+
+//#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",
+		features: ["routine.call"]
+	},
+	{
+		code: "BRAID_RESULT_SETS_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.result-sets"]
+	},
+	{
+		code: "BRAID_STREAM_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["statement.stream"]
+	},
+	{
+		code: "BRAID_CANCEL_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["statement.cancel"]
+	},
+	{
+		code: "BRAID_SESSION_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["session.pinned"]
+	},
+	{
+		code: "BRAID_TX_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["transaction", "transaction.savepoint"]
+	},
+	{
+		code: "BRAID_TX_OPTIONS_INVALID",
+		category: "runtime",
+		owner: "TypeError with code"
+	},
+	{
+		code: "BRAID_TX_OPTION_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: [
+			"transaction.read-only",
+			"transaction.isolation.read-uncommitted",
+			"transaction.isolation.read-committed",
+			"transaction.isolation.repeatable-read",
+			"transaction.isolation.serializable"
+		]
+	},
+	{
+		code: "BRAID_CALL_RESULT_SETS",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.result-sets"]
+	},
+	{
+		code: "BRAID_CALL_CURSOR_TX_REQUIRED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.out-cursor"]
+	},
+	{
+		code: "BRAID_CALL_OUT_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.out", "routine.inout"]
+	},
+	{
+		code: "BRAID_CALL_RETURN_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.call", "routine.return-value"]
+	},
+	{
+		code: "BRAID_CALL_CURSOR_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.out-cursor"]
+	},
+	{
+		code: "BRAID_RESOURCE_CLEANUP",
+		category: "adapter",
+		owner: "adapter cleanup error with code",
+		features: ["resource.cleanup", "resource.discard"]
+	},
+	{
+		code: "BRAID_BIND_HINT_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["statement.bind-hint"]
+	},
+	{
+		code: "BRAID_BIND_VALUE_UNSUPPORTED",
+		category: "adapter",
+		owner: "AdapterError"
+	},
+	{
+		code: "BRAID_INTEGER_MODE_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["result.exact-integer"]
+	},
+	{
+		code: "BRAID_CALL_LOB_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["routine.out"]
+	},
+	{
+		code: "BRAID_BULK_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["statement.bulk"]
+	},
+	{
+		code: "BRAID_PREPARE_UNSUPPORTED",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["statement.prepare"]
+	},
+	{
+		code: "BRAID_DIALECT_MISMATCH",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["dialect"]
+	},
+	{
+		code: "BRAID_RESULT_KIND_AMBIGUOUS",
+		category: "adapter",
+		owner: "UnsupportedFeatureError",
+		features: ["result.rows", "result.command"]
+	},
+	{
+		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);
 }
@@ -257,7 +909,10 @@ function genericLiteral(parameter, dialectId, binary) {
 	const value = parameter.value;
 	if (value === null) return "NULL";
 	if (value === void 0) return "[undefined]";
-	if (typeof value === "string") return `'${value.replaceAll("'", "''")}'`;
+	if (typeof value === "string") {
+		if (/^(?:mysql|mariadb)/i.test(dialectId)) return `[string ${JSON.stringify(value)}]`;
+		return `'${value.replaceAll("'", "''")}'`;
+	}
 	if (typeof value === "boolean") {
 		if (/^(?:mysql|sqlite)/i.test(dialectId) || /^(?:oracle|mssql|sqlserver)/i.test(dialectId)) return value ? "1" : "0";
 		if (/^(?:postgres|postgresql|cockroach|redshift)/i.test(dialectId)) return value ? "TRUE" : "FALSE";
@@ -462,8 +1117,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;
@@ -471,17 +1124,31 @@ var UnsupportedFeatureError = class extends Error {
 		this.name = "UnsupportedFeatureError";
 	}
 };
-var RoutineMappingError = class extends Error {
-	code = "BRAID_CALL_MAP";
-	location;
+/** Return true only for a registered, semantically valid feature/code pair. */
+function isPublicUnsupportedFeatureError(error) {
+	if (!(error instanceof UnsupportedFeatureError)) return false;
+	return PUBLIC_ERROR_DEFINITIONS.find((candidate) => candidate.owner === "UnsupportedFeatureError" && candidate.code === error.code)?.features?.includes(error.feature) === true;
+}
+/** 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";
@@ -490,5 +1157,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, WELL_KNOWN_CAPABILITIES, WELL_KNOWN_CAPABILITY_IDS, createBoundParameter, createBulkBindingDescription, createParameterTypeHint, createRenderedBulk, createRenderedStatement, createRoutineInOutParameter, createRoutineOutParameter, createStatementBindingDescription, decodeExactDecimal, decodeExactInteger, isBoundParameter, isPublicUnsupportedFeatureError, isRoutineParameter, isWellKnownCapabilityId, normalizeExactInteger, parameterizedSql, safeDatabaseCount };
 //# sourceMappingURL=index.js.map