@lakeql/response-transformer 0.1.7 → 1.0.0

package/dist/index.d.mts

@@ -1,163 +1,136 @@
-//#region src/types.d.ts
+import { AdapterName } from "@lakeql/datasource";
 /**
- * Primitive type
- * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ * Adapter-neutral, schema-aware transformation for keyed raw records.
+ *
+ * Runs after an adapter's `ResponseNormalizer` has decoded the wire protocol
+ * into keyed records. Walks each record against a schema, converting nested
+ * objects and arrays, applying field mapping, and normalizing null-ish scalar
+ * values. It never branches on adapter names and never decodes date/timestamp
+ * or timezone information — that stays adapter-owned in the normalizer.
+ *
+ * @module
  */
-type JSONSchema7TypeName = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
 /**
- * Primitive type
- * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ * Minimal JSON-Schema subset interpreted by {@link transformRecords}.
+ */
+interface TransformSchema {
+  /** JSON-Schema type. Only `"object"` and `"array"` trigger recursion. */
+  type?: string;
+  /** Property schemas for `"object"` types, keyed by SOURCE field name. */
+  properties?: Record<string, TransformSchema>;
+  /** Item schema for `"array"` types. */
+  items?: TransformSchema;
+}
+/**
+ * Input for {@link transformRecords}.
  */
-type JSONSchema7Type = string | number | boolean | JSONSchema7Object | JSONSchema7Array | null;
-interface JSONSchema7Object {
-  [key: string]: JSONSchema7Type;
+interface TransformRecordsInput {
+  /** Already-keyed records produced by an adapter normalizer. */
+  records: readonly Record<string, unknown>[];
+  /** Schema used to interpret nested object/array fields. */
+  schema: TransformSchema;
+  /**
+   * Field renaming, direction SOURCE key → TARGET key.
+   *
+   * Top-level fields are typically already renamed by the query dialect via
+   * SQL aliases, so this mapping is primarily relevant for fields nested
+   * inside object/array structures where SQL aliases cannot reach.
+   */
+  fieldMapping?: Readonly<Record<string, string>>;
 }
-type JSONSchema7Array = JSONSchema7Type[];
 /**
- * Meta schema
+ * Transforms keyed raw records against a schema.
  *
- * Recommended values:
- * - 'http://json-schema.org/schema#'
- * - 'http://json-schema.org/hyper-schema#'
- * - 'http://json-schema.org/draft-07/schema#'
- * - 'http://json-schema.org/draft-07/hyper-schema#'
+ * @param input - Records, schema, and optional field mapping.
+ * @returns A new array of transformed records.
+ */
+export declare function transformRecords(input: TransformRecordsInput): Record<string, unknown>[];
+/**
+ * Neutral input shape consumed by {@link ResponseNormalizer.normalize}.
  *
- * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+ * Contains the raw query response rows and metadata needed to convert
+ * backend-specific values into the shared {@link NormalizedResponse} shape.
  */
-type JSONSchema7Version = string;
+interface ResponseNormalizationInput {
+  /** Raw rows returned by the data source query. */
+  response: readonly unknown[];
+  /** Field names selected by the caller. */
+  selectFields: readonly string[];
+  /** Mapping from source field names to target field names. */
+  transformFields: Readonly<Record<string, string>>;
+  /** Field names that carry date/timestamp values. */
+  dateFields: readonly string[];
+  /** Backend-specific schema used for value interpretation. */
+  schema: unknown;
+}
 /**
- * JSON Schema v7
- * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+ * Result shape produced by {@link ResponseNormalizer.normalize}.
+ *
+ * @template T - Shape of each record in the returned data array.
  */
-type JSONSchema7Definition = JSONSchema7 | boolean;
-interface JSONSchema7 {
-  $id?: string | undefined;
-  $ref?: string | undefined;
-  $schema?: JSONSchema7Version | undefined;
-  $comment?: string | undefined;
-  /**
-   * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.2.4
-   * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#appendix-A
-   */
-  $defs?: Record<string, JSONSchema7Definition> | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
-   */
-  type?: JSONSchema7TypeName | JSONSchema7TypeName[] | undefined;
-  enum?: JSONSchema7Type[] | undefined;
-  const?: JSONSchema7Type | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
-   */
-  multipleOf?: number | undefined;
-  maximum?: number | undefined;
-  exclusiveMaximum?: number | undefined;
-  minimum?: number | undefined;
-  exclusiveMinimum?: number | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
-   */
-  maxLength?: number | undefined;
-  minLength?: number | undefined;
-  pattern?: string | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
-   */
-  items?: JSONSchema7Definition | JSONSchema7Definition[] | undefined;
-  additionalItems?: JSONSchema7Definition | undefined;
-  maxItems?: number | undefined;
-  minItems?: number | undefined;
-  uniqueItems?: boolean | undefined;
-  contains?: JSONSchema7Definition | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
-   */
-  maxProperties?: number | undefined;
-  minProperties?: number | undefined;
-  required?: string[] | undefined;
-  properties?: Record<string, JSONSchema7Definition> | undefined;
-  patternProperties?: Record<string, JSONSchema7Definition> | undefined;
-  additionalProperties?: JSONSchema7Definition | undefined;
-  dependencies?: Record<string, JSONSchema7Definition | string[]> | undefined;
-  propertyNames?: JSONSchema7Definition | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
-   */
-  if?: JSONSchema7Definition | undefined;
-  then?: JSONSchema7Definition | undefined;
-  else?: JSONSchema7Definition | undefined;
-  /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
-   */
-  allOf?: JSONSchema7Definition[] | undefined;
-  anyOf?: JSONSchema7Definition[] | undefined;
-  oneOf?: JSONSchema7Definition[] | undefined;
-  not?: JSONSchema7Definition | undefined;
+interface NormalizedResponse<T> {
+  /** Total number of records matching the query, before paging. */
+  totalCount: number;
+  /** Transformed records for the current page. */
+  data: T[];
+}
+/**
+ * Adapter-neutral contract for converting raw query response rows into a
+ * {@link NormalizedResponse}.
+ *
+ * Concrete adapters implement this interface to own backend-specific value
+ * conversion, schema interpretation, and total-count extraction. The shared
+ * SQL read strategy passes neutral input through unchanged and never branches
+ * on adapter names.
+ */
+interface ResponseNormalizer {
+  /** Open identifier of the adapter that owns this normalizer. */
+  readonly adapterName: AdapterName;
   /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
+   * Convert raw response rows into a normalized result.
+   *
+   * @template T - Shape of each record in the returned data array.
+   * @param input - Neutral normalization parameters.
+   * @returns Normalized response containing total count and typed data.
    */
-  format?: string | undefined;
+  normalize: <T>(input: ResponseNormalizationInput) => NormalizedResponse<T>;
+}
+/**
+ * Options for {@link createCteResponseNormalizer}.
+ */
+interface CteResponseNormalizerOptions {
+  /** Open identifier of the adapter that owns this normalizer. */
+  adapterName: AdapterName;
   /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-8
+   * Predicate deciding whether a non-null sentinel value marks a real data
+   * row. This is adapter-specific and MUST stay injected: Trino accepts only
+   * the boolean `true`, while Fabric's TDS driver returns `1`. Widening one
+   * adapter's predicate to the other's would change validation behavior.
    */
-  contentMediaType?: string | undefined;
-  contentEncoding?: string | undefined;
+  isPresentSentinel: (value: unknown) => boolean;
   /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-9
+   * Human-readable description of the accepted sentinel values, used in the
+   * error thrown for an invalid sentinel (e.g. `"true"` or `"true/1"`).
    */
-  definitions?: Record<string, JSONSchema7Definition> | undefined;
+  acceptedSentinelDescription: string;
   /**
-   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+   * Strict plain-object guard. Injected because each adapter already ships its
+   * own (identical) implementation; passing it keeps this package free of a
+   * dependency on either adapter's `sql-helpers`.
    */
-  title?: string | undefined;
-  description?: string | undefined;
-  default?: JSONSchema7Type | undefined;
-  readOnly?: boolean | undefined;
-  writeOnly?: boolean | undefined;
-  examples?: JSONSchema7Type | undefined;
-}
-//#endregion
-//#region src/index.d.ts
-interface TransformInput {
-  data: Record<string, unknown>;
-  definition: JSONSchema7;
-  transformFields?: Record<string, string>;
-  dateFields?: string[];
-  utcDates?: string[];
+  isPlainObject: (value: unknown) => boolean;
 }
-interface TransformArrayInput {
-  data: Record<string, unknown>[];
-  definition: JSONSchema7;
-  transformFields?: Record<string, string>;
-  dateFields?: string[];
-}
-declare const transform: ({ data, definition, transformFields, dateFields, utcDates }: TransformInput) => Record<string, unknown>;
-declare const transformArray: ({ data, definition, transformFields, dateFields }: TransformArrayInput) => Record<string, unknown>[];
-declare const transformObject: ({ data, definition, transformFields, dateFields }: TransformInput) => Record<string, unknown>;
 /**
- * Parameters for convertTrinoResponse.
- */
-interface ConvertTrinoResponseProps {
-  /** The field names to use as object keys. */
-  keys: string[];
-  /** The positional values from the Trino response row. */
-  values: unknown[];
-}
-/**
- * Converts the trino response element ( array of unknown ) to an object
- * based on the given keys. This function expects that
- * amount of keys matches the amount of value elements
+ * Creates a {@link ResponseNormalizer} for the shared CTE query shape.
+ *
+ * The returned normalizer extracts and validates `total_records`, drops the
+ * synthetic count-only row and the internal metadata columns, converts date
+ * fields from seconds to milliseconds, and preserves all other values. The
+ * only adapter-specific behavior is the sentinel predicate.
  *
- * @example
- *  const keys = ["fieldName1", "fieldName2"]
- *  const values = ["value1", 42]
- *  const convert = convertTrinoResponse({keys, values})
- *  // Result:
- *  //[{"fieldName1": "value1", "fieldName2": 42}]
- * @param keys string[]
- * @param values unknown[]
- * @returns Record<string, unknown>
+ * @param options - Adapter name, sentinel predicate and description, and the
+ *   plain-object guard.
+ * @returns A normalizer implementing the neutral {@link ResponseNormalizer}.
  */
-declare function convertTrinoResponse<T = Record<string, unknown>>({ keys, values }: ConvertTrinoResponseProps): T;
-//#endregion
-export { ConvertTrinoResponseProps, TransformArrayInput, TransformInput, convertTrinoResponse, transform, transformArray, transformObject };
+export declare function createCteResponseNormalizer(options: CteResponseNormalizerOptions): ResponseNormalizer;
+export type { CteResponseNormalizerOptions, NormalizedResponse, ResponseNormalizationInput, ResponseNormalizer, TransformRecordsInput, TransformSchema };

package/dist/index.mjs

@@ -1 +1 @@
-import{format as e}from"@formkit/tempo";const t=({data:t,definition:i,transformFields:a,dateFields:o=[],utcDates:s=[]})=>{let c={};for(let[l,u]of Object.entries(t)){let t=a?.[l]??l,d=i.properties?.[l];if(d){if(d.type!==`object`&&d.type!==`array`)if(o.includes(l)){let n=u&&u*1e3;s.includes(l)?c[t]=`${e({date:new Date(n),format:`YYYY-MM-DDTHH:mm:ss`,tz:`Europe/Berlin`})}Z`:c[t]=n}else c[t]=u??null;d.type===`object`&&(c[t]=r({data:u,dateFields:o,definition:d,transformFields:a})),d.type===`array`&&(c[t]=n({data:u,dateFields:o,definition:d.items,transformFields:a}))}}return c},n=({data:e,definition:t,transformFields:n,dateFields:i})=>t.type===`object`?e.map(e=>r({data:e,dateFields:i,definition:t,transformFields:n})):e,r=({data:e,definition:t,transformFields:i,dateFields:a=[]})=>{let o={},s=Object.keys(t.properties??{}),c=Array.isArray(e)?s.map((t,n)=>[t,e[n]]):s.map(e=>[e,null]),l={};for(let[e,t]of c)l[e]=t;let u=l;for(let e of s){let s=i?.[e]??e,c=t.properties?.[e];c&&(c.type!==`array`&&c.type!==`object`&&(a.includes(s)?o[s]=u[e]&&u[e]*1e3:o[s]=u[e]??null),c.type===`object`&&(o[s]=r({data:u[e],dateFields:a,definition:c.properties,transformFields:i})),c.type===`array`&&(o[s]=n({data:u[e],dateFields:a,definition:c.items,transformFields:i})))}return o};function i({keys:e,values:t}){let n=[];for(let[r,i]of t.entries())n.push([e[r],i]);return Object.fromEntries(n)}export{i as convertTrinoResponse,t as transform,n as transformArray,r as transformObject};
+function e(e){return e===`object`||e===`array`}function t(e,t,r){let i=t.properties??{},a={};for(let t of Object.keys(i)){let o=i[t];if(o===void 0)continue;let s=r[t]??t;a[s]=n(e[t],o,r)}return a}function n(r,i,a){if(i.type===`object`)return r==null?null:typeof r!=`object`||Array.isArray(r)?r:t(r,i,a);if(i.type===`array`){if(r==null)return null;if(!Array.isArray(r))return r;let t=i.items;return t===void 0||!e(t.type)?r:r.map(e=>n(e,t,a))}return r??null}function r(e){let{records:n,schema:r,fieldMapping:i={}}=e;return n.map(e=>t(e,r,i))}const i=`total_records`,a=`__lakeql_record_present`;function o(e){if(e==null)throw Error(`Malformed count metadata: total_records is absent or null`);if(typeof e!=`number`)throw TypeError(`Malformed count metadata: total_records must be a number, got ${typeof e}`);if(!Number.isFinite(e))throw TypeError(`Malformed count metadata: total_records must be finite, got ${String(e)}`);if(e<0)throw RangeError(`Malformed count metadata: total_records must be non-negative, got ${e}`);if(!Number.isInteger(e))throw TypeError(`Malformed count metadata: total_records must be an integer, got ${e}`);return e}function s(e,t){if(e===null)return null;if(typeof e!=`number`)throw TypeError(`Invalid date field "${t}": expected a finite number, got ${typeof e}`);if(!Number.isFinite(e))throw TypeError(`Invalid date field "${t}": expected a finite number, got ${String(e)}`);return e*1e3}function c(e,t,n){if(!n(e))throw Error(`Malformed adapter response: row at index ${t} must be a non-null plain object, got ${e===null?`null`:typeof e}`);return e}function l(e){let{adapterName:t,isPresentSentinel:n,acceptedSentinelDescription:r,isPlainObject:l}=e;return{adapterName:t,normalize(e){let{response:t,dateFields:u}=e;if(t.length===0)return{totalCount:0,data:[]};let d=o(c(t[0],0,l)[i]),f=new Set(u),p=[],m=0;for(let e of t){let t=c(e,m,l);m+=1;let o=t[a];if(o===null)continue;if(!n(o))throw Error(`Malformed adapter response: "${a}" must be ${r} for data rows or null for synthetic rows, got ${typeof o==`string`?`"${o}"`:String(o)}`);let u={};for(let e of Object.keys(t))e!==i&&e!==a&&(u[e]=f.has(e)?s(t[e],e):t[e]);p.push(u)}return{totalCount:d,data:p}}}}export{l as createCteResponseNormalizer,r as transformRecords};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lakeql/response-transformer",
-  "version": "0.1.7",
-  "description": "Transforms Trino array responses into typed JavaScript objects",
+  "version": "1.0.0",
+  "description": "Adapter-neutral, schema-aware transformation of keyed records for LakeQL",
   "keywords": [
     "lakeql",
     "mapping",
     "response",
-    "transform",
-    "trino"
+    "schema",
+    "transform"
   ],
   "homepage": "https://lakeql.dev",
   "license": "Apache-2.0",
@@ -39,18 +39,15 @@
     }
   },
   "dependencies": {
-    "@formkit/tempo": "1.1.0"
+    "@lakeql/datasource": "1.0.0"
   },
   "devDependencies": {
-    "@faker-js/faker": "10.5.0",
-    "@types/node": "24.13.3",
-    "@valibot/to-json-schema": "1.7.1",
-    "tsdown": "0.22.13",
-    "tsx": "4.23.1",
+    "@lakeql/tsconfig": "0.1.0",
+    "@lakeql/vitest-config": "0.1.0",
+    "@types/node": "24.19.2",
+    "tsdown": "0.23.7",
     "typescript": "6.0.3",
-    "valibot": "1.4.2",
-    "vitest": "4.1.10",
-    "@lakeql/tsconfig": "0.1.0"
+    "vitest": "5.1.0"
   },
   "scripts": {
     "build": "tsdown",
@@ -58,6 +55,7 @@
     "clean:cache": "git clean -xdf .cache .turbo",
     "clean:dist": "git clean -xdf dist",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }