@stndrds/schema 1.0.0-alpha.92 → 1.0.0-alpha.93

package/dist/index.mjs

@@ -252,7 +252,10 @@ function isFlowFieldsRow(row) {
   return !row.type || row.type === "fields";
 }
 function isLayoutRow(row) {
-  return !!row.type && row.type !== "fields";
+  return !!row.type && row.type !== "fields" && row.type !== "relationList";
+}
+function isFlowRelationListRow(row) {
+  return row.type === "relationList";
 }
 function isFlowDefinition(obj) {
   return typeof obj === "object" && obj !== null && "slots" in obj && "pages" in obj && "relations" in obj && "status" in obj;
@@ -294,7 +297,9 @@ var RESERVED_ATTRIBUTE_NAMES = [
   "completionStatus",
   "values",
   "metadata",
-  "deletedAt"
+  "deletedAt",
+  "schemaVersion",
+  "archivedValues"
 ];
 
 // src/types/permissions.ts
@@ -858,7 +863,8 @@ function createEmptyContext() {
     documents: {},
     variables: {},
     conditionResults: {},
-    createdRecordIds: {}
+    createdRecordIds: {},
+    relationBuffers: {}
   };
 }
 function getContextValue(context, path) {
@@ -1316,6 +1322,14 @@ var WorkflowDefinitionSchema = z.object({
   }
 );
 
+// src/types/migrations.ts
+var DEFAULT_RETENTION_POLICY = {
+  attributeData: 30,
+  deletedObjects: 90,
+  transforms: 365,
+  migrationErrors: 30
+};
+
 // src/lib/object-helpers.ts
 function isEmpty2(obj) {
   if (obj === null || obj === void 0) {
@@ -2834,8 +2848,146 @@ function document(config) {
 
 // src/builders/object-builder.ts
 import z2 from "zod";
+
+// src/builders/migration-builder.ts
+function resolveBuiltInTransform(targetType) {
+  const map = {
+    text: "toString",
+    textarea: "toString",
+    richtext: "toString",
+    number: "toNumber",
+    currency: "toNumber",
+    rating: "toNumber",
+    date: "toDate",
+    checkbox: "toBoolean"
+  };
+  return map[targetType];
+}
+function reverseOperation(op) {
+  switch (op.type) {
+    case "rename_attribute":
+      return { type: "rename_attribute", from: op.to, to: op.from };
+    case "add_attribute":
+      return { type: "remove_attribute", name: op.attribute.name, backup_config: op.attribute };
+    case "remove_attribute":
+      return { type: "add_attribute", attribute: op.backup_config };
+    case "change_type":
+      return {
+        type: "change_type",
+        name: op.name,
+        from: op.to,
+        to: op.from,
+        transform: op.transform ? resolveBuiltInTransform(op.from) : void 0
+      };
+    case "update_config":
+      return { type: "update_config", name: op.name, from: op.to, to: op.from };
+    case "rename_object":
+      return { type: "rename_object", from: op.to, to: op.from };
+    case "remove_object":
+      return { type: "remove_object", backup: op.backup };
+  }
+}
+var MigrationBuilder = class {
+  constructor(version) {
+    this.operations = [];
+    /** Tracks attribute names that have already been referenced in this migration */
+    this.touchedAttributes = /* @__PURE__ */ new Set();
+    this.version = version;
+  }
+  // --------------------------------------------------------------------------
+  // CONFLICT GUARD
+  // --------------------------------------------------------------------------
+  assertNotTouched(name, operationType) {
+    if (this.touchedAttributes.has(name)) {
+      throw new Error(
+        `[MigrationBuilder] Conflicting operations on attribute "${name}": it was already modified earlier in this migration (attempted: ${operationType}).`
+      );
+    }
+  }
+  // --------------------------------------------------------------------------
+  // OPERATION METHODS
+  // --------------------------------------------------------------------------
+  /**
+   * Rename an attribute.
+   * The reverse operation will rename it back.
+   */
+  renameAttribute(from, to) {
+    this.assertNotTouched(from, "rename_attribute");
+    this.touchedAttributes.add(from);
+    this.operations.push({ type: "rename_attribute", from, to });
+    return this;
+  }
+  /**
+   * Change the type of an attribute.
+   *
+   * The `transform` option accepts a function — it is used only to signal
+   * intent; the actual built-in transform is resolved from the target type.
+   */
+  changeType(name, from, to, options) {
+    this.assertNotTouched(name, "change_type");
+    this.touchedAttributes.add(name);
+    const transform = options?.transform ? resolveBuiltInTransform(to) : void 0;
+    this.operations.push({ type: "change_type", name, from, to, transform });
+    return this;
+  }
+  /**
+   * Remove an attribute.
+   *
+   * The `backup_config` is intentionally left empty — the sync engine will
+   * populate it from current DB state before applying the migration.
+   */
+  removeAttribute(name) {
+    this.assertNotTouched(name, "remove_attribute");
+    this.touchedAttributes.add(name);
+    this.operations.push({
+      type: "remove_attribute",
+      name,
+      backup_config: {}
+    });
+    return this;
+  }
+  /**
+   * Add a new attribute.
+   * The reverse operation will remove it (using the attribute definition as backup).
+   */
+  addAttribute(attribute) {
+    this.assertNotTouched(attribute.name, "add_attribute");
+    this.touchedAttributes.add(attribute.name);
+    this.operations.push({ type: "add_attribute", attribute });
+    return this;
+  }
+  /**
+   * Update the configuration of an attribute (partial patch).
+   *
+   * The `from` config is intentionally left empty — the sync engine will
+   * populate it from current DB state before applying the migration.
+   */
+  updateConfig(name, config) {
+    this.assertNotTouched(name, "update_config");
+    this.touchedAttributes.add(name);
+    this.operations.push({ type: "update_config", name, from: {}, to: config });
+    return this;
+  }
+  // --------------------------------------------------------------------------
+  // BUILD
+  // --------------------------------------------------------------------------
+  /**
+   * Produce the final MigrationDefinition with auto-generated reverse operations.
+   */
+  build() {
+    const reverse_operations = [...this.operations].reverse().map((op) => reverseOperation(op));
+    return {
+      version: this.version,
+      operations: [...this.operations],
+      reverse_operations
+    };
+  }
+};
+
+// src/builders/object-builder.ts
 var ObjectBuilder = class {
   constructor(config) {
+    this._migrations = [];
     this.validateName(config.name);
     this.obj = {
       name: config.name,
@@ -2932,6 +3084,37 @@ var ObjectBuilder = class {
     this._labelExpression = template;
     return this;
   }
+  /**
+   * Declare a schema migration for this object.
+   *
+   * - `version` must be >= 2 (version 1 is implicit — no migration needed).
+   * - Versions must be declared in sequential order without gaps or duplicates.
+   * - The callback receives a MigrationBuilder; call `.build()` is not required
+   *   (the ObjectBuilder calls it internally).
+   *
+   * @example
+   * ```typescript
+   * object({ name: "contacts", label: "Contact" })
+   *   .migration(2, (m) => m.renameAttribute("firstName", "first_name"))
+   *   .migration(3, (m) => m.changeType("age", "text", "number"))
+   *   .labelExpression("{{ first_name }}")
+   * ```
+   */
+  migration(version, callback) {
+    if (version < 2) {
+      throw new Error(
+        `[ObjectBuilder] Migration version must be >= 2 (version 1 is implicit). Got: ${version}`
+      );
+    }
+    const isDuplicate = this._migrations.some((m) => m.version === version);
+    if (isDuplicate) {
+      throw new Error(`[ObjectBuilder] Duplicate migration version: ${version}`);
+    }
+    const builder = new MigrationBuilder(version);
+    callback(builder);
+    this._migrations.push(builder.build());
+    return this;
+  }
   /**
    * Build the final ObjectDefinition
    * @throws Error if required fields are missing or invalid
@@ -2951,10 +3134,22 @@ The labelExpression defines how records are displayed in lists and relations.
   \u2705 Example: .labelExpression("{{ firstName }} {{ lastName }}")`
       );
     }
+    const sortedVersions = [...this._migrations].sort((a, b) => a.version - b.version);
+    for (let i = 0; i < sortedVersions.length; i++) {
+      const expected = i + 2;
+      if (sortedVersions[i].version !== expected) {
+        throw new Error(
+          `[ObjectBuilder] Migration versions must be sequential starting at 2. Expected version ${expected}, got ${sortedVersions[i].version}.`
+        );
+      }
+    }
+    const schema_version = sortedVersions.length > 0 ? sortedVersions[sortedVersions.length - 1].version : 1;
     return {
       ...this.obj,
       pluralLabel: this._pluralLabel,
-      labelExpression: this._labelExpression
+      labelExpression: this._labelExpression,
+      schema_version,
+      migrations: sortedVersions
     };
   }
   /**
@@ -3622,6 +3817,7 @@ var TabBuilder = class {
 };
 var DetailViewBuilder = class {
   constructor(name, label) {
+    this._version = 1;
     this.validateName(name);
     this.data = {
       name,
@@ -3683,6 +3879,17 @@ var DetailViewBuilder = class {
     this.data.metadata = value;
     return this;
   }
+  /**
+   * Set the schema version for this view definition.
+   * Increment when making breaking changes to force client updates.
+   * @param v - Version number (must be >= 1)
+   * @default 1
+   */
+  version(v) {
+    if (v < 1) throw new Error("View version must be >= 1");
+    this._version = v;
+    return this;
+  }
   /**
    * Configure a side panel with flat attribute fields displayed alongside tab content.
    * Not available for modal layout.
@@ -3755,7 +3962,8 @@ var DetailViewBuilder = class {
       type: "detail",
       config,
       default: this.data.default,
-      metadata: this.data.metadata
+      metadata: this.data.metadata,
+      schema_version: this._version
     };
   }
   /**
@@ -3784,6 +3992,7 @@ function view(name, label) {
 }
 var ListViewBuilder = class {
   constructor(name, label) {
+    this._version = 1;
     this.validateName(name);
     this.data = {
       name,
@@ -3827,6 +4036,17 @@ var ListViewBuilder = class {
     this.data.metadata = value;
     return this;
   }
+  /**
+   * Set the schema version for this view definition.
+   * Increment when making breaking changes to force client updates.
+   * @param v - Version number (must be >= 1)
+   * @default 1
+   */
+  version(v) {
+    if (v < 1) throw new Error("View version must be >= 1");
+    this._version = v;
+    return this;
+  }
   /**
    * Set base filters applied to ALL tabs (scoping, tenant, etc.)
    * @example .baseFilter({ combinator: "and", rules: [{ attribute: "tenant", operator: "is", value: "acme" }] })
@@ -3922,7 +4142,8 @@ var ListViewBuilder = class {
       type: "list",
       config,
       default: this.data.default,
-      metadata: this.data.metadata
+      metadata: this.data.metadata,
+      schema_version: this._version
     };
   }
   /**
@@ -4264,14 +4485,42 @@ var WorkflowFormBuilder = class {
     this.rows.push(row);
     return this;
   }
+  /**
+   * Add a relation list row to the form.
+   * Renders an editable list of related records for a given slot and relation.
+   *
+   * @param id - Unique row identifier
+   * @param slotId - The slot containing the relation
+   * @param relationName - The relation attribute name
+   * @param options - Display and preload options
+   */
+  relationListField(id, slotId, relationName, options = {}) {
+    this.rowOrder++;
+    const row = {
+      id,
+      order: this.rowOrder,
+      type: "relationList",
+      slotId,
+      relationName,
+      preload: options.preload ?? true,
+      columns: options.columns ?? [],
+      qualifiersInline: options.qualifiersInline ?? true,
+      modalFields: options.modalFields ?? "all",
+      label: options.label
+    };
+    this.rows.push(row);
+    return this;
+  }
   /**
    * Set the next node and complete the form definition
    */
   next(nodeId) {
-    const hasFieldRows = this.rows.some((r) => !r.type || r.type === "fields");
+    const hasFieldRows = this.rows.some(
+      (r) => !r.type || r.type === "fields" || r.type === "relationList"
+    );
     if (!hasFieldRows) {
       throw new Error(
-        `[WorkflowBuilder] Form "${this.nodeId}" has no field rows. Use .row() to add fields.`
+        `[WorkflowBuilder] Form "${this.nodeId}" has no field rows. Use .row() or .relationListField() to add fields.`
       );
     }
     return this.workflowBuilder._addFormNode({
@@ -5809,7 +6058,8 @@ function generateDefaultDetailView(object2, options = {}) {
     object: object2.name,
     type: "detail",
     config,
-    default: true
+    default: true,
+    schema_version: 1
   };
 }
 function generateDefaultListView(object2, options = {}) {
@@ -5834,7 +6084,8 @@ function generateDefaultListView(object2, options = {}) {
     object: object2.name,
     type: "list",
     config,
-    default: true
+    default: true,
+    schema_version: 1
   };
 }
 function generateFallbackView(object2, type, options = {}) {
@@ -6020,6 +6271,7 @@ export {
   CreateShareInputSchema,
   CustomTabConfig,
   DEFAULT_LABEL_FALLBACK,
+  DEFAULT_RETENTION_POLICY,
   DEFAULT_ROLES,
   DEFAULT_ROLE_DESCRIPTIONS,
   DEFAULT_ROLE_FOR_NEW_USERS,
@@ -6212,6 +6464,7 @@ export {
   isFlowDefinition,
   isFlowFieldsRow,
   isFlowPublished,
+  isFlowRelationListRow,
   isFlowsTab,
   isForbiddenError,
   isFormFieldsRow,

package/dist/validation/validators.d.mts

@@ -1,4 +1,4 @@
 import 'zod';
-export { Q as DEFAULT_VALIDATION_MESSAGES, ac as ValidationMessages, ad as ValidationResult, ae as attributeConfigSchemas, af as checkboxConfigSchema, ag as computeRecordStatus, ah as createAttributeValidator, ai as createCheckboxValidator, aj as createCurrencyValidator, ak as createDateValidator, al as createDraftValidator, am as createFileValidator, an as createFormAttributeValidator, ao as createFormulaValidator, ap as createLocationValidator, aq as createMultiRelationValidator, ar as createMultiselectValidator, as as createNumberValidator, at as createObjectValidator, au as createPhoneValidator, av as createRatingValidator, aw as createRelationValidator, ax as createRichtextValidator, ay as createRollupValidator, az as createSelectValidator, aA as createSingleRelationValidator, aB as createStatusValidator, aC as createTextAreaValidator, aD as createTextValidator, aE as createUserValidator, aF as currencyConfigSchema, aG as dateConfigSchema, aH as documentConfigSchema, aI as fileConfigSchema, aJ as formatZodErrors, aK as formulaConfigSchema, aL as getAttributeConfigSchema, aM as getMissingRequiredAttributes, aR as isRecordComplete, aT as locationConfigSchema, aU as multiselectConfigSchema, aV as numberConfigSchema, aW as parseAttributeConfig, aX as phoneConfigSchema, aY as ratingConfigSchema, aZ as relationConfigSchema, a_ as richtextConfigSchema, a$ as rollupConfigSchema, b0 as safeParseAttributeConfig, b1 as selectConfigSchema, b2 as statusConfigSchema, b3 as textConfigSchema, b4 as textareaConfigSchema, b5 as userConfigSchema, b6 as validateAttribute, b7 as validateAttributeConfig, b8 as validateDraft, b9 as validateDraftOrThrow, ba as validateObject, bb as validateObjectOrThrow } from '../validators-BFgj3O3w.mjs';
+export { aV as DEFAULT_VALIDATION_MESSAGES, ca as ValidationMessages, cb as ValidationResult, ci as attributeConfigSchemas, ck as checkboxConfigSchema, cl as computeRecordStatus, cm as createAttributeValidator, cn as createCheckboxValidator, co as createCurrencyValidator, cp as createDateValidator, cq as createDraftValidator, cs as createFileValidator, ct as createFormAttributeValidator, cu as createFormulaValidator, cv as createLocationValidator, cw as createMultiRelationValidator, cx as createMultiselectValidator, cy as createNumberValidator, cz as createObjectValidator, cA as createPhoneValidator, cB as createRatingValidator, cC as createRelationValidator, cD as createRichtextValidator, cE as createRollupValidator, cF as createSelectValidator, cG as createSingleRelationValidator, cI as createStatusValidator, cJ as createTextAreaValidator, cK as createTextValidator, cL as createUserValidator, cM as currencyConfigSchema, cN as dateConfigSchema, cO as documentConfigSchema, cQ as fileConfigSchema, cR as formatZodErrors, cS as formulaConfigSchema, cU as getAttributeConfigSchema, cW as getMissingRequiredAttributes, dt as isRecordComplete, dG as locationConfigSchema, dI as multiselectConfigSchema, dK as numberConfigSchema, dM as parseAttributeConfig, dN as phoneConfigSchema, dO as ratingConfigSchema, dP as relationConfigSchema, dQ as richtextConfigSchema, dR as rollupConfigSchema, dS as safeParseAttributeConfig, dT as selectConfigSchema, dV as statusConfigSchema, dW as textConfigSchema, dX as textareaConfigSchema, dY as userConfigSchema, dZ as validateAttribute, d_ as validateAttributeConfig, d$ as validateDraft, e0 as validateDraftOrThrow, e1 as validateObject, e2 as validateObjectOrThrow } from '../validators-CwhyfvP7.mjs';
 import '@stndrds/constants';
 import '../utils.mjs';

package/dist/validation/validators.d.ts

@@ -1,4 +1,4 @@
 import 'zod';
-export { Q as DEFAULT_VALIDATION_MESSAGES, ac as ValidationMessages, ad as ValidationResult, ae as attributeConfigSchemas, af as checkboxConfigSchema, ag as computeRecordStatus, ah as createAttributeValidator, ai as createCheckboxValidator, aj as createCurrencyValidator, ak as createDateValidator, al as createDraftValidator, am as createFileValidator, an as createFormAttributeValidator, ao as createFormulaValidator, ap as createLocationValidator, aq as createMultiRelationValidator, ar as createMultiselectValidator, as as createNumberValidator, at as createObjectValidator, au as createPhoneValidator, av as createRatingValidator, aw as createRelationValidator, ax as createRichtextValidator, ay as createRollupValidator, az as createSelectValidator, aA as createSingleRelationValidator, aB as createStatusValidator, aC as createTextAreaValidator, aD as createTextValidator, aE as createUserValidator, aF as currencyConfigSchema, aG as dateConfigSchema, aH as documentConfigSchema, aI as fileConfigSchema, aJ as formatZodErrors, aK as formulaConfigSchema, aL as getAttributeConfigSchema, aM as getMissingRequiredAttributes, aR as isRecordComplete, aT as locationConfigSchema, aU as multiselectConfigSchema, aV as numberConfigSchema, aW as parseAttributeConfig, aX as phoneConfigSchema, aY as ratingConfigSchema, aZ as relationConfigSchema, a_ as richtextConfigSchema, a$ as rollupConfigSchema, b0 as safeParseAttributeConfig, b1 as selectConfigSchema, b2 as statusConfigSchema, b3 as textConfigSchema, b4 as textareaConfigSchema, b5 as userConfigSchema, b6 as validateAttribute, b7 as validateAttributeConfig, b8 as validateDraft, b9 as validateDraftOrThrow, ba as validateObject, bb as validateObjectOrThrow } from '../validators-C7i6EpQK.js';
+export { aV as DEFAULT_VALIDATION_MESSAGES, ca as ValidationMessages, cb as ValidationResult, ci as attributeConfigSchemas, ck as checkboxConfigSchema, cl as computeRecordStatus, cm as createAttributeValidator, cn as createCheckboxValidator, co as createCurrencyValidator, cp as createDateValidator, cq as createDraftValidator, cs as createFileValidator, ct as createFormAttributeValidator, cu as createFormulaValidator, cv as createLocationValidator, cw as createMultiRelationValidator, cx as createMultiselectValidator, cy as createNumberValidator, cz as createObjectValidator, cA as createPhoneValidator, cB as createRatingValidator, cC as createRelationValidator, cD as createRichtextValidator, cE as createRollupValidator, cF as createSelectValidator, cG as createSingleRelationValidator, cI as createStatusValidator, cJ as createTextAreaValidator, cK as createTextValidator, cL as createUserValidator, cM as currencyConfigSchema, cN as dateConfigSchema, cO as documentConfigSchema, cQ as fileConfigSchema, cR as formatZodErrors, cS as formulaConfigSchema, cU as getAttributeConfigSchema, cW as getMissingRequiredAttributes, dt as isRecordComplete, dG as locationConfigSchema, dI as multiselectConfigSchema, dK as numberConfigSchema, dM as parseAttributeConfig, dN as phoneConfigSchema, dO as ratingConfigSchema, dP as relationConfigSchema, dQ as richtextConfigSchema, dR as rollupConfigSchema, dS as safeParseAttributeConfig, dT as selectConfigSchema, dV as statusConfigSchema, dW as textConfigSchema, dX as textareaConfigSchema, dY as userConfigSchema, dZ as validateAttribute, d_ as validateAttributeConfig, d$ as validateDraft, e0 as validateDraftOrThrow, e1 as validateObject, e2 as validateObjectOrThrow } from '../validators-BXWI__2n.js';
 import '@stndrds/constants';
 import '../utils.js';