@postxl/schema 1.2.1 → 1.3.1

package/dist/field/defaults.d.ts

@@ -5,6 +5,9 @@ export declare const standardFieldName_createdAt: string & import("zod").$brand<
 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,13 +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_label = 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,
     };
 }
@@ -444,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/portfolex.schema.json

@@ -56,7 +56,8 @@
                 { "name": "target", "excelName": "target", "type": "String", "label": "Target" },
                 { "name": "isotope", "excelName": "isotope", "type": "String", "label": "Isotope" },
                 { "name": "txDx", "excelName": "txDx", "type": "String", "label": "TxDx" },
-                { "name": "indicationId", "excelName": "indication", "type": "Indication", "label": "Indication" }
+                { "name": "indicationId", "excelName": "indication", "type": "Indication", "label": "Indication" },
+                { "name": "color", "excelName": "color", "type": "String?", "label": "Color" }
             ],
             "standardFields": [],
             "seed": [
@@ -257,7 +258,8 @@
                 { "name": "fteRegulatory", "excelName": "fteRegulatory", "type": "Float?", "label": "FTE Regulatory" },
                 { "name": "fteCmc", "excelName": "fteCmc", "type": "Float?", "label": "FTE CMC" },
                 { "name": "isEvent", "excelName": "isEvent", "type": "Boolean", "label": "Is Event?" },
-                { "name": "successorMask", "excelName": "successorMask", "type": "Int", "label": "Successor Mask" }
+                { "name": "successorMask", "excelName": "successorMask", "type": "Int", "label": "Successor Mask" },
+                { "name": "color", "excelName": "color", "type": "String?", "label": "Color" }
             ],
             "standardFields": [],
             "seed": [
@@ -288,7 +290,8 @@
             "schema": "Data",
             "fields": [
                 { "name": "id", "excelName": "indication", "type": "String", "label": "Indication" },
-                { "name": "abbreviation", "excelName": "abbreviation", "type": "String", "label": "Abbreviation" }
+                { "name": "abbreviation", "excelName": "abbreviation", "type": "String", "label": "Abbreviation" },
+                { "name": "color", "excelName": "color", "type": "String?", "label": "Color" }
             ],
             "standardFields": [],
             "seed": [

package/dist/samples/sample-schemas.d.ts

@@ -1056,27 +1056,22 @@ export declare const sampleSchemas: {
                 type: string;
                 label: string;
                 description: string;
-                isUnique?: never;
+                isUnique: boolean;
             } | {
                 name: string;
                 type: string;
                 label: string;
                 description: string;
-                isUnique: boolean;
-            })[];
-            standardFields: string[];
-            labelField: string;
-            seed: ({
-                id: string;
-                name: string;
-                code: string;
-                parentId: null;
+                isUnique?: never;
             } | {
-                id: string;
                 name: string;
-                code: string;
-                parentId: string;
+                type: string;
+                label: string;
+                description?: never;
+                isUnique?: never;
             })[];
+            standardFields?: never;
+            labelField?: never;
         } | {
             name: string;
             description: string;
@@ -1084,119 +1079,50 @@ export declare const sampleSchemas: {
             fields: ({
                 name: string;
                 type: string;
-                label: string;
-                description: string;
-                faker: string;
-                isUnique?: never;
-            } | {
-                name: string;
-                type: string;
-                label: string;
-                description: string;
-                faker?: never;
-                isUnique?: never;
+                label?: never;
+                commonFields?: never;
+                members?: never;
             } | {
                 name: string;
                 type: string;
                 label: string;
-                description: string;
-                isUnique: boolean;
-                faker: string;
+                commonFields: never[];
+                members: {
+                    type: string;
+                    label: string;
+                    fields: {
+                        name: string;
+                        type: string;
+                    }[];
+                }[];
             })[];
-            standardFields: string[];
-            labelField: string;
-            seed: {
-                id: string;
-                name: string;
-                email: string;
-                role: string;
-                hierarchyId: string;
-            }[];
+            standardFields?: never;
+            labelField?: never;
         } | {
             name: string;
             description: string;
             schema: string;
-            fields: ({
+            standardFields: string[];
+            fields: {
                 name: string;
                 type: string;
                 label: string;
                 description: string;
-                faker: string;
-                isUnique?: never;
-                prismaRelationFieldName?: never;
-                seed?: never;
-            } | {
+            }[];
+            labelField?: never;
+        } | {
+            name: string;
+            description: string;
+            schema: string;
+            fields: {
                 name: string;
                 type: string;
                 label: string;
                 description: string;
                 isUnique: boolean;
-                faker?: never;
-                prismaRelationFieldName?: never;
-                seed?: never;
-            } | {
-                name: string;
-                type: string;
-                label: string;
-                description: string;
-                faker?: never;
-                isUnique?: never;
-                prismaRelationFieldName?: never;
-                seed?: never;
-            } | {
-                name: string;
-                type: string;
-                label: string;
-                description: string;
-                prismaRelationFieldName: string;
-                faker?: never;
-                isUnique?: never;
-                seed?: never;
-            } | {
-                name: string;
-                type: string;
-                label: string;
-                description: string;
-                seed: boolean;
-                faker?: never;
-                isUnique?: never;
-                prismaRelationFieldName?: never;
-            })[];
+            }[];
             standardFields: string[];
-            labelField: string;
-            seed: ({
-                id: string;
-                title: string;
-                code: string;
-                description: string;
-                hierarchyId: string;
-                ownerId: string;
-                responsibleId: string;
-                startDate: string;
-                endDate: string;
-                isManagementAttentionNeeded: boolean;
-                trafficLight: string;
-                approvalStatus: string;
-                targetSavings: number;
-                targetDate: string;
-                notes: string;
-            } | {
-                id: string;
-                title: string;
-                code: string;
-                description: string;
-                hierarchyId: string;
-                ownerId: string;
-                responsibleId: string;
-                startDate: string;
-                endDate: string;
-                isManagementAttentionNeeded: boolean;
-                trafficLight: string;
-                approvalStatus: string;
-                targetSavings: null;
-                targetDate: string;
-                notes: string;
-            })[];
+            labelField?: never;
         } | {
             name: string;
             description: string;
@@ -1206,62 +1132,32 @@ export declare const sampleSchemas: {
                 type: string;
                 label: string;
                 description: string;
-                faker: string;
                 prismaRelationFieldName?: never;
+                excelName?: never;
             } | {
                 name: string;
                 type: string;
                 label: string;
+                prismaRelationFieldName: string;
                 description: string;
-                faker?: never;
-                prismaRelationFieldName?: never;
+                excelName?: never;
             } | {
                 name: string;
                 type: string;
                 label: string;
+                excelName: string;
                 description: string;
-                prismaRelationFieldName: string;
-                faker?: never;
-            })[];
-            standardFields: string[];
-            labelField: string;
-            seed: ({
-                id: string;
-                title: string;
-                description: string;
-                initiativeId: string;
-                indicatorId: null;
-                responsibleId: string;
-                status: string;
-                deadline: string;
+                prismaRelationFieldName?: never;
             } | {
-                id: string;
-                title: string;
-                description: string;
-                initiativeId: string;
-                indicatorId: string;
-                responsibleId: string;
-                status: string;
-                deadline: string;
-            })[];
-        } | {
-            name: string;
-            description: string;
-            schema: string;
-            fields: {
                 name: string;
                 type: string;
                 label: string;
+                excelName: string;
+                prismaRelationFieldName: string;
                 description: string;
-            }[];
-            standardFields: string[];
-            labelField: string;
-            seed: {
-                id: string;
-                name: string;
-                unit: string;
-                numberFormat: string;
-            }[];
+            })[];
+            standardFields?: never;
+            labelField?: never;
         } | {
             name: string;
             description: string;
@@ -1271,51 +1167,16 @@ export declare const sampleSchemas: {
                 type: string;
                 label: string;
                 description: string;
-                faker?: never;
+                isUnique?: never;
             } | {
                 name: string;
                 type: string;
                 label: string;
                 description: string;
-                faker: string;
+                isUnique: boolean;
             })[];
             standardFields: string[];
             labelField: string;
-            seed: {
-                id: string;
-                name: string;
-                startDate: string;
-                endDate: string;
-            }[];
-        } | {
-            name: string;
-            description: string;
-            schema: string;
-            fields: {
-                name: string;
-                type: string;
-                label: string;
-                description: string;
-            }[];
-            standardFields: string[];
-            seed: ({
-                id: string;
-                indicatorId: string;
-                initiativeId: string;
-                periodId: string;
-                valueActual: number;
-                valueForecast: null;
-                valueBudget: number;
-            } | {
-                id: string;
-                indicatorId: string;
-                initiativeId: string;
-                periodId: string;
-                valueActual: null;
-                valueForecast: null;
-                valueBudget: number;
-            })[];
-            labelField?: never;
         })[];
         enums: {
             name: string;