@wisemen/nestjs-custom-fields 0.0.0 → 0.0.1

package/dist/validators/custom-field-value.validator.unit.test.js

@@ -0,0 +1,166 @@
+import { describe, it } from 'node:test';
+import { LocalizedString } from '@wisemen/localized-string';
+import { customFieldDefinition } from '#src/factory/custom-field-definition.factory.js';
+import { CustomFieldType } from '#src/enum/custom-field-type.enum.js';
+import { validateCustomFieldValue, validateCustomFieldValues } from '#src/validators/custom-field-value.validator.js';
+import { generateUuid } from '#src/custom-field-definition.uuid.js';
+import { CustomFieldValueValidationError } from '#src/validators/custom-field-value-validation.error.js';
+import { expect } from 'expect';
+describe('validateCustomFieldValues', () => {
+    it('accepts valid custom field values', () => {
+        const textDefinition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: true,
+            rules: {
+                minLength: 2
+            }
+        });
+        const singleSelectDefinition = customFieldDefinition(CustomFieldType.SINGLE_SELECT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'status',
+            label: new LocalizedString([{ locale: 'en', value: 'Status' }]),
+            description: null,
+            isRequired: false,
+            choices: [
+                {
+                    value: 'draft',
+                    label: new LocalizedString([{ locale: 'en', value: 'Draft' }]),
+                    order: 1
+                }
+            ]
+        });
+        expect(() => validateCustomFieldValues([textDefinition, singleSelectDefinition], [
+            {
+                definitionUuid: textDefinition.uuid,
+                type: CustomFieldType.TEXT,
+                value: 'ok'
+            },
+            {
+                definitionUuid: singleSelectDefinition.uuid,
+                type: CustomFieldType.SINGLE_SELECT,
+                value: 'draft'
+            }
+        ])).not.toThrow();
+    });
+    it('rejects duplicate custom field definitions', () => {
+        const textDefinition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: false
+        });
+        expect(() => validateCustomFieldValues([textDefinition, textDefinition], [])).toThrow(new CustomFieldValueValidationError(`Duplicate custom field definition ${textDefinition.uuid}`));
+    });
+    it('rejects a value whose definition was not provided', () => {
+        const textDefinition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: false
+        });
+        const missingDefinitionUuid = generateUuid();
+        expect(() => validateCustomFieldValues([textDefinition], [
+            {
+                definitionUuid: missingDefinitionUuid,
+                type: CustomFieldType.TEXT,
+                value: 'hello'
+            }
+        ])).toThrow(new CustomFieldValueValidationError(`Custom field definition ${missingDefinitionUuid} was not found`));
+    });
+    it('rejects duplicate values for the same definition', () => {
+        const textDefinition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: false
+        });
+        expect(() => validateCustomFieldValues([textDefinition], [
+            {
+                definitionUuid: textDefinition.uuid,
+                type: CustomFieldType.TEXT,
+                value: 'first'
+            },
+            {
+                definitionUuid: textDefinition.uuid,
+                type: CustomFieldType.TEXT,
+                value: 'second'
+            }
+        ])).toThrow(new CustomFieldValueValidationError(`Custom field value for definition ${textDefinition.uuid} can only be provided once`));
+    });
+    it('rejects when a required custom field is missing', () => {
+        const textDefinition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: true
+        });
+        expect(() => validateCustomFieldValues([textDefinition], [])).toThrow(new CustomFieldValueValidationError(`Custom field definition ${textDefinition.uuid} is required`));
+    });
+});
+describe('validateCustomFieldValue', () => {
+    it('rejects when definitionUuid does not match the definition', () => {
+        const definition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: false
+        });
+        expect(() => validateCustomFieldValue(definition, {
+            definitionUuid: generateUuid(),
+            type: CustomFieldType.TEXT,
+            value: 'hello'
+        })).toThrow(new CustomFieldValueValidationError('Custom field value definitionUuid must match the definition uuid'));
+    });
+    it('rejects when value type does not match the definition type', () => {
+        const definition = customFieldDefinition(CustomFieldType.TEXT, {
+            tenantUuid: null,
+            entityType: 'invoice',
+            key: 'notes',
+            label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+            description: null,
+            isRequired: false
+        });
+        expect(() => validateCustomFieldValue(definition, {
+            definitionUuid: definition.uuid,
+            type: CustomFieldType.NUMBER,
+            value: 1
+        })).toThrow(new CustomFieldValueValidationError('Custom field value type must match the definition type'));
+    });
+    it('rejects when the rules type does not match the definition type', () => {
+        const definition = {
+            ...customFieldDefinition(CustomFieldType.TEXT, {
+                tenantUuid: null,
+                entityType: 'invoice',
+                key: 'notes',
+                label: new LocalizedString([{ locale: 'en', value: 'Notes' }]),
+                description: null,
+                isRequired: false
+            }),
+            rules: {
+                type: CustomFieldType.NUMBER,
+                min: 1
+            }
+        };
+        expect(() => validateCustomFieldValue(definition, {
+            definitionUuid: definition.uuid,
+            type: CustomFieldType.TEXT,
+            value: 'hello'
+        })).toThrow(new CustomFieldValueValidationError('Custom field rules must match the definition type'));
+    });
+});
+//# sourceMappingURL=custom-field-value.validator.unit.test.js.map

package/dist/validators/custom-field-value.validator.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-field-value.validator.unit.test.js","sourceRoot":"","sources":["../../lib/validators/custom-field-value.validator.unit.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,64 @@
 {
   "name": "@wisemen/nestjs-custom-fields",
-  "version": "0.0.0",
-  "license": "SEE LICENSE IN LICENSE.md",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "imports": {
+    "#src/*": "./dist/*"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/"
+  ],
+  "dependencies": {
+    "@wisemen/monetary": "^*",
+    "@wisemen/datewise": "^*",
+    "@wisemen/localized-string": "^*",
+    "@wisemen/api-error": "^*",
+    "@wisemen/validators": "^*",
+    "@wisemen/nestjs-typeorm": "^*"
+  },
+  "peerDependencies": {
+    "@nestjs/swagger": "^11.4.2",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@opentelemetry/api": "^1.9.1",
+    "typeorm": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.3.0",
+    "eslint": "10.2.1",
+    "oxlint": "1.59.0",
+    "oxlint-tsgolint": "0.20.0",
+    "typescript": "^5.9.3",
+    "expect": "30.4.1",
+    "@wisemen/eslint-config-nestjs": "1.1.1"
+  },
   "author": "Wisemen",
+  "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
     "url": "https://github.com/wisemen-digital/wisemen-core",
     "directory": "packages/api/nestjs-custom-fields"
+  },
+  "scripts": {
+    "lint:oxlint": "oxlint --type-aware lib",
+    "lint:eslint": "eslint lib",
+    "lint": "pnpm run lint:oxlint && pnpm run lint:eslint",
+    "clean": "rm -rf ./dist",
+    "build": "tsc",
+    "pretest": "pnpm build",
+    "test": "node --test ./dist/**/*.test.js",
+    "prerelease": "npm run build",
+    "release": "pnpx release-it"
   }
-}
+}

package/skills/getting-started/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: nestjs-custom-fields
+description: Use when working with the @wisemen/nestjs-custom-fields package — developer-defined custom fields in NestJS with TypeORM persistence and runtime validation. Covers registering the CustomFieldDefinition entity, authoring definitions with customFieldDefinition(), storing resolved values via @CustomFieldValueColumn(), exposing them through CustomFieldValueDto / @IsCustomFields(), and validating submissions with CustomFieldDefinitionsRepository + validateCustomFieldValues(). Use this whenever a task involves custom field definitions, CustomFieldValue columns, custom-field DTOs, or tenant-scoped field definitions, even if the package is not named explicitly.
+---
+
+# @wisemen/nestjs-custom-fields - Getting Started
+
+This package manages developer-defined custom field definitions and values. It
+does not target end-user managed custom field creation, does not ship
+migrations, and does not auto-discover definitions.
+
+It is intended that custom field definitions are read-only for users.
+Creating, updating, and deleting definitions is handled manually by developers
+through migrations or `playground.ts` scripts.
+
+Definition uniqueness is scoped by `entityType`. For non-tenant definitions,
+`key` must be unique per `entityType`. For tenant-scoped definitions,
+`key + tenantUuid` must be unique per `entityType`.
+
+## Step 1: Register The Exported Entity And Create The Table
+
+This package already exports the effective `CustomFieldDefinition` TypeORM
+entity. Add it to your datasource entities yourself so TypeORM knows about the
+table metadata. After that, generate and run a migration so the table and the
+exported entity's partial unique indexes are created in your database.
+
+```ts
+import { DataSource } from 'typeorm'
+import { CustomFieldDefinition } from '@wisemen/nestjs-custom-fields'
+
+const datasource = new DataSource({
+  entities: ['dist/src/**/*.entity.js', CustomFieldDefinition]
+})
+```
+
+## Step 2: Define Definitions And Insert Them In The Database
+
+Create a definition with `customFieldDefinition(...)`, then insert it yourself.
+The package does not discover definitions automatically. At the moment this is
+mainly done through a migration or through `playground.ts`.
+
+For persisted definitions, `tenantUuid` is part of the definition shape and
+should be `null` for non-tenant definitions or a tenant UUID for tenant-scoped
+definitions. This is different from repository lookups, where `tenantUuid` is
+optional and can simply be omitted.
+
+`key` uniqueness is enforced per `entityType`. Use a unique `key` for global
+definitions, and a unique `key + tenantUuid` combination for tenant-specific
+definitions.
+
+It is recommended to define your `entityType` values in an enum instead of
+repeating string literals across your application.
+
+```ts
+import type { INestApplicationContext } from '@nestjs/common'
+import { NestFactory } from '@nestjs/core'
+import { JobContainer } from '@wisemen/app-container/fastify'
+import { LocalizedString } from '@wisemen/localized-string'
+import { DataSource } from 'typeorm'
+import {
+  CustomFieldDefinition,
+  CustomFieldType,
+  customFieldDefinition
+} from '@wisemen/nestjs-custom-fields'
+
+enum CustomFieldEntityType {
+  TICKET = 'ticket'
+}
+
+export class Playground extends JobContainer {
+  async bootstrap(): Promise<INestApplicationContext> {
+    return await NestFactory.createApplicationContext(PlayGroundModule)
+  }
+
+  async execute(app: INestApplicationContext): Promise<void> {
+    const priorityField = customFieldDefinition(CustomFieldType.SINGLE_SELECT, {
+      tenantUuid: null,
+      entityType: CustomFieldEntityType.TICKET,
+      key: 'priority',
+      label: new LocalizedString([{ locale: 'en', value: 'Priority' }]),
+      description: null,
+      isRequired: true,
+      choices: [
+        {
+          value: 'low',
+          order: 1,
+          label: new LocalizedString([{ locale: 'en', value: 'Low' }])
+        },
+        {
+          value: 'high',
+          order: 2,
+          label: new LocalizedString([{ locale: 'en', value: 'High' }])
+        }
+      ]
+    })
+
+    await app.get(DataSource).manager.insert(CustomFieldDefinition, priorityField)
+  }
+}
+```
+
+## Step 3: Store Values On The Entity With The Custom Column
+
+Resolved custom field values live on your own entity. Use
+`@CustomFieldValueColumn()` for the persisted values column.
+
+```ts
+import { Entity, PrimaryGeneratedColumn } from 'typeorm'
+import { CustomFieldValueColumn, type CustomFieldValue } from '@wisemen/nestjs-custom-fields'
+
+@Entity()
+export class Ticket {
+  @PrimaryGeneratedColumn('uuid')
+  uuid: string
+
+  @CustomFieldValueColumn({ nullable: true })
+  customFields: CustomFieldValue[] | null
+}
+```
+
+## Step 4: Receive And Show Values With DTOs
+
+Requests and responses use the DTO layer from this package. For incoming
+payloads, use `CustomFieldValueDto` with `@IsCustomFields()`. For outgoing
+payloads, map stored values back with `CustomFieldValueDto.from(...)`.
+
+```ts
+// update-ticket.command.ts
+import { ApiProperty } from '@nestjs/swagger'
+import {
+  CustomFieldValueApiExtraModels,
+  CustomFieldValueDto,
+  CustomFieldValueDtoApiProperty,
+  IsCustomFields
+} from '@wisemen/nestjs-custom-fields'
+
+@CustomFieldValueApiExtraModels()
+export class UpdateTicketCommand {
+  @CustomFieldValueDtoApiProperty({ isArray: true })
+  @IsCustomFields()
+  customFields: CustomFieldValueDto[]
+}
+
+// view-ticket.response.ts
+@CustomFieldValueApiExtraModels()
+export class ViewTicketResponse {
+  @ApiProperty({ type: String, format: 'uuid' })
+  uuid: string
+
+  @CustomFieldValueDtoApiProperty({ isArray: true })
+  customFields: CustomFieldValueDto[]
+
+  constructor(ticket: Ticket) {
+    this.uuid = ticket.uuid
+    this.customFields = ticket.customFields?.map((value) => CustomFieldValueDto.from(value)) ?? []
+  }
+}
+```
+
+Calling `parse()` on a DTO turns the transport-friendly input into the domain
+custom field value shape, including richer value objects when needed. For
+example, a `MonetaryDto` is parsed into the package's monetary value object
+instead of staying a plain JSON structure.
+
+```ts
+import {
+  CustomFieldType,
+  MonetaryCustomFieldValueDto
+} from '@wisemen/nestjs-custom-fields'
+
+const dto = new MonetaryCustomFieldValueDto()
+dto.definitionUuid = definitionUuid
+dto.value = {
+  amount: '12.50',
+  currency: 'EUR',
+  precision: 2
+}
+
+const parsed = dto.parse()
+
+// parsed is now a domain custom field value object:
+// {
+//   definitionUuid,
+//   type: CustomFieldType.MONETARY,
+//   value: dto.value.parse()
+// }
+```
+
+## Step 5: Retrieve Definitions For Validation
+
+When you process submitted values, retrieve the matching definitions through
+`CustomFieldDefinitionsRepository` and validate against them with
+`validateCustomFieldValues(...)`. If you also want to return definitions from
+an API, map the same repository results with `CustomFieldDefinitionResponse`.
+To inject the repository, register `CustomFieldDefinitionRepositoryModule` in
+the Nest module that owns your use case or controller.
+
+```ts
+import { Module } from '@nestjs/common'
+import { CustomFieldDefinitionRepositoryModule } from '@wisemen/nestjs-custom-fields'
+
+@Module({
+  imports: [CustomFieldDefinitionRepositoryModule],
+  providers: [UpdateTicketUseCase]
+})
+export class UpdateTicketModule {}
+```
+
+`validateCustomFieldValues(...)` throws `CustomFieldValueValidationError` when
+the submitted values do not match the definitions. In controllers, document
+that error according to the `@wisemen/api-error` package pattern by registering
+it with `@ApiErrorResponse(...)`.
+
+```ts
+import { ApiErrorResponse } from '@wisemen/api-error'
+import { CustomFieldValueValidationError } from '@wisemen/nestjs-custom-fields'
+
+@ApiErrorResponse(CustomFieldValueValidationError)
+async update(...): Promise<void> {
+  // controller logic
+}
+```
+On repository lookups, `tenantUuid` is optional. Omit it to work with
+non-tenant definitions, or set it to retrieve tenant-specific definitions in a
+multi-tenant setup.
+
+After DTO parsing, validate the resolved values against the definitions that
+apply for that entity and tenant. This is the runtime check that enforces the
+definition rules.
+
+The runtime order matters: call `.parse()` on the DTOs first, then run
+`validateCustomFieldValues(...)` against the definitions for that
+`entityType` and tenant scope.
+
+```ts
+import { Injectable } from '@nestjs/common'
+import {
+  CustomFieldDefinitionResponse,
+  CustomFieldDefinitionsRepository,
+  validateCustomFieldValues
+} from '@wisemen/nestjs-custom-fields'
+
+enum CustomFieldEntityType {
+  TICKET = 'ticket'
+}
+
+@Injectable()
+export class UpdateTicketUseCase {
+  constructor(
+    private readonly repository: CustomFieldDefinitionsRepository
+  ) {}
+
+  async execute(command: UpdateTicketCommand): Promise<void> {
+    const values = command.customFields.map((value) => value.parse())
+    const definitions = await this.repository.findDefinitions({
+      entityType: CustomFieldEntityType.TICKET
+    })
+    validateCustomFieldValues(definitions, values)
+
+    // Remaining use-case logic
+  }
+}
+```