@query-farm/vgi 0.8.0 → 0.10.0

package/dist/arguments/argument-spec.d.ts

@@ -8,7 +8,63 @@ export interface ArgumentSpec {
     isVarargs?: boolean;
     isConst?: boolean;
     doc?: string;
+    /**
+     * Discovery-facing constraint metadata, pre-encoded to their surfaced UTF-8
+     * forms (presence-only — `undefined` means the constraint is absent and the
+     * corresponding field-metadata key is omitted entirely). Mirrors Python's
+     * `ArgumentSpec.default_json` / `choices_json` / `range_notation` / `pattern`
+     * so `argumentSpecsToSchema`/`schemaToArgumentSpecs` round-trip symmetrically.
+     */
+    defaultJson?: string;
+    choicesJson?: string;
+    rangeNotation?: string;
+    pattern?: string;
 }
+/**
+ * Raw per-argument constraint declarations, as authored on a function's
+ * argument descriptor. Encoded into the pre-computed {@link ArgumentSpec}
+ * constraint fields via {@link constraintSpecFields}.
+ */
+export interface ArgumentConstraints {
+    /** Closed set of allowed values (JSON-encoded into `vgi_choices`). */
+    choices?: readonly unknown[];
+    /** Inclusive lower bound (`>=`). */
+    ge?: number;
+    /** Inclusive upper bound (`<=`). */
+    le?: number;
+    /** Exclusive lower bound (`>`). */
+    gt?: number;
+    /** Exclusive upper bound (`<`). */
+    lt?: number;
+    /** Regex the value must match (surfaced as `vgi_pattern`, as-is). */
+    pattern?: string;
+    /** Default value (JSON-encoded into `vgi_default`); optional args only. */
+    default?: unknown;
+}
+/**
+ * Build interval notation from an argument's numeric bounds.
+ *
+ * Inclusive bounds (`ge`/`le`) render as square brackets, exclusive bounds
+ * (`gt`/`lt`) as parentheses, and an open side as `-inf`/`+inf`. Returns
+ * `undefined` when the argument has no numeric bound at all.
+ *
+ * Examples: `ge=0,le=10` -> `"[0, 10]"`; `gt=0` -> `"(0, +inf)"`;
+ * `ge=1,lt=10` -> `"[1, 10)"`.
+ */
+export declare function formatRange(ge?: number, le?: number, gt?: number, lt?: number): string | undefined;
+/**
+ * Encode raw {@link ArgumentConstraints} into the pre-computed constraint
+ * fields of an {@link ArgumentSpec} (presence-only — absent constraints yield
+ * no field). Mirrors Python's `_constraint_kwargs`.
+ */
+export declare function constraintSpecFields(constraints: ArgumentConstraints | undefined): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern">;
+/**
+ * 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 declare function validateConstConstraints(name: string, constraints: ArgumentConstraints, value: unknown): void;
 /**
  * Convert ArgumentSpecs to an Arrow Schema with VGI metadata keys.
  * Positional arguments come first (in order), named arguments follow.

package/dist/functions/scalar.d.ts

@@ -25,6 +25,20 @@ export interface ScalarParameterDef {
     varargs?: boolean;
     /** Human-readable per-argument description (surfaced as `vgi_doc`). */
     doc?: string;
+    /** Closed set of allowed values (surfaced as `vgi_choices`). */
+    choices?: readonly unknown[];
+    /** Inclusive lower bound, `>=` (folded into `vgi_range`). */
+    ge?: number;
+    /** Inclusive upper bound, `<=` (folded into `vgi_range`). */
+    le?: number;
+    /** Exclusive lower bound, `>` (folded into `vgi_range`). */
+    gt?: number;
+    /** Exclusive upper bound, `<` (folded into `vgi_range`). */
+    lt?: number;
+    /** Regex the value must match (surfaced as `vgi_pattern`). */
+    pattern?: string;
+    /** Default value (surfaced as `vgi_default`, JSON-encoded). */
+    default?: unknown;
 }
 /**
  * The typed compute row for a scalar function: one property per declared

package/dist/index.core.d.ts

@@ -14,7 +14,7 @@ export { FunctionRegistry } from "./functions/registry.js";
 export { FunctionType, FunctionStability, NullHandling, OrderPreservation, OrderDependence, DistinctDependence, TableInOutPhase, DEFAULT_MAX_WORKERS, } from "./types.js";
 export type { BindRequest, BindResponse, CopyFromContext, CopyToContext, InitRequest, GlobalInitResponse, TableCardinality, } from "./protocol/types.js";
 export { Arguments } from "./arguments/arguments.js";
-export { type ArgumentSpec, argumentSpecsToSchema, schemaToArgumentSpecs, macroArgumentsSchema, macroParameterDocsFromSchema } from "./arguments/argument-spec.js";
+export { type ArgumentSpec, type ArgumentConstraints, argumentSpecsToSchema, schemaToArgumentSpecs, macroArgumentsSchema, macroParameterDocsFromSchema, formatRange, constraintSpecFields } from "./arguments/argument-spec.js";
 export { VgiError, RowCountMismatchError, FunctionNotFoundError, CatalogReadOnlyError, CatalogNotFoundError, CatalogAlreadyExistsError, ArgumentValidationError, NoCatalogError, } from "./errors.js";
 export type { ResolvedMetadata, ParameterInfo } from "./metadata/types.js";
 export { CatalogFunctionType } from "./metadata/types.js";

package/dist/index.js

@@ -2600,6 +2600,10 @@ var VGI_VARARGS_TRUE = "true";
 var VGI_CONST_KEY = "vgi_const";
 var VGI_CONST_TRUE = "true";
 var VGI_DOC_KEY = "vgi_doc";
+var VGI_DEFAULT_KEY = "vgi_default";
+var VGI_CHOICES_KEY = "vgi_choices";
+var VGI_RANGE_KEY = "vgi_range";
+var VGI_PATTERN_KEY = "vgi_pattern";
 var DEFAULT_MAX_WORKERS = 99999;
 
 // src/errors.ts
@@ -2659,6 +2663,229 @@ class NoCatalogError extends VgiError {
   }
 }
 
+// src/arguments/argument-spec.ts
+init_arrow();
+function safeJson(value) {
+  try {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+      return JSON.stringify(String(value));
+    }
+    return encoded;
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}
+function formatRange(ge, le, gt, lt) {
+  if (ge === undefined && le === undefined && gt === undefined && lt === undefined) {
+    return;
+  }
+  let low;
+  if (gt !== undefined) {
+    low = `(${gt}`;
+  } else if (ge !== undefined) {
+    low = `[${ge}`;
+  } else {
+    low = "(-inf";
+  }
+  let high;
+  if (lt !== undefined) {
+    high = `${lt})`;
+  } else if (le !== undefined) {
+    high = `${le}]`;
+  } else {
+    high = "+inf)";
+  }
+  return `${low}, ${high}`;
+}
+function constraintSpecFields(constraints) {
+  const fields = {};
+  if (constraints === undefined)
+    return fields;
+  if ("default" in constraints && constraints.default !== undefined) {
+    fields.defaultJson = safeJson(constraints.default);
+  }
+  if (constraints.choices !== undefined) {
+    fields.choicesJson = safeJson([...constraints.choices]);
+  }
+  const range = formatRange(constraints.ge, constraints.le, constraints.gt, constraints.lt);
+  if (range !== undefined) {
+    fields.rangeNotation = range;
+  }
+  if (constraints.pattern !== undefined) {
+    fields.pattern = constraints.pattern;
+  }
+  return fields;
+}
+function toNumber(value) {
+  if (typeof value === "number")
+    return value;
+  if (typeof value === "bigint")
+    return Number(value);
+  return;
+}
+function choiceEquals(choice, value) {
+  const cn = toNumber(choice);
+  const vn = toNumber(value);
+  if (cn !== undefined && vn !== undefined)
+    return cn === vn;
+  return choice === value;
+}
+function validateConstConstraints(name, constraints, value) {
+  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;
+    try {
+      re = new RegExp(constraints.pattern);
+    } catch {
+      re = undefined;
+    }
+    if (re !== undefined && !re.test(value)) {
+      throw new ArgumentValidationError(`argument '${name}' must match pattern ${JSON.stringify(constraints.pattern)}`);
+    }
+  }
+}
+function argumentSpecSortKey(spec) {
+  if (typeof spec.position === "number") {
+    return [0, spec.position];
+  }
+  return [1, spec.position];
+}
+function argumentSpecsToSchema(specs) {
+  const sorted = [...specs].sort((a, b) => {
+    const ka = argumentSpecSortKey(a);
+    const kb = argumentSpecSortKey(b);
+    if (ka[0] !== kb[0])
+      return ka[0] - kb[0];
+    if (typeof ka[1] === "number" && typeof kb[1] === "number") {
+      return ka[1] - kb[1];
+    }
+    return String(ka[1]).localeCompare(String(kb[1]));
+  });
+  const fields = [];
+  for (const spec of sorted) {
+    const metadata = new Map;
+    if (typeof spec.position === "string") {
+      metadata.set(VGI_ARG_KEY, VGI_ARG_NAMED);
+    }
+    if (spec.isTableInput) {
+      metadata.set(VGI_TYPE_KEY, VGI_TYPE_TABLE);
+    } else if (spec.isAnyType) {
+      metadata.set(VGI_TYPE_KEY, VGI_TYPE_ANY);
+    }
+    if (spec.isVarargs) {
+      metadata.set(VGI_VARARGS_KEY, VGI_VARARGS_TRUE);
+    }
+    if (spec.isConst) {
+      metadata.set(VGI_CONST_KEY, VGI_CONST_TRUE);
+    }
+    if (spec.doc) {
+      metadata.set(VGI_DOC_KEY, spec.doc);
+    }
+    if (spec.defaultJson !== undefined) {
+      metadata.set(VGI_DEFAULT_KEY, spec.defaultJson);
+    }
+    if (spec.choicesJson !== undefined) {
+      metadata.set(VGI_CHOICES_KEY, spec.choicesJson);
+    }
+    if (spec.rangeNotation !== undefined) {
+      metadata.set(VGI_RANGE_KEY, spec.rangeNotation);
+    }
+    if (spec.pattern !== undefined) {
+      metadata.set(VGI_PATTERN_KEY, spec.pattern);
+    }
+    const field3 = field2(spec.name, spec.arrowType, true, metadata.size > 0 ? metadata : undefined);
+    fields.push(field3);
+  }
+  return schema2(fields);
+}
+function macroArgumentsSchema(parameters, parameterDefaultValues, parameterDocs) {
+  const docs = parameterDocs ?? {};
+  const defaultTypes = new Map;
+  if (parameterDefaultValues && parameterDefaultValues.length > 0) {
+    const batch = deserializeBatch(parameterDefaultValues);
+    for (const f of batch.schema.fields) {
+      defaultTypes.set(f.name, f.type);
+    }
+  }
+  const fields = [];
+  for (const name of parameters) {
+    const metadata = new Map;
+    const doc = docs[name];
+    if (doc) {
+      metadata.set(VGI_DOC_KEY, doc);
+    }
+    const fieldType = defaultTypes.get(name) ?? nullType2();
+    fields.push(field2(name, fieldType, true, metadata.size > 0 ? metadata : undefined));
+  }
+  return schema2(fields);
+}
+function macroParameterDocsFromSchema(schema3) {
+  const docs = {};
+  for (const field3 of schema3.fields) {
+    const doc = field3.metadata.get(VGI_DOC_KEY);
+    if (doc) {
+      docs[field3.name] = doc;
+    }
+  }
+  return docs;
+}
+function schemaToArgumentSpecs(schema3) {
+  const specs = [];
+  let positionIndex = 0;
+  for (const field3 of schema3.fields) {
+    const metadata = field3.metadata;
+    const isNamed = metadata.get(VGI_ARG_KEY) === VGI_ARG_NAMED;
+    const position = isNamed ? field3.name : positionIndex++;
+    const vgiType = metadata.get(VGI_TYPE_KEY);
+    const isTableInput = vgiType === VGI_TYPE_TABLE;
+    const isAnyType = vgiType === VGI_TYPE_ANY;
+    const isVarargs = metadata.get(VGI_VARARGS_KEY) === VGI_VARARGS_TRUE;
+    const isConst = metadata.get(VGI_CONST_KEY) === VGI_CONST_TRUE;
+    const doc = metadata.get(VGI_DOC_KEY) ?? "";
+    const defaultJson = metadata.get(VGI_DEFAULT_KEY);
+    const choicesJson = metadata.get(VGI_CHOICES_KEY);
+    const rangeNotation = metadata.get(VGI_RANGE_KEY);
+    const pattern = metadata.get(VGI_PATTERN_KEY);
+    specs.push({
+      name: field3.name,
+      position,
+      arrowType: field3.type,
+      isTableInput,
+      isAnyType,
+      isVarargs,
+      isConst,
+      doc,
+      defaultJson,
+      choicesJson,
+      rangeNotation,
+      pattern
+    });
+  }
+  return specs;
+}
+
 // src/util/arrow/index.ts
 init_arrow();
 
@@ -2676,7 +2903,8 @@ function defineScalarFunction(config) {
         isAnyType: isAny,
         isConst: p.const,
         isVarargs: p.varargs,
-        doc: p.doc
+        doc: p.doc,
+        ...constraintSpecFields(p)
       });
     }
   } else {
@@ -2705,6 +2933,14 @@ function defineScalarFunction(config) {
       }
     }
   }
+  const constConstraints = new Map;
+  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 = {
     name: config.name,
     description: config.description,
@@ -2731,7 +2967,11 @@ function defineScalarFunction(config) {
         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;
+            const constraints = constConstraints.get(spec.name);
+            if (constraints)
+              validateConstConstraints(spec.name, constraints, value);
             constIdx++;
           }
         }
@@ -6322,108 +6562,6 @@ function serializeColumnStatistics(stats, _cacheMaxAgeSeconds) {
   return serializeBatch(buildStatisticsBatch(stats));
 }
 
-// src/arguments/argument-spec.ts
-init_arrow();
-function argumentSpecSortKey(spec) {
-  if (typeof spec.position === "number") {
-    return [0, spec.position];
-  }
-  return [1, spec.position];
-}
-function argumentSpecsToSchema(specs) {
-  const sorted = [...specs].sort((a, b) => {
-    const ka = argumentSpecSortKey(a);
-    const kb = argumentSpecSortKey(b);
-    if (ka[0] !== kb[0])
-      return ka[0] - kb[0];
-    if (typeof ka[1] === "number" && typeof kb[1] === "number") {
-      return ka[1] - kb[1];
-    }
-    return String(ka[1]).localeCompare(String(kb[1]));
-  });
-  const fields = [];
-  for (const spec of sorted) {
-    const metadata = new Map;
-    if (typeof spec.position === "string") {
-      metadata.set(VGI_ARG_KEY, VGI_ARG_NAMED);
-    }
-    if (spec.isTableInput) {
-      metadata.set(VGI_TYPE_KEY, VGI_TYPE_TABLE);
-    } else if (spec.isAnyType) {
-      metadata.set(VGI_TYPE_KEY, VGI_TYPE_ANY);
-    }
-    if (spec.isVarargs) {
-      metadata.set(VGI_VARARGS_KEY, VGI_VARARGS_TRUE);
-    }
-    if (spec.isConst) {
-      metadata.set(VGI_CONST_KEY, VGI_CONST_TRUE);
-    }
-    if (spec.doc) {
-      metadata.set(VGI_DOC_KEY, spec.doc);
-    }
-    const field3 = field2(spec.name, spec.arrowType, true, metadata.size > 0 ? metadata : undefined);
-    fields.push(field3);
-  }
-  return schema2(fields);
-}
-function macroArgumentsSchema(parameters, parameterDefaultValues, parameterDocs) {
-  const docs = parameterDocs ?? {};
-  const defaultTypes = new Map;
-  if (parameterDefaultValues && parameterDefaultValues.length > 0) {
-    const batch = deserializeBatch(parameterDefaultValues);
-    for (const f of batch.schema.fields) {
-      defaultTypes.set(f.name, f.type);
-    }
-  }
-  const fields = [];
-  for (const name of parameters) {
-    const metadata = new Map;
-    const doc = docs[name];
-    if (doc) {
-      metadata.set(VGI_DOC_KEY, doc);
-    }
-    const fieldType = defaultTypes.get(name) ?? nullType2();
-    fields.push(field2(name, fieldType, true, metadata.size > 0 ? metadata : undefined));
-  }
-  return schema2(fields);
-}
-function macroParameterDocsFromSchema(schema3) {
-  const docs = {};
-  for (const field3 of schema3.fields) {
-    const doc = field3.metadata.get(VGI_DOC_KEY);
-    if (doc) {
-      docs[field3.name] = doc;
-    }
-  }
-  return docs;
-}
-function schemaToArgumentSpecs(schema3) {
-  const specs = [];
-  let positionIndex = 0;
-  for (const field3 of schema3.fields) {
-    const metadata = field3.metadata;
-    const isNamed = metadata.get(VGI_ARG_KEY) === VGI_ARG_NAMED;
-    const position = isNamed ? field3.name : positionIndex++;
-    const vgiType = metadata.get(VGI_TYPE_KEY);
-    const isTableInput = vgiType === VGI_TYPE_TABLE;
-    const isAnyType = vgiType === VGI_TYPE_ANY;
-    const isVarargs = metadata.get(VGI_VARARGS_KEY) === VGI_VARARGS_TRUE;
-    const isConst = metadata.get(VGI_CONST_KEY) === VGI_CONST_TRUE;
-    const doc = metadata.get(VGI_DOC_KEY) ?? "";
-    specs.push({
-      name: field3.name,
-      position,
-      arrowType: field3.type,
-      isTableInput,
-      isAnyType,
-      isVarargs,
-      isConst,
-      doc
-    });
-  }
-  return specs;
-}
-
 // src/metadata/types.ts
 var CatalogFunctionType;
 ((CatalogFunctionType2) => {
@@ -10791,6 +10929,7 @@ export {
   fromBrandedNumber,
   fromBrandedBigInt,
   fromBranded,
+  formatRange,
   formatPushedFilters,
   float642 as float64,
   float323 as float32,
@@ -10839,6 +10978,7 @@ export {
   dateMillisecond2 as dateMillisecond,
   dateDay2 as dateDay,
   date2 as date,
+  constraintSpecFields,
   columnFromArray,
   codecFor,
   bytes,
@@ -10917,4 +11057,4 @@ export {
   ArgumentValidationError
 };
 
-//# debugId=2E19C6BFB109AD5C64756E2164756E21
+//# debugId=4ECD85EFC57F269A64756E2164756E21