prisma-arktype 2.3.0 → 2.4.0

package/README.md

@@ -239,6 +239,7 @@ Control schema generation using annotations in your Prisma schema. All annotatio
 | `@prisma-arktype.input.hide` | Field | Hide from Create and Update input schemas |
 | `@prisma-arktype.create.input.hide` | Field | Hide from Create input schema only |
 | `@prisma-arktype.update.input.hide` | Field | Hide from Update input schema only |
+| `@prisma-arktype.schema="<schema>"` | Field | Custom ArkType schema (inline or external) |
 | `@prisma-arktype.typeOverwrite="<type>"` | Field | Override the generated ArkType type |
 
 ### Hide Fields/Models
@@ -301,6 +302,48 @@ model User {
 
 This allows you to use any ArkType type definition, including built-in refinements like `string.email`, `string.url`, `number.integer`, etc.
 
+### Custom Schemas
+
+Bring your own ArkType schemas for any field using `@prisma-arktype.schema`:
+
+```prisma
+model User {
+  id String @id
+
+  /// Inline schema for structured JSON
+  /// @prisma-arktype.schema="{ name: 'string', age: 'number' }"
+  profile Json
+
+  /// External schema from a file (named export)
+  /// @prisma-arktype.schema="../schemas/address:AddressSchema"
+  address Json
+
+  /// External schema (default export)
+  /// @prisma-arktype.schema="../schemas/config"
+  settings Json
+}
+```
+
+**Import Path Rules:**
+- Paths are relative to the generated validators directory
+- Named exports use colon syntax: `"path:ExportName"`
+- Default exports omit the colon: `"path"`
+- Works with ANY field type (not just Json)
+
+**Priority:** `schema` > `typeOverwrite` > default type mapping
+
+**Example external schema file** (`schemas/address.ts`):
+```typescript
+import { type } from "arktype";
+
+export const AddressSchema = type({
+  street: "string",
+  city: "string",
+  zipCode: "string",
+  country: "string",
+});
+```
+
 ## Type Mapping
 
 Prisma types are mapped to ArkType as follows:

package/dist/index.js

@@ -43,6 +43,9 @@ function isHiddenInputUpdate(annotation) {
 function isTypeOverwrite(annotation) {
   return annotation.type === "TYPE_OVERWRITE";
 }
+function isSchema(annotation) {
+  return annotation.type === "SCHEMA";
+}
 const annotationKeys = [
   {
     keys: ["@prisma-arktype.hide", "@prisma-arktype.hidden"],
@@ -66,9 +69,11 @@ const annotationKeys = [
     ],
     type: "HIDDEN_INPUT_UPDATE"
   },
-  { keys: ["@prisma-arktype.typeOverwrite"], type: "TYPE_OVERWRITE" }
+  { keys: ["@prisma-arktype.typeOverwrite"], type: "TYPE_OVERWRITE" },
+  { keys: ["@prisma-arktype.schema"], type: "SCHEMA" }
 ];
 const prismaArktypeTypeOverwriteRegex = /@prisma-arktype\.typeOverwrite=(.+)/;
+const prismaArktypeSchemaRegex = /@prisma-arktype\.schema="([^"]+)"/;
 function extractAnnotations(documentation) {
   const annotations = [];
   const descriptionLines = [];
@@ -78,18 +83,52 @@ function extractAnnotations(documentation) {
       for (const { keys, type } of annotationKeys) {
         for (const key of keys) {
           if (line.includes(key)) {
-            isAnnotation = true;
             if (type === "TYPE_OVERWRITE") {
               const match = line.match(prismaArktypeTypeOverwriteRegex);
               if (match && match[1]) {
+                isAnnotation = true;
                 annotations.push({
                   type: "TYPE_OVERWRITE",
                   value: match[1].trim()
                 });
-              } else {
-                throw new Error(`Invalid TYPE_OVERWRITE annotation: ${line}`);
+              }
+            } else if (type === "SCHEMA") {
+              const match = line.match(prismaArktypeSchemaRegex);
+              if (match && match[1]) {
+                isAnnotation = true;
+                const schemaValue = match[1].trim();
+                const isExternal = schemaValue.includes("/") || !(schemaValue.startsWith("{") || schemaValue.startsWith('"') || schemaValue.startsWith("'")) && schemaValue.includes(":") && // Ensure it's a module:export pattern, not object syntax like { key: value }
+                !schemaValue.includes(" ") && !schemaValue.includes(",");
+                if (isExternal) {
+                  const colonIndex = schemaValue.indexOf(":");
+                  if (colonIndex > 0) {
+                    const path = schemaValue.substring(0, colonIndex).trim();
+                    const exportName = schemaValue.substring(colonIndex + 1).trim();
+                    annotations.push({
+                      type: "SCHEMA",
+                      value: schemaValue,
+                      isExternal: true,
+                      importPath: path,
+                      exportName
+                    });
+                  } else {
+                    annotations.push({
+                      type: "SCHEMA",
+                      value: schemaValue,
+                      isExternal: true,
+                      importPath: schemaValue
+                    });
+                  }
+                } else {
+                  annotations.push({
+                    type: "SCHEMA",
+                    value: schemaValue,
+                    isExternal: false
+                  });
+                }
               }
             } else {
+              isAnnotation = true;
               annotations.push({ type });
             }
             break;
@@ -186,7 +225,8 @@ function processPlain(models) {
       processedPlain.push({
         name: model.name,
         stringified: result.stringified,
-        enumDependencies: result.enumDependencies
+        enumDependencies: result.enumDependencies,
+        externalSchemaDependencies: result.externalSchemaDependencies
       });
     }
   }
@@ -202,6 +242,12 @@ function stringifyPlain(model, isInputCreate = false, isInputUpdate = false) {
   }
   const fields = [];
   const enumDependencies = [];
+  const externalSchemaDependencies = [];
+  function generateUniqueAlias(path, exportName, fieldName) {
+    const baseName = exportName || path.split("/").pop()?.replace(/\.(ts|js)$/, "") || "Schema";
+    const suffix = fieldName ? `_${fieldName}` : "";
+    return `${baseName}${suffix}`;
+  }
   for (const field of model.fields) {
     const {
       annotations: fieldAnnotations,
@@ -218,10 +264,36 @@ function stringifyPlain(model, isInputCreate = false, isInputUpdate = false) {
       if (config.ignoredKeysOnInputModels.includes(field.name)) continue;
       if (field.name.endsWith("Id") && field.relationName) continue;
     }
+    const schemaAnnotation = fieldAnnotations.find(isSchema);
     const typeOverwrite = fieldAnnotations.find(isTypeOverwrite);
     let fieldType;
     let fieldName = field.name;
-    if (typeOverwrite) {
+    if (schemaAnnotation) {
+      if (schemaAnnotation.isExternal) {
+        const alias = generateUniqueAlias(
+          schemaAnnotation.importPath,
+          schemaAnnotation.exportName,
+          field.name
+        );
+        if (!externalSchemaDependencies.some((d) => d.localAlias === alias)) {
+          const dependency = {
+            importPath: schemaAnnotation.importPath,
+            localAlias: alias
+          };
+          if (schemaAnnotation.exportName) {
+            dependency.exportName = schemaAnnotation.exportName;
+          }
+          externalSchemaDependencies.push(dependency);
+        }
+        fieldType = alias;
+      } else {
+        if (schemaAnnotation.value.trim().startsWith("{")) {
+          fieldType = schemaAnnotation.value;
+        } else {
+          fieldType = `"${schemaAnnotation.value}"`;
+        }
+      }
+    } else if (typeOverwrite) {
       fieldType = typeOverwrite.value;
     } else if (isPrimitivePrismaFieldType(field.type)) {
       fieldType = stringifyPrimitiveType(field.type);
@@ -235,16 +307,17 @@ function stringifyPlain(model, isInputCreate = false, isInputUpdate = false) {
     } else {
       continue;
     }
-    const isEnumType = field.kind === "enum" && !typeOverwrite;
+    const isEnumType = field.kind === "enum" && !typeOverwrite && !schemaAnnotation;
+    const isExternalSchema = schemaAnnotation?.isExternal === true;
     if (field.isList) {
-      if (isEnumType) {
+      if (isExternalSchema || isEnumType) {
         fieldType = `${fieldType}.array()`;
       } else {
         fieldType = `"${wrapPrimitiveWithArray(fieldType.slice(1, -1))}"`;
       }
     }
     if (!field.isRequired) {
-      if (isEnumType) {
+      if (isExternalSchema || isEnumType) {
         fieldType = `${fieldType}.or("null")`;
       } else {
         const inner = fieldType.slice(1, -1);
@@ -263,7 +336,8 @@ function stringifyPlain(model, isInputCreate = false, isInputUpdate = false) {
     stringified: `{
   ${fields.join(",\n  ")}
 }`,
-    enumDependencies
+    enumDependencies,
+    externalSchemaDependencies
   };
 }
 function stringifyPlainInputCreate(model) {
@@ -283,7 +357,8 @@ function processCreate(models) {
       processedCreate.push({
         name: model.name,
         stringified: result.stringified,
-        enumDependencies: result.enumDependencies
+        enumDependencies: result.enumDependencies,
+        externalSchemaDependencies: result.externalSchemaDependencies
       });
     }
   }
@@ -532,9 +607,7 @@ function processSelect(models) {
   Object.freeze(processedSelect);
 }
 function stringifySelect(model) {
-  const { hidden } = extractAnnotations(
-    model.documentation
-  );
+  const { hidden } = extractAnnotations(model.documentation);
   if (hidden) {
     return;
   }
@@ -560,7 +633,8 @@ function processUpdate(models) {
       processedUpdate.push({
         name: model.name,
         stringified: result.stringified,
-        enumDependencies: result.enumDependencies
+        enumDependencies: result.enumDependencies,
+        externalSchemaDependencies: result.externalSchemaDependencies
       });
     }
   }
@@ -569,6 +643,7 @@ function processUpdate(models) {
 
 const processedWhere = [];
 const processedWhereUnique = [];
+const extRegex = /\.(ts|js)$/;
 function processWhere(models) {
   for (const model of models) {
     const result = stringifyWhere(model);
@@ -576,7 +651,8 @@ function processWhere(models) {
       processedWhere.push({
         name: model.name,
         stringified: result.stringified,
-        enumDependencies: result.enumDependencies
+        enumDependencies: result.enumDependencies,
+        externalSchemaDependencies: result.externalSchemaDependencies
       });
     }
     const uniqueResult = stringifyWhereUnique(model);
@@ -584,7 +660,8 @@ function processWhere(models) {
       processedWhereUnique.push({
         name: model.name,
         stringified: uniqueResult.stringified,
-        enumDependencies: uniqueResult.enumDependencies
+        enumDependencies: uniqueResult.enumDependencies,
+        externalSchemaDependencies: uniqueResult.externalSchemaDependencies
       });
     }
   }
@@ -592,21 +669,51 @@ function processWhere(models) {
   Object.freeze(processedWhereUnique);
 }
 function stringifyWhere(model) {
-  const { hidden } = extractAnnotations(
-    model.documentation
-  );
+  const { hidden } = extractAnnotations(model.documentation);
   if (hidden) {
     return;
   }
   const fields = [];
   const enumDependencies = [];
+  const externalSchemaDependencies = [];
+  function generateUniqueAlias(path, exportName, fieldName) {
+    const baseName = exportName || path.split("/").pop()?.replace(extRegex, "") || "Schema";
+    const suffix = fieldName ? `_${fieldName}` : "";
+    return `${baseName}${suffix}`;
+  }
   for (const field of model.fields) {
     const { annotations: fieldAnnotations, hidden: fieldHidden } = extractAnnotations(field.documentation);
     if (fieldHidden) continue;
     if (field.kind === "object") continue;
+    const schemaAnnotation = fieldAnnotations.find(isSchema);
     const typeOverwrite = fieldAnnotations.find(isTypeOverwrite);
     let fieldType;
-    if (typeOverwrite) {
+    if (schemaAnnotation) {
+      if (schemaAnnotation.isExternal) {
+        const alias = generateUniqueAlias(
+          schemaAnnotation.importPath,
+          schemaAnnotation.exportName,
+          field.name
+        );
+        if (!externalSchemaDependencies.some((d) => d.localAlias === alias)) {
+          const dependency = {
+            importPath: schemaAnnotation.importPath,
+            localAlias: alias
+          };
+          if (schemaAnnotation.exportName) {
+            dependency.exportName = schemaAnnotation.exportName;
+          }
+          externalSchemaDependencies.push(dependency);
+        }
+        fieldType = alias;
+      } else {
+        if (schemaAnnotation.value.trim().startsWith("{")) {
+          fieldType = schemaAnnotation.value;
+        } else {
+          fieldType = `"${schemaAnnotation.value}"`;
+        }
+      }
+    } else if (typeOverwrite) {
       fieldType = typeOverwrite.value;
     } else if (isPrimitivePrismaFieldType(field.type)) {
       fieldType = stringifyPrimitiveType(field.type);
@@ -620,9 +727,10 @@ function stringifyWhere(model) {
     } else {
       continue;
     }
-    const isEnumType = field.kind === "enum" && !typeOverwrite;
+    const isEnumType = field.kind === "enum" && !typeOverwrite && !schemaAnnotation;
+    const isExternalSchema = schemaAnnotation?.isExternal === true;
     if (field.isList) {
-      if (isEnumType) {
+      if (isExternalSchema || isEnumType) {
         fieldType = `${fieldType}.array()`;
       } else {
         const inner = fieldType.slice(1, -1);
@@ -635,26 +743,57 @@ function stringifyWhere(model) {
     stringified: `{
   ${fields.join(",\n  ")}
 }`,
-    enumDependencies
+    enumDependencies,
+    externalSchemaDependencies
   };
 }
 function stringifyWhereUnique(model) {
-  const { hidden } = extractAnnotations(
-    model.documentation
-  );
+  const { hidden } = extractAnnotations(model.documentation);
   if (hidden) {
     return;
   }
   const fields = [];
   const enumDependencies = [];
+  const externalSchemaDependencies = [];
+  function generateUniqueAlias(path, exportName, fieldName) {
+    const baseName = exportName || path.split("/").pop()?.replace(extRegex, "") || "Schema";
+    const suffix = fieldName ? `_${fieldName}` : "";
+    return `${baseName}${suffix}`;
+  }
   for (const field of model.fields) {
     const { annotations: fieldAnnotations, hidden: fieldHidden } = extractAnnotations(field.documentation);
     if (fieldHidden) continue;
     if (field.kind === "object") continue;
     if (!(field.isId || field.isUnique)) continue;
+    const schemaAnnotation = fieldAnnotations.find(isSchema);
     const typeOverwrite = fieldAnnotations.find(isTypeOverwrite);
     let fieldType;
-    if (typeOverwrite) {
+    if (schemaAnnotation) {
+      if (schemaAnnotation.isExternal) {
+        const alias = generateUniqueAlias(
+          schemaAnnotation.importPath,
+          schemaAnnotation.exportName,
+          field.name
+        );
+        if (!externalSchemaDependencies.some((d) => d.localAlias === alias)) {
+          const dependency = {
+            importPath: schemaAnnotation.importPath,
+            localAlias: alias
+          };
+          if (schemaAnnotation.exportName) {
+            dependency.exportName = schemaAnnotation.exportName;
+          }
+          externalSchemaDependencies.push(dependency);
+        }
+        fieldType = alias;
+      } else {
+        if (schemaAnnotation.value.trim().startsWith("{")) {
+          fieldType = schemaAnnotation.value;
+        } else {
+          fieldType = `"${schemaAnnotation.value}"`;
+        }
+      }
+    } else if (typeOverwrite) {
       fieldType = typeOverwrite.value;
     } else if (isPrimitivePrismaFieldType(field.type)) {
       fieldType = stringifyPrimitiveType(field.type);
@@ -677,7 +816,8 @@ function stringifyWhereUnique(model) {
     stringified: `{
   ${fields.join(",\n  ")}
 }`,
-    enumDependencies
+    enumDependencies,
+    externalSchemaDependencies
   };
 }
 
@@ -700,6 +840,18 @@ function generateModelImports(modelDependencies) {
   ).join("\n")}
 `;
 }
+function generateExternalSchemaImports(externalSchemaDependencies) {
+  if (!externalSchemaDependencies || externalSchemaDependencies.length === 0) {
+    return "";
+  }
+  return `${externalSchemaDependencies.map((dep) => {
+    if (dep.exportName) {
+      return `import { ${dep.exportName} as ${dep.localAlias} } from "${dep.importPath}";`;
+    }
+    return `import ${dep.localAlias} from "${dep.importPath}";`;
+  }).join("\n")}
+`;
+}
 function mapAllModelsForWrite(processedEnums, processedPlain, processedRelations, processedWhere, processedWhereUnique, processedCreate, processedUpdate, processedRelationsCreate, processedRelationsUpdate, processedSelect, processedInclude, processedOrderBy) {
   const config = getConfig();
   const modelMap = /* @__PURE__ */ new Map();
@@ -713,7 +865,10 @@ function mapAllModelsForWrite(processedEnums, processedPlain, processedRelations
   }
   for (const model of processedPlain) {
     const enumImports = generateEnumImports(model.enumDependencies);
-    const content = `${arktypeImport}${enumImports}export const ${model.name}Plain = type(${model.stringified});
+    const externalSchemaImports = generateExternalSchemaImports(
+      model.externalSchemaDependencies
+    );
+    const content = `${arktypeImport}${enumImports}${externalSchemaImports}export const ${model.name}Plain = type(${model.stringified});
 `;
     modelMap.set(`${model.name}Plain`, content);
   }
@@ -742,25 +897,37 @@ export const ${plain.name} = ${plain.name}Plain;
   }
   for (const model of processedWhere) {
     const enumImports = generateEnumImports(model.enumDependencies);
-    const content = `${arktypeImport}${enumImports}export const ${model.name}Where = type(${model.stringified});
+    const externalSchemaImports = generateExternalSchemaImports(
+      model.externalSchemaDependencies
+    );
+    const content = `${arktypeImport}${enumImports}${externalSchemaImports}export const ${model.name}Where = type(${model.stringified});
 `;
     modelMap.set(`${model.name}Where`, content);
   }
   for (const model of processedWhereUnique) {
     const enumImports = generateEnumImports(model.enumDependencies);
-    const content = `${arktypeImport}${enumImports}export const ${model.name}WhereUnique = type(${model.stringified});
+    const externalSchemaImports = generateExternalSchemaImports(
+      model.externalSchemaDependencies
+    );
+    const content = `${arktypeImport}${enumImports}${externalSchemaImports}export const ${model.name}WhereUnique = type(${model.stringified});
 `;
     modelMap.set(`${model.name}WhereUnique`, content);
   }
   for (const model of processedCreate) {
     const enumImports = generateEnumImports(model.enumDependencies);
-    const content = `${arktypeImport}${enumImports}export const ${model.name}Create = type(${model.stringified});
+    const externalSchemaImports = generateExternalSchemaImports(
+      model.externalSchemaDependencies
+    );
+    const content = `${arktypeImport}${enumImports}${externalSchemaImports}export const ${model.name}Create = type(${model.stringified});
 `;
     modelMap.set(`${model.name}Create`, content);
   }
   for (const model of processedUpdate) {
     const enumImports = generateEnumImports(model.enumDependencies);
-    const content = `${arktypeImport}${enumImports}export const ${model.name}Update = type(${model.stringified});
+    const externalSchemaImports = generateExternalSchemaImports(
+      model.externalSchemaDependencies
+    );
+    const content = `${arktypeImport}${enumImports}${externalSchemaImports}export const ${model.name}Update = type(${model.stringified});
 `;
     modelMap.set(`${model.name}Update`, content);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-arktype",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Generate ArkType schemas from your Prisma schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,11 +55,11 @@
     "vitest": "^4.0.16"
   },
   "scripts": {
-    "build": "pkgroll",
+    "build": "pkgroll && prisma generate",
     "dev": "pkgroll --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "pnpm build && prisma generate && vitest run",
+    "test:e2e": "pnpm build && vitest run",
     "pretest": "pnpm build",
     "postinstall": "lefthook install",
     "lint": "biome check",