@prisma-next/adapter-postgres 0.3.0-dev.7 → 0.3.0-dev.71

package/src/core/json-schema-type-expression.ts

@@ -0,0 +1,131 @@
+type JsonSchemaRecord = Record<string, unknown>;
+
+const MAX_DEPTH = 32;
+
+function isRecord(value: unknown): value is JsonSchemaRecord {
+  return typeof value === 'object' && value !== null;
+}
+
+function escapeStringLiteral(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}
+
+function quotePropertyKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${escapeStringLiteral(key)}'`;
+}
+
+function renderLiteral(value: unknown): string {
+  if (typeof value === 'string') {
+    return `'${escapeStringLiteral(value)}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  return 'unknown';
+}
+
+function renderUnion(items: readonly unknown[], depth: number): string {
+  const rendered = items.map((item) => render(item, depth));
+  return rendered.join(' | ');
+}
+
+function renderObjectType(schema: JsonSchemaRecord, depth: number): string {
+  const properties = isRecord(schema['properties']) ? schema['properties'] : {};
+  const required = Array.isArray(schema['required'])
+    ? new Set(schema['required'].filter((key): key is string => typeof key === 'string'))
+    : new Set<string>();
+  const keys = Object.keys(properties).sort((left, right) => left.localeCompare(right));
+
+  if (keys.length === 0) {
+    const additionalProperties = schema['additionalProperties'];
+    if (additionalProperties === true || additionalProperties === undefined) {
+      return 'Record<string, unknown>';
+    }
+    return `Record<string, ${render(additionalProperties, depth)}>`;
+  }
+
+  const renderedProperties = keys.map((key) => {
+    const valueSchema = (properties as JsonSchemaRecord)[key];
+    const optionalMarker = required.has(key) ? '' : '?';
+    return `${quotePropertyKey(key)}${optionalMarker}: ${render(valueSchema, depth)}`;
+  });
+
+  return `{ ${renderedProperties.join('; ')} }`;
+}
+
+function renderArrayType(schema: JsonSchemaRecord, depth: number): string {
+  if (Array.isArray(schema['items'])) {
+    return `readonly [${schema['items'].map((item) => render(item, depth)).join(', ')}]`;
+  }
+
+  if (schema['items'] !== undefined) {
+    const itemType = render(schema['items'], depth);
+    const needsParens = itemType.includes(' | ') || itemType.includes(' & ');
+    return needsParens ? `(${itemType})[]` : `${itemType}[]`;
+  }
+
+  return 'unknown[]';
+}
+
+function render(schema: unknown, depth: number): string {
+  if (depth > MAX_DEPTH || !isRecord(schema)) {
+    return 'JsonValue';
+  }
+
+  const nextDepth = depth + 1;
+
+  if ('const' in schema) {
+    return renderLiteral(schema['const']);
+  }
+
+  if (Array.isArray(schema['enum'])) {
+    return schema['enum'].map((value) => renderLiteral(value)).join(' | ');
+  }
+
+  if (Array.isArray(schema['oneOf'])) {
+    return renderUnion(schema['oneOf'], nextDepth);
+  }
+
+  if (Array.isArray(schema['anyOf'])) {
+    return renderUnion(schema['anyOf'], nextDepth);
+  }
+
+  if (Array.isArray(schema['allOf'])) {
+    return schema['allOf'].map((item) => render(item, nextDepth)).join(' & ');
+  }
+
+  if (Array.isArray(schema['type'])) {
+    return schema['type'].map((item) => render({ ...schema, type: item }, nextDepth)).join(' | ');
+  }
+
+  switch (schema['type']) {
+    case 'string':
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'null':
+      return 'null';
+    case 'array':
+      return renderArrayType(schema, nextDepth);
+    case 'object':
+      return renderObjectType(schema, nextDepth);
+    default:
+      break;
+  }
+
+  return 'JsonValue';
+}
+
+export function renderTypeScriptTypeFromJsonSchema(schema: unknown): string {
+  return render(schema, 0);
+}

package/src/core/json-schema-validator.ts

@@ -0,0 +1,53 @@
+import type {
+  JsonSchemaValidateFn,
+  JsonSchemaValidationError,
+  JsonSchemaValidationResult,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import Ajv from 'ajv';
+
+export type { JsonSchemaValidateFn, JsonSchemaValidationError, JsonSchemaValidationResult };
+
+/**
+ * Shared Ajv instance for all JSON Schema validators.
+ * Reusing a single instance avoids ~50-100KB memory overhead per compiled schema.
+ */
+let sharedAjv: Ajv | undefined;
+
+function getSharedAjv(): Ajv {
+  if (!sharedAjv) {
+    sharedAjv = new Ajv({ allErrors: false, strict: false });
+  }
+  return sharedAjv;
+}
+
+/**
+ * Compiles a JSON Schema object into a reusable validate function using Ajv.
+ *
+ * The returned function validates a value against the schema and returns
+ * a structured result with error details on failure.
+ *
+ * Uses a shared Ajv instance and fail-fast mode (`allErrors: false`)
+ * to minimize memory and CPU overhead.
+ *
+ * @param schema - A JSON Schema object (draft-07 compatible)
+ * @returns A validate function
+ */
+export function compileJsonSchemaValidator(schema: Record<string, unknown>): JsonSchemaValidateFn {
+  const ajv = getSharedAjv();
+  const validate = ajv.compile(schema);
+
+  return (value: unknown): JsonSchemaValidationResult => {
+    const valid = validate(value);
+    if (valid) {
+      return { valid: true };
+    }
+
+    const errors: JsonSchemaValidationError[] = (validate.errors ?? []).map((err) => ({
+      path: err.instancePath || '/',
+      message: err.message ?? 'unknown validation error',
+      keyword: err.keyword,
+    }));
+
+    return { valid: false, errors };
+  };
+}

package/src/core/parameterized-types.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared utility for expanding parameterized Postgres types to their full SQL representation.
+ *
+ * This module provides a single source of truth for type expansion logic, used by:
+ * - Schema verification (verify-sql-schema.ts) via the expandNativeType codec control hook
+ * - Migration planner (planner.ts) via direct import
+ *
+ * @module
+ */
+
+import {
+  PG_BIT_CODEC_ID,
+  PG_CHAR_CODEC_ID,
+  PG_INTERVAL_CODEC_ID,
+  PG_NUMERIC_CODEC_ID,
+  PG_TIME_CODEC_ID,
+  PG_TIMESTAMP_CODEC_ID,
+  PG_TIMESTAMPTZ_CODEC_ID,
+  PG_TIMETZ_CODEC_ID,
+  PG_VARBIT_CODEC_ID,
+  PG_VARCHAR_CODEC_ID,
+  SQL_CHAR_CODEC_ID,
+  SQL_VARCHAR_CODEC_ID,
+} from './codec-ids';
+
+/**
+ * Input for expanding parameterized native types.
+ */
+export interface ExpandNativeTypeInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+/** Set of codec IDs that use the 'length' parameter */
+const LENGTH_CODEC_IDS: Set<string> = new Set([
+  SQL_CHAR_CODEC_ID,
+  SQL_VARCHAR_CODEC_ID,
+  PG_CHAR_CODEC_ID,
+  PG_VARCHAR_CODEC_ID,
+  PG_BIT_CODEC_ID,
+  PG_VARBIT_CODEC_ID,
+]);
+
+/** Set of codec IDs that use the 'precision' parameter for temporal types */
+const TEMPORAL_PRECISION_CODEC_IDS: Set<string> = new Set([
+  PG_TIMESTAMP_CODEC_ID,
+  PG_TIMESTAMPTZ_CODEC_ID,
+  PG_TIME_CODEC_ID,
+  PG_TIMETZ_CODEC_ID,
+  PG_INTERVAL_CODEC_ID,
+]);
+
+/**
+ * Validates that a value is a valid type parameter number.
+ * Type parameters must be finite, non-negative integers.
+ */
+function isValidTypeParamNumber(value: unknown): value is number {
+  return (
+    typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value >= 0
+  );
+}
+
+/**
+ * Expands a parameterized native type to its full SQL representation.
+ *
+ * For example:
+ * - { nativeType: 'character varying', typeParams: { length: 255 } } -> 'character varying(255)'
+ * - { nativeType: 'numeric', typeParams: { precision: 10, scale: 2 } } -> 'numeric(10,2)'
+ * - { nativeType: 'timestamp without time zone', typeParams: { precision: 3 } } -> 'timestamp without time zone(3)'
+ *
+ * Returns the original nativeType if:
+ * - No typeParams are provided
+ * - No codecId is provided
+ * - The codecId is not a known parameterized type
+ * - The typeParams values are invalid
+ */
+export function expandParameterizedNativeType(input: ExpandNativeTypeInput): string {
+  const { nativeType, codecId, typeParams } = input;
+
+  if (!typeParams || !codecId) {
+    return nativeType;
+  }
+
+  // Length-parameterized types: char, varchar, bit, varbit
+  if (LENGTH_CODEC_IDS.has(codecId)) {
+    const length = typeParams['length'];
+    if (isValidTypeParamNumber(length)) {
+      return `${nativeType}(${length})`;
+    }
+    return nativeType;
+  }
+
+  // Numeric with precision and optional scale
+  if (codecId === PG_NUMERIC_CODEC_ID) {
+    const precision = typeParams['precision'];
+    const scale = typeParams['scale'];
+
+    if (isValidTypeParamNumber(precision)) {
+      if (isValidTypeParamNumber(scale)) {
+        return `${nativeType}(${precision},${scale})`;
+      }
+      return `${nativeType}(${precision})`;
+    }
+    return nativeType;
+  }
+
+  // Temporal types with precision: timestamp, timestamptz, time, timetz, interval
+  if (TEMPORAL_PRECISION_CODEC_IDS.has(codecId)) {
+    const precision = typeParams['precision'];
+    if (isValidTypeParamNumber(precision)) {
+      return `${nativeType}(${precision})`;
+    }
+    return nativeType;
+  }
+
+  return nativeType;
+}

package/src/core/sql-utils.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared SQL utility functions for the Postgres adapter.
+ *
+ * These functions handle safe SQL identifier and literal escaping
+ * with security validations to prevent injection and encoding issues.
+ */
+
+/**
+ * Error thrown when an invalid SQL identifier or literal is detected.
+ * Boundary layers map this to structured envelopes.
+ */
+export class SqlEscapeError extends Error {
+  constructor(
+    message: string,
+    public readonly value: string,
+    public readonly kind: 'identifier' | 'literal',
+  ) {
+    super(message);
+    this.name = 'SqlEscapeError';
+  }
+}
+
+/**
+ * Maximum length for PostgreSQL identifiers (NAMEDATALEN - 1).
+ */
+const MAX_IDENTIFIER_LENGTH = 63;
+
+/**
+ * Validates and quotes a PostgreSQL identifier (table, column, type, schema names).
+ *
+ * Security validations:
+ * - Rejects null bytes which could cause truncation or unexpected behavior
+ * - Rejects empty identifiers
+ * - Warns on identifiers exceeding PostgreSQL's 63-character limit
+ *
+ * @throws {SqlEscapeError} If the identifier contains null bytes or is empty
+ */
+export function quoteIdentifier(identifier: string): string {
+  if (identifier.length === 0) {
+    throw new SqlEscapeError('Identifier cannot be empty', identifier, 'identifier');
+  }
+  if (identifier.includes('\0')) {
+    throw new SqlEscapeError(
+      'Identifier cannot contain null bytes',
+      identifier.replace(/\0/g, '\\0'),
+      'identifier',
+    );
+  }
+  // PostgreSQL will truncate identifiers longer than 63 characters.
+  // We don't throw here because it's not a security issue, but callers should be aware.
+  if (identifier.length > MAX_IDENTIFIER_LENGTH) {
+    // Log warning in development, but don't fail - PostgreSQL handles truncation
+    console.warn(
+      `Identifier "${identifier.slice(0, 20)}..." exceeds PostgreSQL's ${MAX_IDENTIFIER_LENGTH}-character limit and will be truncated`,
+    );
+  }
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Escapes a string literal for safe use in SQL statements.
+ *
+ * Security validations:
+ * - Rejects null bytes which could cause truncation or unexpected behavior
+ *
+ * Note: This assumes PostgreSQL's `standard_conforming_strings` is ON (default since PG 9.1).
+ * Backslashes are treated as literal characters, not escape sequences.
+ *
+ * @throws {SqlEscapeError} If the value contains null bytes
+ */
+export function escapeLiteral(value: string): string {
+  if (value.includes('\0')) {
+    throw new SqlEscapeError(
+      'Literal value cannot contain null bytes',
+      value.replace(/\0/g, '\\0'),
+      'literal',
+    );
+  }
+  return value.replace(/'/g, "''");
+}
+
+/**
+ * Builds a qualified name (schema.object) with proper quoting.
+ */
+export function qualifyName(schemaName: string, objectName: string): string {
+  return `${quoteIdentifier(schemaName)}.${quoteIdentifier(objectName)}`;
+}
+
+/**
+ * Validates that an enum value doesn't exceed PostgreSQL's label length limit.
+ *
+ * PostgreSQL enum labels have a maximum length of NAMEDATALEN-1 (63 bytes by default).
+ * Unlike identifiers, enum labels that exceed this limit cause an error rather than
+ * silent truncation.
+ *
+ * @param value - The enum value to validate
+ * @param enumTypeName - Name of the enum type (for error messages)
+ * @throws {SqlEscapeError} If the value exceeds the maximum length
+ */
+export function validateEnumValueLength(value: string, enumTypeName: string): void {
+  // PostgreSQL uses byte length, not character length. For simplicity, we use
+  // character length as a conservative approximation (multi-byte chars would fail earlier).
+  if (value.length > MAX_IDENTIFIER_LENGTH) {
+    throw new SqlEscapeError(
+      `Enum value "${value.slice(0, 20)}..." for type "${enumTypeName}" exceeds PostgreSQL's ` +
+        `${MAX_IDENTIFIER_LENGTH}-character label limit`,
+      value,
+      'literal',
+    );
+  }
+}

package/src/core/standard-schema.ts

@@ -0,0 +1,71 @@
+type UnknownRecord = Record<string, unknown>;
+
+type StandardSchemaJsonSchemaField = {
+  readonly output?: unknown;
+};
+
+/**
+ * Runtime view of the Standard Schema protocol.
+ * Reads `~standard.jsonSchema.output` for the serializable JSON Schema representation,
+ * and `.expression` for an optional TypeScript type expression string (Arktype-specific).
+ *
+ * This differs from the compile-time `StandardSchemaLike` in `codec-types.ts`, which reads
+ * `~standard.types.output` for TypeScript type narrowing in contract.d.ts.
+ */
+export type StandardSchemaLike = {
+  readonly '~standard'?: {
+    readonly version?: number;
+    readonly jsonSchema?: StandardSchemaJsonSchemaField;
+  };
+  readonly expression?: unknown;
+};
+
+function isObjectLike(value: unknown): value is UnknownRecord {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+
+function resolveOutputJsonSchemaField(schema: StandardSchemaLike): unknown {
+  const jsonSchema = schema['~standard']?.jsonSchema;
+  if (!jsonSchema) {
+    return undefined;
+  }
+
+  if (typeof jsonSchema.output === 'function') {
+    return jsonSchema.output({
+      target: 'draft-07',
+    });
+  }
+
+  return jsonSchema.output;
+}
+
+export function extractStandardSchemaOutputJsonSchema(
+  schema: StandardSchemaLike,
+): UnknownRecord | undefined {
+  const outputSchema = resolveOutputJsonSchemaField(schema);
+  if (!isObjectLike(outputSchema)) {
+    return undefined;
+  }
+
+  return outputSchema;
+}
+
+export function extractStandardSchemaTypeExpression(
+  schema: StandardSchemaLike,
+): string | undefined {
+  const expression = schema.expression;
+  if (typeof expression !== 'string') {
+    return undefined;
+  }
+
+  const trimmedExpression = expression.trim();
+  if (trimmedExpression.length === 0) {
+    return undefined;
+  }
+
+  return trimmedExpression;
+}
+
+export function isStandardSchemaLike(value: unknown): value is StandardSchemaLike {
+  return isObjectLike(value) && isObjectLike((value as StandardSchemaLike)['~standard']);
+}

package/src/exports/codec-types.ts

@@ -7,5 +7,77 @@
  * Runtime codec implementations are provided by the adapter's codec registry.
  */
 
-export type { CodecTypes } from '../core/codecs';
+import type { CodecTypes as CoreCodecTypes, JsonValue } from '../core/codecs';
+
+/**
+ * Compile-time view of the Standard Schema protocol.
+ * Reads `~standard.types.output` to resolve TypeScript output types for contract.d.ts.
+ *
+ * This differs from the runtime `StandardSchemaLike` in `standard-schema.ts`, which reads
+ * `~standard.jsonSchema.output` for the serializable JSON Schema representation.
+ * Both are needed: this one drives compile-time type narrowing, the other drives
+ * build-time contract emission.
+ */
+type StandardSchemaLike = {
+  readonly '~standard'?: {
+    readonly types?: {
+      readonly output?: unknown;
+    };
+  };
+};
+
+type ResolveStandardSchemaOutput<P> = P extends { readonly schema: infer Schema }
+  ? Schema extends { readonly infer: infer Output }
+    ? Output
+    : Schema extends {
+          readonly '~standard': { readonly types?: { readonly output?: infer Output } };
+        }
+      ? Output extends undefined
+        ? JsonValue
+        : Output
+      : JsonValue
+  : JsonValue;
+
+export type CodecTypes = CoreCodecTypes & {
+  readonly 'pg/json@1': CoreCodecTypes['pg/json@1'] & {
+    readonly parameterizedOutput: <P extends { readonly schema?: StandardSchemaLike }>(
+      params: P,
+    ) => ResolveStandardSchemaOutput<P>;
+  };
+  readonly 'pg/jsonb@1': CoreCodecTypes['pg/jsonb@1'] & {
+    readonly parameterizedOutput: <P extends { readonly schema?: StandardSchemaLike }>(
+      params: P,
+    ) => ResolveStandardSchemaOutput<P>;
+  };
+};
+
+export type { JsonValue };
 export { dataTypes } from '../core/codecs';
+
+type Branded<T, Shape extends Record<string, unknown>> = T & {
+  readonly [K in keyof Shape]: Shape[K];
+};
+
+type BrandedString<Shape extends Record<string, unknown>> = Branded<string, Shape>;
+
+export type Char<N extends number> = BrandedString<{ __charLength: N }>;
+export type Varchar<N extends number> = BrandedString<{ __varcharLength: N }>;
+export type Numeric<P extends number, S extends number | undefined = undefined> = BrandedString<{
+  __numericPrecision: P;
+  __numericScale: S;
+}>;
+export type Bit<N extends number> = BrandedString<{ __bitLength: N }>;
+export type VarBit<N extends number> = BrandedString<{ __varbitLength: N }>;
+export type Timestamp<P extends number | undefined = undefined> = BrandedString<{
+  __timestampPrecision: P;
+}>;
+export type Timestamptz<P extends number | undefined = undefined> = BrandedString<{
+  __timestamptzPrecision: P;
+}>;
+export type Time<P extends number | undefined = undefined> = BrandedString<{ __timePrecision: P }>;
+export type Timetz<P extends number | undefined = undefined> = BrandedString<{
+  __timetzPrecision: P;
+}>;
+export type Interval<P extends number | undefined = undefined> = BrandedString<{
+  __intervalPrecision: P;
+}>;