pocketbase-zod-schema 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.0.1](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v1.0.0...pocketbase-zod-schema-v1.0.1) (2026-07-28)
+
+
+### Bug Fixes
+
+* bug fixes for schema ([7007f4d](https://github.com/dastron/pocketbase-zod-schema/commit/7007f4dda37bef732cfcdb126e1a8dba79ece120))
+* bug fixes for schema ([17bd233](https://github.com/dastron/pocketbase-zod-schema/commit/17bd23392a0455ff5b94d8cb54b30fbdcad7ffbc))
+
 ## [1.0.0](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v0.7.2...pocketbase-zod-schema-v1.0.0) (2026-07-28)
 
 

package/README.md

@@ -212,7 +212,7 @@ The library provides explicit field helper functions for all PocketBase field ty
 | `SelectField(values, options?)` | select | Single or multiple select field | `status: SelectField(["draft", "published"])` |
 | `FileField(options?)` | file | Single file upload field | `avatar: FileField({ mimeTypes: ["image/*"] })` |
 | `FilesField(options?)` | file | Multiple file upload field | `images: FilesField({ maxSelect: 5 })` |
-| `JSONField(schema?)` | json | JSON field with optional schema | `metadata: JSONField()` |
+| `JSONField(schema?, options?)` | json | JSON field with optional schema and size cap | `metadata: JSONField({ maxSize: "5M" })` |
 | `GeoPointField()` | geoPoint | Geographic coordinates field | `location: GeoPointField()` |
 | `RelationField(config)` | relation | Single relation field | `author: RelationField({ collection: "users" })` |
 | `RelationsField(config)` | relation | Multiple relation field | `tags: RelationsField({ collection: "tags" })` |
@@ -278,8 +278,11 @@ The library provides explicit field helper functions for all PocketBase field ty
 - `maxSelect?: number` - Maximum number of files allowed
 - Returns: `z.ZodType<string[], (File | string)[]>`
 
-**JSONField(schema?)**
+**JSONField(schema?, options?)**
 - `schema?: z.ZodTypeAny` - Optional Zod schema for JSON structure validation
+- `options?.maxSize?: number | "5M"` - Maximum serialized size, in bytes or with a `K`/`M`/`G`
+  suffix. PocketBase applies a 1MB default when unset, so larger payloads must set it. Either
+  argument may be passed alone: `JSONField({ maxSize: "5M" })`
 - Returns: `T | z.ZodRecord<z.ZodString, z.ZodAny>`
 
 **GeoPointField()**

package/dist/cli/index.cjs

@@ -496,6 +496,7 @@ var CollectionIdRegistry = class {
 };
 
 // src/migration/rule-validator.ts
+var BACK_RELATION_SEGMENT = /^[a-zA-Z_][a-zA-Z0-9_]*_via_[a-zA-Z_][a-zA-Z0-9_]*$/;
 var RuleValidator = class {
   fields;
   collectionName;
@@ -571,7 +572,7 @@ var RuleValidator = class {
   /**
    * Extract field references from expression
    *
-   * Matches field names that are not @request references.
+   * Matches field names that are not @request or @collection references.
    * Handles dot notation for relations: user.email, post.author.name
    *
    * @param expression - The rule expression
@@ -581,6 +582,7 @@ var RuleValidator = class {
     const refs = [];
     let cleaned = expression2.replace(/"[^"]*"/g, '""').replace(/'[^']*'/g, "''");
     cleaned = cleaned.replace(/@request\.[a-zA-Z_][a-zA-Z0-9_.]*/g, "");
+    cleaned = cleaned.replace(/@collection\.[a-zA-Z_][a-zA-Z0-9_.]*/g, "");
     const fieldPattern = /(?:^|[^@\w])([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)(?=[^a-zA-Z0-9_.]|$)/g;
     let match;
     while ((match = fieldPattern.exec(cleaned)) !== null) {
@@ -601,12 +603,26 @@ var RuleValidator = class {
     const keywords = ["true", "false", "null", "AND", "OR", "NOT", "LIKE", "IN"];
     return keywords.includes(word.toUpperCase());
   }
+  /**
+   * Check whether a path segment is a back-relation rather than a field
+   *
+   * A declared field wins: a collection may legitimately contain a field
+   * literally named `foo_via_bar`, and it should be validated as one.
+   *
+   * @param segment - A single dot-separated path segment
+   * @returns True if the segment should be treated as a back-relation
+   */
+  isBackRelationSegment(segment) {
+    return !this.fields.has(segment) && BACK_RELATION_SEGMENT.test(segment);
+  }
   /**
    * Validate a field reference exists in schema
    *
-   * Checks if the root field exists and validates relation chains.
-   * For nested references, warns about potential issues since we can't
-   * validate across collections without loading related schemas.
+   * Only the root of the path is checked — the validator holds a single
+   * collection's fields, so anything past the first hop belongs to another
+   * collection and is accepted as-is. A root back-relation
+   * (`Members_via_WorkspaceRef.UserRef`) has no local field to check against
+   * either, so it is accepted too; PocketBase resolves it at runtime.
    *
    * @param fieldRef - The field reference to validate (e.g., "user" or "user.email")
    * @param result - The validation result to update
@@ -614,6 +630,9 @@ var RuleValidator = class {
   validateFieldReference(fieldRef, result) {
     const parts = fieldRef.split(".");
     const rootField = parts[0];
+    if (this.isBackRelationSegment(rootField)) {
+      return;
+    }
     if (!this.fields.has(rootField)) {
       result.errors.push(`Field '${rootField}' does not exist in collection '${this.collectionName}'`);
       result.valid = false;
@@ -624,10 +643,6 @@ var RuleValidator = class {
       if (field.type !== "relation") {
         result.errors.push(`Field '${rootField}' is not a relation field, cannot access nested property '${parts[1]}'`);
         result.valid = false;
-      } else {
-        result.warnings.push(
-          `Nested field reference '${fieldRef}' - ensure target collection has field '${parts.slice(1).join(".")}'`
-        );
       }
     }
   }
@@ -1016,14 +1031,35 @@ function isMultipleRelationField(fieldName, zodType) {
   const hasUppercase = /[A-Z]/.test(fieldName);
   return hasUppercase;
 }
+var REFERENCE_NAME_SUFFIXES = /* @__PURE__ */ new Set([
+  "ref",
+  "refs",
+  "id",
+  "ids",
+  "uid",
+  "uids",
+  "uuid",
+  "uuids",
+  "fk",
+  "fks",
+  "pk",
+  "pks"
+]);
 function resolveTargetCollection(fieldName) {
   const matches = fieldName.match(/[A-Z][a-z]+/g);
   if (!matches || matches.length === 0) {
     return pluralize(fieldName);
   }
   const entityName = matches[matches.length - 1];
+  if (REFERENCE_NAME_SUFFIXES.has(entityName.toLowerCase())) {
+    throw new Error(buildUnresolvableTargetMessage(fieldName, entityName, matches.slice(0, -1)));
+  }
   return pluralize(entityName);
 }
+function buildUnresolvableTargetMessage(fieldName, suffix, leadingSegments) {
+  const likelyTarget = leadingSegments.length > 0 ? pluralize(leadingSegments.join("")) : "TargetCollection";
+  return `Cannot infer the relation target for field "${fieldName}": the name ends in "${suffix}", which marks it as a reference without naming the collection it points at. Declare the target explicitly, e.g. ${fieldName}: RelationField({ collection: "${likelyTarget}" }).`;
+}
 function isRelationField(fieldName, zodType) {
   return isSingleRelationField(fieldName, zodType) || isMultipleRelationField(fieldName, zodType);
 }
@@ -1296,6 +1332,39 @@ function filterSupportedFieldOptions(fieldType, options) {
   }
   return Object.keys(filtered).length > 0 ? filtered : void 0;
 }
+var OPTION_UNSET_VALUES = {
+  pattern: "",
+  autogeneratePattern: "",
+  cost: 0,
+  maxSize: 0,
+  maxSelect: 0,
+  minSelect: 0,
+  primaryKey: false,
+  onlyInt: false,
+  noDecimal: false,
+  convertURLs: false,
+  protected: false,
+  hidden: false,
+  presentable: false,
+  system: false,
+  values: [],
+  mimeTypes: [],
+  thumbs: [],
+  exceptDomains: [],
+  onlyDomains: []
+};
+function getFieldOptionUnsetValue(fieldType, key) {
+  if (key === "min" || key === "max") {
+    if (fieldType === "number") {
+      return null;
+    }
+    if (fieldType === "date") {
+      return "";
+    }
+    return 0;
+  }
+  return OPTION_UNSET_VALUES[key];
+}
 function dedentSql(value) {
   const lines = value.replace(/\r\n/g, "\n").split("\n");
   while (lines.length > 0 && lines[0].trim() === "") {
@@ -1661,7 +1730,8 @@ function buildFieldDefinition(fieldName, zodType) {
     } else {
       required2 = isFieldRequired(zodType);
     }
-    const { required: _required, ...options2 } = fieldMetadata.options || {};
+    const { required: _required, ...metadataOptions } = fieldMetadata.options || {};
+    const options2 = { ...extractChainedFieldOptions(fieldMetadata.type, unwrappedType), ...metadataOptions };
     const fieldDef2 = {
       name: fieldName,
       id: generateFieldId(fieldMetadata.type, fieldName),
@@ -1737,6 +1807,13 @@ function buildFieldDefinition(fieldName, zodType) {
   fieldDef.options = filterSupportedFieldOptions(fieldDef.type, fieldDef.options);
   return fieldDef;
 }
+var TYPES_READING_CHAINED_VALIDATORS = /* @__PURE__ */ new Set(["text", "password", "number", "select", "file"]);
+function extractChainedFieldOptions(fieldType, unwrappedType) {
+  if (!TYPES_READING_CHAINED_VALIDATORS.has(fieldType)) {
+    return {};
+  }
+  return extractFieldOptions(unwrappedType);
+}
 function convertZodSchemaToCollectionSchema(collectionName, zodSchema) {
   const rawFields = extractFieldDefinitions(zodSchema);
   const explicitType = extractCollectionTypeFromSchema(zodSchema);
@@ -2057,12 +2134,26 @@ var FIELD_CONSTRUCTORS = {
   AutodateField,
   PasswordField
 };
-function generateRuntimeFieldId(type) {
-  let digits = "";
-  for (let i = 0; i < 10; i++) {
-    digits += Math.floor(Math.random() * 10).toString();
+var crcTable = null;
+function crc32(input) {
+  if (!crcTable) {
+    crcTable = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+      let c = i;
+      for (let bit = 0; bit < 8; bit++) {
+        c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+      }
+      crcTable[i] = c >>> 0;
+    }
+  }
+  let crc = 4294967295;
+  for (const byte of new TextEncoder().encode(input)) {
+    crc = crcTable[(crc ^ byte) & 255] ^ crc >>> 8;
   }
-  return `${type || "field"}${digits}`;
+  return (crc ^ 4294967295) >>> 0;
+}
+function generateRuntimeFieldId(type, name) {
+  return `${type || "field"}${crc32(name)}`;
 }
 
 // src/migration/engine/fields-list.ts
@@ -2070,22 +2161,19 @@ var FieldsList = class {
   items = [];
   constructor(fields) {
     if (Array.isArray(fields)) {
-      for (const field of fields) {
-        this.items.push(field instanceof Field ? field : new Field(field));
-      }
+      this.add(...fields);
     }
   }
   get length() {
     return this.items.length;
   }
   /**
-   * Appends fields; a field whose id matches an existing entry replaces it
-   * in place (position preserved), matching PocketBase upsert semantics.
+   * Appends fields; a field that matches an existing entry replaces it in
+   * place (position preserved), matching PocketBase upsert semantics.
    */
   add(...fields) {
     for (const raw of fields) {
-      const field = raw instanceof Field ? raw : new Field(raw);
-      const existing = this.indexOfId(field.id);
+      const { field, existing } = this.resolveIncoming(raw);
       if (existing >= 0) {
         this.items[existing] = field;
       } else {
@@ -2094,15 +2182,14 @@ var FieldsList = class {
     }
   }
   /**
-   * Inserts fields at a position. A field with an already-present id is
+   * Inserts fields at a position. A field matching an already-present entry is
    * moved: the old entry is removed first, then the field is inserted at
    * the requested position.
    */
   addAt(position, ...fields) {
     let insertAt = Math.max(0, Math.min(position, this.items.length));
     for (const raw of fields) {
-      const field = raw instanceof Field ? raw : new Field(raw);
-      const existing = this.indexOfId(field.id);
+      const { field, existing } = this.resolveIncoming(raw);
       if (existing >= 0) {
         this.items.splice(existing, 1);
         if (existing < insertAt) {
@@ -2114,6 +2201,36 @@ var FieldsList = class {
       insertAt++;
     }
   }
+  /**
+   * Materializes an incoming field and locates the entry it replaces.
+   *
+   * PocketBase's rule (documented on `FieldsList.Add` in types.d.ts): match by
+   * id, "or by their name if the new field doesn't have an explicit id", and
+   * autogenerate a missing id from the name. Matching by id alone turns the
+   * idiomatic `fields.add(new TextField({name: "title", max: 500}))` — no id,
+   * meant to rewrite `title` — into a second field also called `title`, which
+   * PocketBase would reject on save but the engine used to accept, corrupting
+   * the reconstructed state.
+   *
+   * On a name match the *existing* id is kept rather than replaced with the
+   * derived one. For a collection PocketBase authored the two are identical
+   * (its auto-ids already are `<type><crc32(name)>`); they diverge only when
+   * the stored field carries a hand-assigned id, and there preserving it keeps
+   * a later `removeById`/`getById` in the same migration working.
+   */
+  resolveIncoming(raw) {
+    const field = raw instanceof Field ? raw : new Field(raw);
+    const hasExplicitId = typeof field.id === "string" && field.id !== "";
+    if (hasExplicitId) {
+      return { field, existing: this.indexOfId(field.id) };
+    }
+    const existing = this.items.findIndex((f) => f.name === field.name);
+    field.id = existing >= 0 ? this.items[existing].id : generateRuntimeFieldId(
+      typeof field.type === "string" ? field.type : "",
+      typeof field.name === "string" ? field.name : ""
+    );
+    return { field, existing };
+  }
   removeById(id) {
     const index = this.indexOfId(id);
     if (index >= 0) {
@@ -2126,12 +2243,18 @@ var FieldsList = class {
       this.items.splice(index, 1);
     }
   }
+  /**
+   * Null rather than undefined for a miss: these two return a Go `Field`
+   * interface, and goja surfaces a nil interface to JavaScript as `null`. A
+   * migration written as `if (collection.fields.getByName("x") === null)` has
+   * to take the same branch here as it does in production.
+   */
   getById(id) {
     const index = this.indexOfId(id);
-    return index >= 0 ? this.items[index] : void 0;
+    return index >= 0 ? this.items[index] : null;
   }
   getByName(name) {
-    return this.items.find((f) => f.name === name);
+    return this.items.find((f) => f.name === name) ?? null;
   }
   at(index) {
     return this.items.at(index);
@@ -2156,9 +2279,14 @@ var FieldsList = class {
     this.items = [];
     this.add(...fields);
   }
-  /** Plain objects, in order */
+  /**
+   * Plain objects, in order — copied deeply, so option arrays like a select
+   * field's `values` are not shared with the live list. A shallow spread let a
+   * snapshot handed to the diff engine alias engine state, where an in-place
+   * sort or push downstream would silently rewrite the collection it came from.
+   */
   serialize() {
-    return this.items.map((field) => ({ ...field }));
+    return this.items.map((field) => copyPlainData({ ...field }));
   }
   indexOfId(id) {
     if (typeof id !== "string" || id === "") {
@@ -2167,6 +2295,22 @@ var FieldsList = class {
     return this.items.findIndex((f) => f.id === id);
   }
 };
+function copyPlainData(value) {
+  if (Array.isArray(value)) {
+    return value.map(copyPlainData);
+  }
+  if (value !== null && typeof value === "object" && !(value instanceof Date)) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype || prototype === null) {
+      const copy = {};
+      for (const [key, entry] of Object.entries(value)) {
+        copy[key] = copyPlainData(entry);
+      }
+      return copy;
+    }
+  }
+  return value;
+}
 
 // src/migration/engine/collection.ts
 var AUTH_SYSTEM_FIELDS = [
@@ -3585,6 +3729,13 @@ function createInertStub(name, options, warn) {
       if (prop === "then") {
         return void 0;
       }
+      if (prop === "length") {
+        return 0;
+      }
+      if (prop === Symbol.iterator) {
+        return function* emptyIterator() {
+        };
+      }
       if (typeof prop === "symbol") {
         return void 0;
       }
@@ -3643,7 +3794,10 @@ var SimulatedAppImpl = class {
     ensureAuthSystemFields(collection);
     for (const field of collection.fields) {
       if (typeof field.id !== "string" || field.id === "") {
-        field.id = generateRuntimeFieldId(typeof field.type === "string" ? field.type : "");
+        field.id = generateRuntimeFieldId(
+          typeof field.type === "string" ? field.type : "",
+          typeof field.name === "string" ? field.name : ""
+        );
       }
     }
     this.store.upsert(collection);
@@ -4415,40 +4569,23 @@ function areValuesEqual(a, b) {
   }
   return a === b;
 }
-var OPTION_ZERO_VALUES = {
-  autogeneratePattern: "",
-  pattern: "",
-  primaryKey: false,
-  convertURLs: false,
-  cost: 0,
-  hidden: false,
-  presentable: false,
-  system: false
-};
 function normalizeOptionValue(key, value, fieldType) {
-  if (OPTION_ZERO_VALUES[key] !== void 0 && value === OPTION_ZERO_VALUES[key]) {
+  if (value === null || value === void 0) {
     return void 0;
   }
-  if (key === "maxSelect" && value === 1 && (fieldType === "select" || fieldType === "file")) {
+  const unsetValue = getFieldOptionUnsetValue(fieldType, key);
+  if (unsetValue !== void 0 && areValuesEqual(value, unsetValue)) {
     return void 0;
   }
-  if (key === "maxSize" && value === 0 && fieldType === "file") {
+  if (key === "values" && fieldType === "select" && Array.isArray(value)) {
+    return [...value].sort();
+  }
+  if (key === "maxSelect" && value === 1 && (fieldType === "select" || fieldType === "file")) {
     return void 0;
   }
   if (key === "min" && value === 1 && fieldType === "number") {
     return void 0;
   }
-  if (fieldType === "file") {
-    if (key === "mimeTypes" && Array.isArray(value) && value.length === 0) {
-      return void 0;
-    }
-    if (key === "thumbs" && Array.isArray(value) && value.length === 0) {
-      return void 0;
-    }
-    if (key === "protected" && value === false) {
-      return void 0;
-    }
-  }
   if (fieldType === "autodate") {
     if (key === "onCreate" && value === true) {
       return void 0;
@@ -5268,13 +5405,16 @@ function generateFieldModification(collectionName, modification, varName, isLast
   const lines = [];
   const collectionVar = varName || `collection_${collectionName}_${modification.fieldName}`;
   const fieldVar = `${collectionVar}_field`;
+  const fieldType = modification.newDefinition?.type ?? modification.currentDefinition?.type;
   lines.push(`  const ${collectionVar} = ${generateFindCollectionCode(collectionName, collectionIdMap)};`);
   lines.push(`  const ${fieldVar} = ${collectionVar}.fields.getByName("${modification.fieldName}");`);
   lines.push(``);
   for (const change of modification.changes) {
     if (change.property.startsWith("options.")) {
       const optionKey = change.property.replace("options.", "");
-      lines.push(`  ${fieldVar}.${optionKey} = ${formatValue(change.newValue)};`);
+      const newValue = change.newValue === void 0 ? getFieldOptionUnsetValue(fieldType, optionKey) : change.newValue;
+      const pbKey = fieldType === "number" && optionKey === "noDecimal" ? "onlyInt" : optionKey;
+      lines.push(`  ${fieldVar}.${pbKey} = ${formatValue(newValue)};`);
     } else if (change.property.startsWith("relation.")) {
       const relationKey = change.property.replace("relation.", "");
       if (relationKey === "collection") {