@postxl/schema 1.2.0 → 1.3.0

package/dist/field/defaults.d.ts

@@ -4,6 +4,10 @@ export declare const standardFieldName_id: "id" & import("zod").$brand<"PXL.Fiel
 export declare const standardFieldName_createdAt: string & import("zod").$brand<"PXL.FieldName">;
 export declare const standardFieldName_updatedAt: string & import("zod").$brand<"PXL.FieldName">;
 export declare const standardFieldName_name: string & import("zod").$brand<"PXL.FieldName">;
+export declare const standardFieldName_label: string & import("zod").$brand<"PXL.FieldName">;
+export declare const standardFieldName_key: string & import("zod").$brand<"PXL.FieldName">;
+export declare const standardFieldName_excelKey: string & import("zod").$brand<"PXL.FieldName">;
+export declare const standardFieldName_slug: string & import("zod").$brand<"PXL.FieldName">;
 export declare const standardFieldNames: (string & import("zod").$brand<"PXL.FieldName">)[];
 export declare const standardField_id: FieldJSONInput;
 export declare const standardField_createdAt: FieldJSONInput;

package/dist/field/defaults.js

@@ -33,12 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.standardFields = exports.standardField_name = exports.standardField_updatedAt = exports.standardField_createdAt = exports.standardField_id = exports.standardFieldNames = exports.standardFieldName_name = exports.standardFieldName_updatedAt = exports.standardFieldName_createdAt = exports.standardFieldName_id = void 0;
+exports.standardFields = exports.standardField_name = exports.standardField_updatedAt = exports.standardField_createdAt = exports.standardField_id = exports.standardFieldNames = exports.standardFieldName_slug = exports.standardFieldName_excelKey = exports.standardFieldName_key = exports.standardFieldName_label = exports.standardFieldName_name = exports.standardFieldName_updatedAt = exports.standardFieldName_createdAt = exports.standardFieldName_id = void 0;
 const Branded = __importStar(require("./shared/brands"));
 exports.standardFieldName_id = Branded.toFieldIdName('id');
 exports.standardFieldName_createdAt = Branded.toFieldName('createdAt');
 exports.standardFieldName_updatedAt = Branded.toFieldName('updatedAt');
 exports.standardFieldName_name = Branded.toFieldName('name');
+exports.standardFieldName_label = Branded.toFieldName('label');
+// Field names used as fallback for keyField resolution (in order: key, excelKey, slug, id)
+exports.standardFieldName_key = Branded.toFieldName('key');
+exports.standardFieldName_excelKey = Branded.toFieldName('excelKey');
+exports.standardFieldName_slug = Branded.toFieldName('slug');
 exports.standardFieldNames = [
     exports.standardFieldName_id,
     exports.standardFieldName_createdAt,

package/dist/model/model.json-decoder.d.ts

@@ -13,6 +13,7 @@ export declare const zModelJSON: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
     standardFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     defaultField: z.ZodOptional<z.ZodString>;
     labelField: z.ZodOptional<z.ZodString>;
+    keyField: z.ZodOptional<z.ZodString>;
     indexes: z.ZodOptional<z.ZodArray<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PXL.FieldName", "out">>>>;
     seed: z.ZodOptional<z.ZodArray<z.ZodAny>>;
     source: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/model/model.json-decoder.js

@@ -80,6 +80,12 @@ Example use case: default language, root region in region tree.`),
         .string()
         .optional().describe(`The name of the field that is used in the UI as the label of the entity.
 The label field must be a string field. If not provided, the \`name\` field is used as the label.`),
+    keyField: zod_1.z
+        //
+        .string()
+        .optional().describe(`The name of the field that is used as the key (unique identifier) for the entity.
+The key field must be a scalar string field. If not provided, the fallback order is: \`key\`, \`excelKey\`, \`slug\`, then \`id\`.
+The key field is used in navigation, Excel import, and other places where a human-readable identifier is needed.`),
     indexes: zod_1.z
         //
         .array(zod_1.z.array(brands_1.zFieldName).min(2, { error: 'Index must have at least 2 fields' }))

package/dist/model/model.transformer.d.ts

@@ -11,6 +11,7 @@ export declare function modelJSONTransformer(input: ModelJSON, ctx: z.Refinement
     databaseName: string & z.core.$brand<"PXL.DatabaseModelName">;
     defaultFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     labelFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
+    keyFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     isReadonly: boolean;
     excelName: string;
     description: string;
@@ -43,16 +44,18 @@ declare function addDefaults({ description, fields, standardFields, seed, faker,
     schema?: string | undefined;
     defaultField?: string | undefined;
     labelField?: string | undefined;
+    keyField?: string | undefined;
     source?: Record<string, unknown> | undefined;
 };
 type WithDefaults = ReturnType<typeof addDefaults>;
-declare function brandModel({ name, schema, databaseName, standardFields, defaultField, labelField, ...input }: WithDefaults): {
+declare function brandModel({ name, schema, databaseName, standardFields, defaultField, labelField, keyField, ...input }: WithDefaults): {
     name: string & z.core.$brand<"PXL.ModelName">;
     schema: (string & z.core.$brand<"PXL.DatabaseSchemaName">) | undefined;
     databaseName: string & z.core.$brand<"PXL.DatabaseModelName">;
     standardFields: (string & z.core.$brand<"PXL.FieldName">)[];
     defaultFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     labelFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
+    keyFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     isReadonly: boolean;
     excelName: string;
     description: string;
@@ -80,6 +83,7 @@ declare function combineFields({ fields, standardFields, ...model }: BrandedMode
     databaseName: string & z.core.$brand<"PXL.DatabaseModelName">;
     defaultFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     labelFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
+    keyFieldName: (string & z.core.$brand<"PXL.FieldName">) | undefined;
     isReadonly: boolean;
     excelName: string;
     description: string;

package/dist/model/model.transformer.js

@@ -65,7 +65,7 @@ function addDefaults({ description, fields, standardFields, seed, faker, ...inpu
         },
     };
 }
-function brandModel({ name, schema, databaseName, standardFields, defaultField, labelField, ...input }) {
+function brandModel({ name, schema, databaseName, standardFields, defaultField, labelField, keyField, ...input }) {
     return {
         ...input,
         name: (0, model_brands_1.toModelName)(name),
@@ -74,6 +74,7 @@ function brandModel({ name, schema, databaseName, standardFields, defaultField,
         standardFields: standardFields.map((f) => Field.toFieldName(f)),
         defaultFieldName: defaultField ? Field.toFieldName(defaultField) : undefined,
         labelFieldName: labelField ? Field.toFieldName(labelField) : undefined,
+        keyFieldName: keyField ? Field.toFieldName(keyField) : undefined,
     };
 }
 function combineFields({ fields, standardFields, ...model }, ctx) {

package/dist/model/model.types.d.ts

@@ -13,6 +13,13 @@ export type Model = {
     idField: Field.FieldId;
     defaultField: Field.FieldDatabaseNative | undefined;
     labelField: Field.FieldDatabaseNative;
+    /**
+     * The field used as the key/unique identifier for the entity.
+     * Used in navigation, Excel import, and other places where a human-readable identifier is needed.
+     * Must be a scalar string field. Resolved from: explicit keyField, or fallback to key, excelKey, slug, id (in that order).
+     * Always defined since id field is always present.
+     */
+    keyField: Field.FieldDatabaseNative;
     indexes: ModelIndex[];
     seed: Seed[];
     /**

package/dist/project-schema/project-schema.json-decoder.d.ts

@@ -23,6 +23,7 @@ export declare const zProjectSchemaJSON: z.ZodPipe<z.ZodTransform<unknown, unkno
         standardFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
         defaultField: z.ZodOptional<z.ZodString>;
         labelField: z.ZodOptional<z.ZodString>;
+        keyField: z.ZodOptional<z.ZodString>;
         indexes: z.ZodOptional<z.ZodArray<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PXL.FieldName", "out">>>>;
         seed: z.ZodOptional<z.ZodArray<z.ZodAny>>;
         source: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

package/dist/project-schema/project-schema.transformer.d.ts

@@ -28,6 +28,7 @@ export declare const zProjectSchema: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown,
         standardFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
         defaultField: z.ZodOptional<z.ZodString>;
         labelField: z.ZodOptional<z.ZodString>;
+        keyField: z.ZodOptional<z.ZodString>;
         indexes: z.ZodOptional<z.ZodArray<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PXL.FieldName", "out">>>>;
         seed: z.ZodOptional<z.ZodArray<z.ZodAny>>;
         source: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -73,6 +74,7 @@ export declare const zProjectSchema: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown,
         standardFields?: string[] | undefined;
         defaultField?: string | undefined;
         labelField?: string | undefined;
+        keyField?: string | undefined;
         indexes?: (string & z.core.$brand<"PXL.FieldName">)[][] | undefined;
         seed?: any[] | undefined;
         source?: Record<string, unknown> | undefined;

package/dist/project-schema/project-schema.transformer.js

@@ -270,13 +270,15 @@ function transformModel(model, projectSchema, ctx) {
     const idField = extractIdField(fields, model, ctx);
     const defaultField = extractDefaultField(model, fields, ctx);
     const labelField = extractLabelField(model, fields, ctx);
-    const { defaultFieldName, labelFieldName, ...remainingModel } = model;
+    const keyField = extractKeyField(model, fields, idField, ctx);
+    const { defaultFieldName, labelFieldName, keyFieldName, ...remainingModel } = model;
     return {
         ...remainingModel,
         databaseSchema: model.schema ?? projectSchema.defaultDatabaseSchema,
         fields,
         defaultField,
         labelField,
+        keyField,
         idField,
     };
 }
@@ -424,12 +426,14 @@ function extractLabelField({ labelFieldName, ...model }, fields, ctx) {
     return labelField;
 }
 function extractLabelFieldFromNameOrIdField({ name }, fields, ctx) {
-    // If no label field is provided, ensure name field exists and use it
-    const fallbackField = fields.get(Field.standardFieldName_name) ?? fields.get(Field.standardFieldName_id);
+    // If no label field is provided, try name field first, then label field, then id field
+    const fallbackField = fields.get(Field.standardFieldName_name) ??
+        fields.get(Field.standardFieldName_label) ??
+        fields.get(Field.standardFieldName_id);
     if (fallbackField === undefined) {
         ctx.addIssue({
             code: zod_1.z.ZodIssueCode.custom,
-            message: `Model ${name} neither provides a \`${Field.standardFieldName_name}\` field nor has \`labelField\` property!`,
+            message: `Model ${name} neither provides a \`${Field.standardFieldName_name}\` or \`${Field.standardFieldName_label}\` field nor has \`labelField\` property!`,
         });
         return zod_1.z.NEVER;
     }
@@ -442,3 +446,53 @@ function extractLabelFieldFromNameOrIdField({ name }, fields, ctx) {
     }
     return fallbackField;
 }
+function extractKeyField({ keyFieldName, ...model }, fields, idField, ctx) {
+    if (keyFieldName === undefined) {
+        return extractKeyFieldFromFallbacks(fields, idField);
+    }
+    const keyField = fields.get(keyFieldName);
+    if (keyField === undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `Key field ${keyFieldName} is not defined in model ${model.name}!`,
+        });
+        return zod_1.z.NEVER;
+    }
+    if (keyField.kind !== 'scalar' && keyField.kind !== 'id') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `Key field ${keyFieldName} in model ${model.name} must be a scalar string field, but instead is of type ${Field.getFieldType(keyField)}!`,
+        });
+        return zod_1.z.NEVER;
+    }
+    const type = keyField.kind === 'scalar' ? keyField.type : keyField.unbrandedTypeName;
+    if (type !== 'string') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `Key field ${keyFieldName} in model ${model.name} must be of type \`string\`, but instead is of type ${type}!`,
+        });
+        return zod_1.z.NEVER;
+    }
+    return keyField;
+}
+function extractKeyFieldFromFallbacks(fields, idField) {
+    // Fallback order: key, excelKey, slug, id
+    // Only consider string scalar fields for the fallbacks (except id which is always string)
+    const keyField = fields.get(Field.standardFieldName_key);
+    if (keyField !== undefined && isStringScalarField(keyField)) {
+        return keyField;
+    }
+    const excelKeyField = fields.get(Field.standardFieldName_excelKey);
+    if (excelKeyField !== undefined && isStringScalarField(excelKeyField)) {
+        return excelKeyField;
+    }
+    const slugField = fields.get(Field.standardFieldName_slug);
+    if (slugField !== undefined && isStringScalarField(slugField)) {
+        return slugField;
+    }
+    // id field is always present and is always a string
+    return idField;
+}
+function isStringScalarField(field) {
+    return field.kind === 'scalar' && field.type === 'string';
+}

package/dist/samples/simple.schema.json

@@ -136,7 +136,7 @@
             ],
             "standardFields": ["id", "createdAt", "updatedAt"],
             "labelField": "title",
-            "standardActions": ["create", "update", "upsert", "delete", "clone", "cloneMany"],
+            "standardActions": ["create", "update", "updateField", "upsert", "delete", "clone", "cloneMany"],
             "actions": {
                 "publish": "Publish a post",
                 "unpublish": "Unpublish a post"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postxl/schema",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Decoders for PXL Schema definitions and validation for PXL code generation framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,7 +36,7 @@
     "directory": "packages/schema"
   },
   "dependencies": {
-    "@postxl/utils": "^1.2.0"
+    "@postxl/utils": "^1.3.1"
   },
   "devDependencies": {},
   "wallaby": {