@query-farm/vgi 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",

package/src/arguments/argument-spec.ts

@@ -19,6 +19,7 @@ import {
   VGI_RANGE_KEY,
   VGI_PATTERN_KEY,
 } from "../types.js";
+import { ArgumentValidationError } from "../errors.js";
 
 export interface ArgumentSpec {
   name: string;
@@ -151,6 +152,73 @@ export function constraintSpecFields(
   return fields;
 }
 
+/** Coerce a numeric const value (number or int64 `bigint`) to `number`. */
+function toNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  return undefined;
+}
+
+/** Equality for a choice comparison, coercing numeric/bigint operands. */
+function choiceEquals(choice: unknown, value: unknown): boolean {
+  const cn = toNumber(choice);
+  const vn = toNumber(value);
+  if (cn !== undefined && vn !== undefined) return cn === vn;
+  return choice === value;
+}
+
+/**
+ * Enforce a bind-time const value against its declared {@link ArgumentConstraints},
+ * throwing {@link ArgumentValidationError} on violation. Mirrors the Python SDK's
+ * `Arg._validate`: numeric range (`ge`/`le`/`gt`/`lt`), closed choice set, and
+ * regex `pattern`. A `null`/`undefined` value skips its value constraints.
+ */
+export function validateConstConstraints(
+  name: string,
+  constraints: ArgumentConstraints,
+  value: unknown,
+): void {
+  if (value === null || value === undefined) return;
+
+  const num = toNumber(value);
+  if (num !== undefined) {
+    if (constraints.ge !== undefined && num < constraints.ge) {
+      throw new ArgumentValidationError(`argument '${name}' must be >= ${constraints.ge}`);
+    }
+    if (constraints.le !== undefined && num > constraints.le) {
+      throw new ArgumentValidationError(`argument '${name}' must be <= ${constraints.le}`);
+    }
+    if (constraints.gt !== undefined && num <= constraints.gt) {
+      throw new ArgumentValidationError(`argument '${name}' must be > ${constraints.gt}`);
+    }
+    if (constraints.lt !== undefined && num >= constraints.lt) {
+      throw new ArgumentValidationError(`argument '${name}' must be < ${constraints.lt}`);
+    }
+  }
+
+  if (constraints.choices !== undefined && constraints.choices.length > 0) {
+    if (!constraints.choices.some((c) => choiceEquals(c, value))) {
+      throw new ArgumentValidationError(
+        `argument '${name}' must be one of ${JSON.stringify([...constraints.choices])}`,
+      );
+    }
+  }
+
+  if (constraints.pattern !== undefined && typeof value === "string") {
+    let re: RegExp | undefined;
+    try {
+      re = new RegExp(constraints.pattern);
+    } catch {
+      re = undefined; // an invalid declared regex must not reject the caller
+    }
+    if (re !== undefined && !re.test(value)) {
+      throw new ArgumentValidationError(
+        `argument '${name}' must match pattern ${JSON.stringify(constraints.pattern)}`,
+      );
+    }
+  }
+}
+
 function argumentSpecSortKey(spec: ArgumentSpec): [number, number | string] {
   if (typeof spec.position === "number") {
     return [0, spec.position];

package/src/functions/scalar.ts

@@ -37,7 +37,12 @@ import type {
   FunctionExample,
 } from "./types.js";
 import type { ArgumentSpec } from "../arguments/argument-spec.js";
-import { argumentSpecsToSchema, constraintSpecFields } from "../arguments/argument-spec.js";
+import {
+  argumentSpecsToSchema,
+  constraintSpecFields,
+  validateConstConstraints,
+  type ArgumentConstraints,
+} from "../arguments/argument-spec.js";
 import { batchToScalarDict, batchToSecretDict, batchFromColumns, projectBatch, safeNumber } from "../util/arrow/index.js";
 
 // ============================================================================
@@ -232,6 +237,26 @@ export function defineScalarFunction<
     }
   }
 
+  // Raw const-arg constraints for bind-time enforcement, keyed by arg name.
+  // Only the ordered `parameters` API carries constraints (the legacy
+  // params/constParams path does not), so only its const params appear here.
+  const constConstraints = new Map<string, ArgumentConstraints>();
+  if (config.parameters) {
+    for (const p of config.parameters) {
+      if (
+        p.const &&
+        (p.choices !== undefined ||
+          p.ge !== undefined ||
+          p.le !== undefined ||
+          p.gt !== undefined ||
+          p.lt !== undefined ||
+          p.pattern !== undefined)
+      ) {
+        constConstraints.set(p.name, p);
+      }
+    }
+  }
+
   const meta: FunctionMeta = {
     name: config.name,
     description: config.description,
@@ -270,7 +295,11 @@ export function defineScalarFunction<
         let constIdx = 0;
         for (const spec of specs) {
           if (spec.isConst) {
-            constArgs[spec.name] = request.arguments.get(constIdx, undefined);
+            const value = request.arguments.get(constIdx, undefined);
+            constArgs[spec.name] = value;
+            // Enforce declared const-arg constraints at bind (choices/range/pattern).
+            const constraints = constConstraints.get(spec.name);
+            if (constraints) validateConstConstraints(spec.name, constraints, value);
             constIdx++;
           }
         }