@lakeql/schema-generator 0.1.1 → 0.2.0

package/dist/endpoint-schema.d.mts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+
+//#region src/endpoint-schema.d.ts
+/**
+ * Regex pattern for field names: alphanumeric + underscore, no leading digit, max 64 chars.
+ */
+declare const fieldNamePattern: RegExp;
+/**
+ * Regex pattern for metadata fields (tableName, catalog, schema): alphanumeric + underscore,
+ * no leading digit, max 128 chars.
+ */
+declare const metadataFieldPattern: RegExp;
+/**
+ * Supported load strategies for the mutation write pipeline.
+ */
+declare const loadStrategies: readonly ["full_load", "full_load_append", "append"];
+type LoadStrategy = (typeof loadStrategies)[number];
+/**
+ * Mutation pipeline configuration for an endpoint.
+ */
+interface MutationConfig {
+  /** Load strategy for the write pipeline. */
+  loadStrategy: LoadStrategy;
+  /** S3 base path for endpoint data. */
+  basePath: string;
+}
+/**
+ * Zod schema for the mutation configuration object.
+ */
+declare const mutationConfigSchema: z.ZodObject<{
+  loadStrategy: z.ZodEnum<{
+    full_load: "full_load";
+    full_load_append: "full_load_append";
+    append: "append";
+  }>;
+  basePath: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod schema for the mutation field: either `false` (disabled) or a config object (enabled).
+ */
+declare const mutationSchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+  loadStrategy: z.ZodEnum<{
+    full_load: "full_load";
+    full_load_append: "full_load_append";
+    append: "append";
+  }>;
+  basePath: z.ZodString;
+}, z.core.$strip>]>;
+/**
+ * Supported primitive types for field definitions.
+ */
+declare const primitiveTypes: readonly ["String", "Integer", "Float", "Boolean", "Date", "DateTime"];
+type PrimitiveType = (typeof primitiveTypes)[number];
+/**
+ * Field-level validation refinement types.
+ */
+type FieldValidation = {
+  type: "email";
+} | {
+  type: "url";
+} | {
+  type: "uuid";
+} | {
+  type: "min";
+  value: number;
+} | {
+  type: "max";
+  value: number;
+} | {
+  type: "regex";
+  pattern: string;
+};
+/**
+ * Field-level options for mutation input validation.
+ */
+interface FieldOptions {
+  /** Whether the field is required in mutation input. Default: false. */
+  required?: boolean;
+  /** Validation refinements to apply via Zod. */
+  validations?: FieldValidation[];
+}
+/**
+ * Zod schema for field validation refinements.
+ */
+declare const fieldValidationSchema: z.ZodType<FieldValidation>;
+/**
+ * Zod schema for field-level options.
+ */
+declare const fieldOptionsSchema: z.ZodType<FieldOptions>;
+interface ArrayItemDefinition {
+  type: PrimitiveType | "Object";
+  fields?: FieldDefinition[];
+}
+interface FieldDefinition {
+  name: string;
+  type: PrimitiveType | "Object" | "Array";
+  fields?: FieldDefinition[];
+  items?: ArrayItemDefinition;
+  options?: FieldOptions;
+}
+/**
+ * Zod schema for field definitions using a discriminated union on "type".
+ * Supports recursive nesting via z.lazy for Object fields and Array items.
+ */
+declare const fieldDefinitionSchema: z.ZodType<FieldDefinition>;
+/**
+ * Zod schema for the complete endpoint definition format.
+ */
+declare const endpointDefinitionSchema: z.ZodObject<{
+  version: z.ZodLiteral<"1.0">;
+  tableName: z.ZodString;
+  catalog: z.ZodString;
+  schema: z.ZodString;
+  fields: z.ZodArray<z.ZodType<FieldDefinition, unknown, z.core.$ZodTypeInternals<FieldDefinition, unknown>>>;
+  mutation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    loadStrategy: z.ZodEnum<{
+      full_load: "full_load";
+      full_load_append: "full_load_append";
+      append: "append";
+    }>;
+    basePath: z.ZodString;
+  }, z.core.$strip>]>>;
+}, z.core.$strip>;
+type EndpointDefinitionFormat = z.infer<typeof endpointDefinitionSchema>;
+/**
+ * Checks for duplicate field names at the same nesting level within a list of field definitions.
+ * Returns an array of objects describing each duplicate found, including the field name and path.
+ */
+declare function findDuplicateFieldNames(fields: FieldDefinition[], path?: string[]): {
+  name: string;
+  path: string[];
+}[];
+//#endregion
+export { ArrayItemDefinition, EndpointDefinitionFormat, FieldDefinition, FieldOptions, FieldValidation, LoadStrategy, MutationConfig, PrimitiveType, endpointDefinitionSchema, fieldDefinitionSchema, fieldNamePattern, fieldOptionsSchema, fieldValidationSchema, findDuplicateFieldNames, loadStrategies, metadataFieldPattern, mutationConfigSchema, mutationSchema, primitiveTypes };

package/dist/endpoint-schema.mjs

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=/^[a-zA-Z_][a-zA-Z0-9_]{0,63}$/u,n=/^[a-zA-Z_][a-zA-Z0-9_]{0,127}$/u,r=[`full_load`,`full_load_append`,`append`],i=e.object({loadStrategy:e.enum(r),basePath:e.string().min(1)}),a=e.union([e.literal(!1),i]),o=[`String`,`Integer`,`Float`,`Boolean`,`Date`,`DateTime`],s=e.union([e.object({type:e.literal(`email`)}),e.object({type:e.literal(`url`)}),e.object({type:e.literal(`uuid`)}),e.object({type:e.literal(`min`),value:e.number()}),e.object({type:e.literal(`max`),value:e.number()}),e.object({type:e.literal(`regex`),pattern:e.string()})]),c=e.object({required:e.boolean().optional(),validations:e.array(s).optional()}),l=e.lazy(()=>e.discriminatedUnion(`type`,[e.object({name:e.string().regex(t),type:e.literal(`String`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Integer`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Float`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Boolean`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Date`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`DateTime`),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Object`),fields:e.array(l).min(1),options:c.optional()}),e.object({name:e.string().regex(t),type:e.literal(`Array`),items:e.union([e.object({type:e.enum(o)}),e.object({type:e.literal(`Object`),fields:e.array(l).min(1)})]),options:c.optional()})])),u=e.object({version:e.literal(`1.0`),tableName:e.string().regex(n),catalog:e.string().regex(n),schema:e.string().regex(n),fields:e.array(l),mutation:a.optional()});function d(e,t=[]){let n=[],r=new Set;for(let i of e)r.has(i.name)?n.push({name:i.name,path:t}):r.add(i.name),i.type===`Object`&&i.fields&&n.push(...d(i.fields,[...t,i.name])),i.type===`Array`&&i.items?.type===`Object`&&i.items.fields&&n.push(...d(i.items.fields,[...t,i.name,`items`]));return n}export{u as endpointDefinitionSchema,l as fieldDefinitionSchema,t as fieldNamePattern,c as fieldOptionsSchema,s as fieldValidationSchema,d as findDuplicateFieldNames,r as loadStrategies,n as metadataFieldPattern,i as mutationConfigSchema,a as mutationSchema,o as primitiveTypes};

package/dist/graphql-schema.d.mts

@@ -42,29 +42,52 @@ type FieldDefinitionResponse = {
   subModel: JSONSchema7;
   filter: boolean;
 };
+/**
+ * Parameters for generateModel.
+ */
+interface GenerateModelProps {
+  /** The JSON Schema source definition to generate a model from. */
+  source: JSONSchema7;
+  /** The name of the model being generated. */
+  name: string;
+  /** The parent model name for nested models. */
+  parent?: string;
+  /** Accumulated model definitions. */
+  models: Record<string, ModelResponse>;
+  /** Whether this is the root model definition. */
+  isRoot: boolean;
+}
+/**
+ * Generates a GraphQL model definition from JSON Schema.
+ */
 declare const generateModel: ({
   source,
   name,
   parent,
   models,
   isRoot
-}: {
-  source: JSONSchema7;
-  name: string;
+}: GenerateModelProps) => Record<string, ModelResponse>;
+/**
+ * Parameters for generateFieldDefinition.
+ */
+interface GenerateFieldDefinitionProps {
+  /** The sanitized field name. */
+  fieldName: string;
+  /** The original raw field name from the schema. */
+  rawFieldName: string;
+  /** The JSON Schema definition for this field. */
+  fieldDefinition: JSONSchema7;
+  /** The parent model name for generating nested type references. */
   parent?: string;
-  models: Record<string, ModelResponse>;
-  isRoot: boolean;
-}) => Record<string, ModelResponse>;
+}
+/**
+ * Generates field definitions for a single model property.
+ */
 declare const generateFieldDefinition: ({
   fieldName,
   rawFieldName,
   fieldDefinition,
   parent
-}: {
-  fieldName: string;
-  rawFieldName: string;
-  fieldDefinition: JSONSchema7;
-  parent?: string;
-}) => FieldDefinitionResponse;
+}: GenerateFieldDefinitionProps) => FieldDefinitionResponse;
 //#endregion
-export { CurrentModelResponse, FieldDefinitionResponse, FilterFieldInput, ModelResponse, generateFieldDefinition, generateModel };
+export { CurrentModelResponse, FieldDefinitionResponse, FilterFieldInput, GenerateFieldDefinitionProps, GenerateModelProps, ModelResponse, generateFieldDefinition, generateModel };

package/dist/hive-table.d.mts

@@ -13,28 +13,56 @@ type ParquetField = Record<string, string | [string, ParquetField] | [string, {
     element: ParquetField;
   };
 }]>;
+/**
+ * Parameters for generateSqlSchema.
+ */
+interface GenerateSqlSchemaProps {
+  /** The JSON Schema property definitions to generate SQL columns from. */
+  definition: Record<string, SchemaDefinition>;
+}
+/**
+ * Generates SQL column definitions from parsed columns.
+ */
 declare function generateSqlSchema({
   definition
-}: {
-  definition: Record<string, SchemaDefinition>;
-}): SqlFieldDefinition[];
+}: GenerateSqlSchemaProps): SqlFieldDefinition[];
+/**
+ * Parameters for parquetTransformer.
+ */
+interface ParquetTransformerProps {
+  /** The JSON Schema property definitions to transform for Parquet format. */
+  definition: Record<string, JSONSchema7>;
+}
+/**
+ * Transforms column definitions for Parquet format.
+ */
 declare function parquetTransformer({
   definition
-}: {
-  definition: Record<string, JSONSchema7>;
-}): ParquetField;
+}: ParquetTransformerProps): ParquetField;
+/**
+ * Parameters for generateCreateTableStatement.
+ */
+interface GenerateCreateTableStatementProps {
+  /** The Hive schema name. */
+  schema: string;
+  /** The table name. */
+  tableName: string;
+  /** The S3 bucket name for external storage. */
+  bucketName: string;
+  /** The path within the S3 bucket. */
+  bucketPath: string;
+  /** The JSON Schema property definitions for table columns. */
+  definition: Record<string, SchemaDefinition>;
+}
+/**
+ * Generates a full CREATE TABLE DDL statement.
+ */
 declare function generateCreateTableStatement({
   schema,
   tableName,
   bucketName,
   bucketPath,
   definition
-}: {
-  schema: string;
-  tableName: string;
-  bucketName: string;
-  bucketPath: string;
-  definition: Record<string, SchemaDefinition>;
-}): string;
+}: GenerateCreateTableStatementProps): string;
 //#endregion
-export { generateCreateTableStatement, generateSqlSchema, parquetTransformer };
+export { GenerateCreateTableStatementProps, GenerateSqlSchemaProps, ParquetTransformerProps, generateCreateTableStatement, generateSqlSchema, parquetTransformer };

package/dist/json-schema.d.mts

@@ -1,7 +1,24 @@
+import { FieldDefinition } from "./endpoint-schema.mjs";
 import { t as JSONSchema7 } from "./index-CGZiTFRE.mjs";
 import { JSONType } from "json-column-parser/lib/common/types/type.common";
 
 //#region src/json-schema.d.ts
 declare function generateJsonSchema(parsedColumns: Record<string, JSONType>): JSONSchema7;
+/**
+ * Converts an array of FieldDefinitions to a complete JSON Schema Draft-07 document.
+ *
+ * The root schema has `$schema`, `type: "object"`, `properties`, and `additionalProperties: false`.
+ * Each field is recursively mapped according to the type mapping rules:
+ * - String → {type: "string"}
+ * - Integer → {type: "integer"}
+ * - Float → {type: "number"}
+ * - Boolean → {type: "boolean"}
+ * - Date → {type: "string", format: "date"}
+ * - DateTime → {type: "string", format: "date-time"}
+ * - Object → {type: "object", properties: {...}, additionalProperties: false}
+ * - Array (primitive) → {type: "array", items: {primitive schema}}
+ * - Array (object) → {type: "array", items: {type: "object", properties: {...}, additionalProperties: false}}
+ */
+declare function generateJsonSchemaFromFields(fields: FieldDefinition[]): JSONSchema7;
 //#endregion
-export { generateJsonSchema };
+export { generateJsonSchema, generateJsonSchemaFromFields };

package/dist/json-schema.mjs

@@ -1 +1 @@
-import{isObject as e}from"@lakeql/helpers/object-helper";import{createRegExp as t,global as n,not as r}from"magic-regexp";function i(e){return{$schema:`https://json-schema.org/draft-07/schema#`,...s(e),additionalProperties:!1}}function a(e){let i=t(r.letter,[n]),a=e.toString().replace(i,``);switch(a){case`varchar`:return{type:`string`};case`decimal`:case`double`:case`float`:return{type:`number`};case`integer`:case`bigint`:return{type:`integer`};case`boolean`:return{type:`boolean`};case`timestamp`:return{format:`date-time`,type:`string`};case`date`:return{format:`date`,type:`string`};default:throw Error(`Type ${a.toString()} is unknown.`)}}function o(t){if(t.length>1)throw Error("We expect that an array has only one element ( e.g. a primitive like `varchar` or an object like `row()`.");if(Array.isArray(t[0]))throw TypeError(`We currently do not support 'array of array'. Feel free to raise an issue.`);if(typeof t[0]==`string`)return{items:a(t[0]),type:`array`};if(e(t[0]))return{items:s(t[0]),type:`array`};throw Error("Unexpected case in `json-generator.handleArray`")}function s(t){let n={additionalProperties:!1,properties:{},type:`object`};for(let[r,i]of Object.entries(t)){if(typeof i==`string`)try{n.properties[r]=a(i)}catch(e){console.log(e)}if(Array.isArray(i))try{n.properties[r]=o(i)}catch(e){console.log(e)}if(e(i))try{n.properties[r]=s(i)}catch(e){console.log(e)}}return n}export{i as generateJsonSchema};
+import{isObject as e}from"@lakeql/helpers/object-helper";import{createRegExp as t,global as n,not as r}from"magic-regexp";function i(e){return{$schema:`https://json-schema.org/draft-07/schema#`,...s(e),additionalProperties:!1}}function a(e){let i=t(r.letter,[n]),a=e.toString().replace(i,``);switch(a){case`varchar`:return{type:`string`};case`decimal`:case`double`:case`float`:return{type:`number`};case`integer`:case`bigint`:return{type:`integer`};case`boolean`:return{type:`boolean`};case`timestamp`:return{format:`date-time`,type:`string`};case`date`:return{format:`date`,type:`string`};default:throw Error(`Type ${a.toString()} is unknown.`)}}function o(t){if(t.length>1)throw Error("We expect that an array has only one element ( e.g. a primitive like `varchar` or an object like `row()`.");if(Array.isArray(t[0]))throw TypeError(`We currently do not support 'array of array'. Feel free to raise an issue.`);if(typeof t[0]==`string`)return{items:a(t[0]),type:`array`};if(e(t[0]))return{items:s(t[0]),type:`array`};throw Error("Unexpected case in `json-generator.handleArray`")}function s(t){let n={additionalProperties:!1,properties:{},type:`object`};for(let[r,i]of Object.entries(t)){if(typeof i==`string`)try{n.properties[r]=a(i)}catch(e){console.log(e)}if(Array.isArray(i))try{n.properties[r]=o(i)}catch(e){console.log(e)}if(e(i))try{n.properties[r]=s(i)}catch(e){console.log(e)}}return n}function c(e){switch(e){case`String`:return{type:`string`};case`Integer`:return{type:`integer`};case`Float`:return{type:`number`};case`Boolean`:return{type:`boolean`};case`Date`:return{type:`string`,format:`date`};case`DateTime`:return{type:`string`,format:`date-time`};default:return{type:`string`}}}function l(e){return e.type===`Object`&&e.fields?{type:`object`,properties:d(e.fields),additionalProperties:!1}:c(e.type)}function u(e){switch(e.type){case`Object`:return{type:`object`,properties:d(e.fields??[]),additionalProperties:!1};case`Array`:return{type:`array`,items:e.items?l(e.items):{type:`string`}};default:return c(e.type)}}function d(e){let t={};for(let n of e)t[n.name]=u(n);return t}function f(e){return{$schema:`https://json-schema.org/draft-07/schema#`,type:`object`,properties:d(e),additionalProperties:!1}}export{i as generateJsonSchema,f as generateJsonSchemaFromFields};

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@lakeql/schema-generator",
-  "version": "0.1.1",
+  "version": "0.2.0",
+  "description": "Generates GraphQL schemas, Hive table definitions, and JSON schemas from Trino metadata",
+  "keywords": [
+    "codegen",
+    "graphql",
+    "hive",
+    "json-schema",
+    "lakeql",
+    "schema"
+  ],
   "homepage": "https://lakeql.dev",
   "license": "Apache-2.0",
   "author": {
@@ -24,6 +33,10 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./endpoint-schema": {
+      "types": "./dist/endpoint-schema.d.mts",
+      "import": "./dist/endpoint-schema.mjs"
+    },
     "./graphql-schema": {
       "types": "./dist/graphql-schema.d.mts",
       "import": "./dist/graphql-schema.mjs"
@@ -41,12 +54,14 @@
     "kysely": "0.29.2",
     "lodash-es": "4.18.1",
     "magic-regexp": "0.11.0",
-    "@lakeql/helpers": "0.1.1"
+    "zod": "4.4.3",
+    "@lakeql/helpers": "0.1.2"
   },
   "devDependencies": {
     "@types/json-schema": "7.0.15",
     "@types/lodash-es": "4.17.12",
     "@types/node": "24.13.2",
+    "fast-check": "^4.8.0",
     "json-column-parser": "2.0.0",
     "tsdown": "0.22.2",
     "typescript": "6.0.3",
@@ -59,6 +74,7 @@
     "clean:cache": "git clean -xdf .cache .turbo",
     "clean:dist": "git clean -xdf dist",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }