@classytic/repo-core 0.3.0 → 0.4.0

package/dist/schema/field-rules.d.mts

@@ -69,5 +69,45 @@ declare function isFieldUpdateAllowed(fieldName: string, options?: SchemaBuilder
  * walking the rules themselves.
  */
 declare function validateUpdateBody(body?: Record<string, unknown>, options?: SchemaBuilderOptions): ValidationResult;
+/**
+ * Merge constraint-style `fieldRules` into a generated schema bag in place.
+ *
+ * Operates on the three slots that carry property maps — `createBody`,
+ * `updateBody`, `response`. `listQuery` and `params` are skipped (their
+ * constraint vocabulary is owned by the kit's query parser).
+ *
+ * Existing constraints on a property always win — the merge only fills in
+ * gaps. Kits that already walk `fieldRules` during base-schema assembly
+ * can call this helper for free (the checks are no-ops when constraints
+ * already exist).
+ *
+ * Schema slot type is intentionally loose (`Record<string, unknown> | null
+ * | undefined`) so adapters can pass either an `OpenApiSchemas`-shaped bag
+ * or a kit-native bag without coercion.
+ */
+declare function mergeFieldRuleConstraints(schemas: Record<string, unknown> | null | undefined, schemaOptions?: SchemaBuilderOptions): void;
+/**
+ * Widen a JSON Schema property to also accept `null`.
+ *
+ * Handles the three ways a property can be typed:
+ *   - `type: 'string'`     → `type: ['string', 'null']`
+ *   - `type: [...]`        → append `'null'` if missing
+ *   - `anyOf: [...]`       → append `{ type: 'null' }` branch if missing
+ *
+ * **Enum interaction:** when the widened prop also carries `enum: [...]`,
+ * `null` is appended to the enum list too. AJV's `enum` keyword rejects
+ * values not in the list regardless of the widened `type`, so
+ * `{ type: ['string','null'], enum: ['a','b'] }` alone would still reject
+ * `null`. The fix is `enum: ['a','b', null]`. (The `anyOf` branch dodges
+ * this entirely — each branch scopes its own enum.)
+ *
+ * No-op when the schema already admits null (don't double-wrap) or has
+ * no `type` / `anyOf` anchor to widen (e.g. Mixed — already accepts null).
+ *
+ * Mutates in place — callers already treat the slot schema as owned.
+ * Exported so adapters that walk `fieldRules` inline can reuse the same
+ * widening logic.
+ */
+declare function applyNullable(prop: Record<string, unknown>): void;
 //#endregion
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody };

package/dist/schema/field-rules.mjs

@@ -126,5 +126,96 @@ function validateUpdateBody(body = {}, options = {}) {
 		violations
 	};
 }
+/**
+* Merge constraint-style `fieldRules` into a generated schema bag in place.
+*
+* Operates on the three slots that carry property maps — `createBody`,
+* `updateBody`, `response`. `listQuery` and `params` are skipped (their
+* constraint vocabulary is owned by the kit's query parser).
+*
+* Existing constraints on a property always win — the merge only fills in
+* gaps. Kits that already walk `fieldRules` during base-schema assembly
+* can call this helper for free (the checks are no-ops when constraints
+* already exist).
+*
+* Schema slot type is intentionally loose (`Record<string, unknown> | null
+* | undefined`) so adapters can pass either an `OpenApiSchemas`-shaped bag
+* or a kit-native bag without coercion.
+*/
+function mergeFieldRuleConstraints(schemas, schemaOptions) {
+	if (!schemas || typeof schemas !== "object") return;
+	const rules = schemaOptions?.fieldRules;
+	if (!rules || Object.keys(rules).length === 0) return;
+	for (const slot of [
+		"createBody",
+		"updateBody",
+		"response"
+	]) {
+		const slotSchema = schemas[slot];
+		if (!slotSchema || typeof slotSchema !== "object") continue;
+		const properties = slotSchema["properties"];
+		if (!properties) continue;
+		for (const [field, rule] of Object.entries(rules)) {
+			const prop = properties[field];
+			if (!prop || typeof prop !== "object") continue;
+			if (rule.minLength != null && prop["minLength"] == null) prop["minLength"] = rule.minLength;
+			if (rule.maxLength != null && prop["maxLength"] == null) prop["maxLength"] = rule.maxLength;
+			if (rule.min != null && prop["minimum"] == null) prop["minimum"] = rule.min;
+			if (rule.max != null && prop["maximum"] == null) prop["maximum"] = rule.max;
+			if (rule.pattern != null && prop["pattern"] == null) prop["pattern"] = rule.pattern;
+			if (rule.enum != null && prop["enum"] == null) prop["enum"] = rule.enum;
+			if (rule.description != null && prop["description"] == null) prop["description"] = rule.description;
+			if (rule.nullable === true) applyNullable(prop);
+		}
+	}
+}
+/**
+* Widen a JSON Schema property to also accept `null`.
+*
+* Handles the three ways a property can be typed:
+*   - `type: 'string'`     → `type: ['string', 'null']`
+*   - `type: [...]`        → append `'null'` if missing
+*   - `anyOf: [...]`       → append `{ type: 'null' }` branch if missing
+*
+* **Enum interaction:** when the widened prop also carries `enum: [...]`,
+* `null` is appended to the enum list too. AJV's `enum` keyword rejects
+* values not in the list regardless of the widened `type`, so
+* `{ type: ['string','null'], enum: ['a','b'] }` alone would still reject
+* `null`. The fix is `enum: ['a','b', null]`. (The `anyOf` branch dodges
+* this entirely — each branch scopes its own enum.)
+*
+* No-op when the schema already admits null (don't double-wrap) or has
+* no `type` / `anyOf` anchor to widen (e.g. Mixed — already accepts null).
+*
+* Mutates in place — callers already treat the slot schema as owned.
+* Exported so adapters that walk `fieldRules` inline can reuse the same
+* widening logic.
+*/
+function applyNullable(prop) {
+	if (Array.isArray(prop["anyOf"])) {
+		if (!prop["anyOf"].some((b) => b !== null && typeof b === "object" && (b["type"] === "null" || b["const"] === null))) prop["anyOf"].push({ type: "null" });
+		return;
+	}
+	if (Array.isArray(prop["type"])) {
+		if (!prop["type"].includes("null")) prop["type"].push("null");
+		widenEnumToIncludeNull(prop);
+		return;
+	}
+	if (typeof prop["type"] === "string") {
+		prop["type"] = [prop["type"], "null"];
+		widenEnumToIncludeNull(prop);
+		return;
+	}
+}
+/**
+* Append `null` to `enum` when present. Required because AJV's `enum`
+* keyword is independent of `type` — a value must appear in the enum
+* array verbatim even if the widened type says null is allowed.
+*/
+function widenEnumToIncludeNull(prop) {
+	if (!Array.isArray(prop["enum"])) return;
+	if (prop["enum"].includes(null)) return;
+	prop["enum"] = [...prop["enum"], null];
+}
 //#endregion
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody };

package/dist/schema/index.d.mts

@@ -1,4 +1,4 @@
 import { CrudSchemas, FieldRule, FieldRules, JsonSchema, SchemaBuilderOptions, ValidationResult } from "./types.mjs";
-import { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from "./field-rules.mjs";
+import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { SchemaGenerator, SchemaGeneratorContext, isSchemaGenerator } from "./generator.mjs";
-export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type ValidationResult, applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, validateUpdateBody };
+export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type ValidationResult, applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };

package/dist/schema/index.mjs

@@ -1,3 +1,3 @@
-import { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from "./field-rules.mjs";
+import { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
 import { isSchemaGenerator } from "./generator.mjs";
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };

package/dist/schema/types.d.mts

@@ -36,6 +36,27 @@ interface FieldRule {
    * narrow on the same flag.
    */
   hidden?: boolean;
+  /** String minimum length — JSON Schema `minLength`. */
+  minLength?: number;
+  /** String maximum length — JSON Schema `maxLength`. */
+  maxLength?: number;
+  /** Number minimum — JSON Schema `minimum`. */
+  min?: number;
+  /** Number maximum — JSON Schema `maximum`. */
+  max?: number;
+  /** Regex pattern — JSON Schema `pattern`. */
+  pattern?: string;
+  /** Allowed values — JSON Schema `enum`. */
+  enum?: ReadonlyArray<string | number>;
+  /**
+   * Widen the property type to also accept `null`. Implemented as a
+   * draft-07 type tuple (`type: ['string','null']`) or anyOf branch
+   * (`anyOf: [..., { type: 'null' }]`). Existing nullability is
+   * preserved — never double-widens.
+   */
+  nullable?: boolean;
+  /** Human-readable description — JSON Schema `description`. */
+  description?: string;
 }
 /** Map of field name → FieldRule. */
 interface FieldRules {