@rawsql-ts/sql-contract 0.1.0 → 0.2.0

package/dist/utils/coercions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Attempts to parse a numeric string into a JavaScript number while making the
+ * unsafe precision loss explicit in the API name.
+ *
+ * This helper leaves non-string values untouched so callers can safely run it
+ * over raw database output without branching on the column type themselves.
+ */
+export declare function decimalStringToNumberUnsafe(value: unknown): unknown;
+/**
+ * Coerces bigint-encoded strings into actual `bigint` values while avoiding
+ * falsy or empty strings.
+ */
+export declare function bigintStringToBigInt(value: unknown): unknown;
+/**
+ * Normalizes timestamp values returned by SQL drivers into a valid `Date`.
+ *
+ * Accepts `Date` instances and parseable timestamp strings.
+ * Throws for invalid dates, empty strings, or unsupported value types.
+ */
+export declare function timestampFromDriver(value: unknown, fieldName?: string): Date;

package/dist/utils/coercions.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decimalStringToNumberUnsafe = decimalStringToNumberUnsafe;
+exports.bigintStringToBigInt = bigintStringToBigInt;
+exports.timestampFromDriver = timestampFromDriver;
+/**
+ * Attempts to parse a numeric string into a JavaScript number while making the
+ * unsafe precision loss explicit in the API name.
+ *
+ * This helper leaves non-string values untouched so callers can safely run it
+ * over raw database output without branching on the column type themselves.
+ */
+function decimalStringToNumberUnsafe(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return value;
+        }
+        const parsed = Number(trimmed);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return value;
+}
+/**
+ * Coerces bigint-encoded strings into actual `bigint` values while avoiding
+ * falsy or empty strings.
+ */
+function bigintStringToBigInt(value) {
+    if (typeof value === 'bigint') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed) {
+            try {
+                return BigInt(trimmed);
+            }
+            catch {
+                return value;
+            }
+        }
+    }
+    return value;
+}
+/**
+ * Normalizes timestamp values returned by SQL drivers into a valid `Date`.
+ *
+ * Accepts `Date` instances and parseable timestamp strings.
+ * Throws for invalid dates, empty strings, or unsupported value types.
+ */
+function timestampFromDriver(value, fieldName) {
+    const fieldLabel = (fieldName === null || fieldName === void 0 ? void 0 : fieldName.trim()) ? ` for "${fieldName}"` : '';
+    // Preserve valid Date instances while rejecting "Invalid Date".
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new Error(`Invalid Date value${fieldLabel}.`);
+        }
+        return value;
+    }
+    // Parse driver-returned timestamp strings after trimming transport whitespace.
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            throw new Error(`Expected a non-empty timestamp string${fieldLabel}.`);
+        }
+        const timestamp = Date.parse(trimmed);
+        if (Number.isNaN(timestamp)) {
+            throw new Error(`Invalid timestamp string${fieldLabel}: "${value}".`);
+        }
+        return new Date(timestamp);
+    }
+    const actualType = value === null ? 'null' : typeof value;
+    throw new Error(`Expected Date or timestamp string${fieldLabel}, received ${actualType}.`);
+}
+//# sourceMappingURL=coercions.js.map

package/dist/utils/coercions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coercions.js","sourceRoot":"","sources":["../../src/utils/coercions.ts"],"names":[],"mappings":";;AAOA,kEAeC;AAMD,oDAeC;AAQD,kDA+BC;AAlFD;;;;;;GAMG;AACH,SAAgB,2BAA2B,CAAC,KAAc;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,KAAK,CAAA;QACd,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;QAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,MAAM,CAAA;QACf,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;QAC5B,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAA;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,KAAc,EAAE,SAAkB;IACpE,MAAM,UAAU,GAAG,CAAA,SAAS,aAAT,SAAS,uBAAT,SAAS,CAAE,IAAI,EAAE,EAAC,CAAC,CAAC,SAAS,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAEjE,gEAAgE;IAChE,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,qBAAqB,UAAU,GAAG,CAAC,CAAA;QACrD,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,+EAA+E;IAC/E,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,UAAU,GAAG,CAAC,CAAA;QACxE,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrC,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,2BAA2B,UAAU,MAAM,KAAK,IAAI,CACrD,CAAA;QACH,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5B,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,CAAA;IACzD,MAAM,IAAI,KAAK,CACb,oCAAoC,UAAU,cAAc,UAAU,GAAG,CAC1E,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rawsql-ts/sql-contract",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight mapper and writer helpers that keep client SQL authoritative while exposing an explicit contract for data hydration and CUD emitters.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,14 @@
       "types": "./dist/mapper/*.d.ts",
       "default": "./dist/mapper/*.js"
     },
+    "./utils/coercions": {
+      "types": "./dist/utils/coercions.d.ts",
+      "default": "./dist/utils/coercions.js"
+    },
+    "./utils/*": {
+      "types": "./dist/utils/*.d.ts",
+      "default": "./dist/utils/*.js"
+    },
     "./writer": {
       "types": "./dist/writer/index.d.ts",
       "default": "./dist/writer/index.js"
@@ -47,6 +55,7 @@
     "node": ">=20"
   },
   "devDependencies": {
+    "zod": "^4.3.6",
     "typescript": "^5.8.2",
     "vitest": "^4.0.7",
     "pg-promise": "^12.0.0"
@@ -57,6 +66,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
+    "test:integration": "vitest run --config ../../vitest.integration.config.ts",
     "test:watch": "vitest",
     "lint": "eslint src --ext .ts"
   }