refactor: monorepo split + honest compat layer + honest benchmarks + honest docs [Phase 0-4]

.changeset/README.md

@@ -0,0 +1,32 @@
+# Changesets
+
+## What are changesets?
+
+Changesets are a way of managing and documenting changes to a monorepo. They allow teams to:
+
+- Document changes with clear descriptions
+- Manage versioning across multiple packages
+- Automate changelog generation
+- Coordinate releases
+
+## Creating a changeset
+
+To create a changeset, run:
+
+```bash
+pnpm changeset
+```
+
+This will prompt you to:
+
+1. Select which packages have changed
+2. Determine the type of change (major, minor, or patch)
+3. Write a summary of the change
+
+## Before releasing
+
+Always ensure your changes have accompanying changesets. You can check the status with:
+
+```bash
+pnpm changeset status
+```

.changeset/config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": ["@changesets/changelog-github", { "repo": "Isqanderm/data-mapper" }],
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/feat-each-option.md

@@ -0,0 +1,11 @@
+---
+'@tech-pioneer/data-mapper-class-validator': minor
+---
+
+Implement `ValidationOptions.each`, which was previously accepted nowhere and silently skipped per-element validation.
+
+`@IsString({ each: true })` and every other decorator now apply their constraint to each element of an array or `Set` instead of to the property value. Behaviour follows class-validator 0.14.4: a failing element produces one error for the property (not one per element), the error's `value` is the whole collection, an empty collection passes, and a value that is neither an array nor a `Set` is left unvalidated.
+
+Default messages for an `each` constraint are prefixed — `each value must be at least 5 characters`. Upstream's prefix is `each value in `, which runs on into the property name upstream puts in every message; this package's messages carry no property name, so the prefix stops at `each value`. A message supplied by the caller is used exactly as written, as upstream does.
+
+Constraint deduplication now takes `each` into account, so `@MinLength(5)` and `@MinLength(5, { each: true })` on one property stay two constraints instead of collapsing into one.

.changeset/feat-message-property-name.md

@@ -0,0 +1,23 @@
+---
+'@tech-pioneer/data-mapper-class-validator': major
+---
+
+**Breaking:** default messages now name the property they are about.
+
+`@MinLength(3)` on `username` produced `must be at least 3 characters`. Anything showing `error.constraints` to a person — a form, an API response, a log line — had to pair the sentence back up with `error.property` by hand to say which field it meant. Upstream writes `username must be longer than or equal to 3 characters`; messages now carry the same subject: `username must be at least 3 characters`.
+
+Under `each` the property follows upstream's prefix: `each value in tags must be at least 5 characters` (it previously stopped at `each value`, because there was no property name for the preposition to lead into).
+
+A message supplied by the caller — string or function — is untouched.
+
+Five defaults opened with their own noun and would have read as `lat latitude must be…` once prefixed, so they were reworded:
+
+| decorator      | before                                            | now                                     |
+| -------------- | ------------------------------------------------- | --------------------------------------- |
+| `@IsLatitude`  | `latitude must be a number between -90 and 90`    | `must be a number between -90 and 90`   |
+| `@IsLongitude` | `longitude must be a number between -180 and 180` | `must be a number between -180 and 180` |
+| `@ArrayUnique` | `all elements must be unique`                     | `must contain only unique values`       |
+| `@MinDate`     | `minimal allowed date is …`                       | `must not be before …`                  |
+| `@MaxDate`     | `maximal allowed date is …`                       | `must not be after …`                   |
+
+The wording of the sentences still differs from upstream's in most cases — only the subject is matched. Three of the six messages compared came out identical to upstream anyway (`must be an email`, `should not be empty`, `must contain at least N elements`).

.changeset/feat-missing-decorators.md

@@ -0,0 +1,17 @@
+---
+'@tech-pioneer/data-mapper-class-validator': minor
+---
+
+Add the 21 decorators upstream ships that this package did not: `IsAscii`, `IsBase32`, `IsBase58`, `IsBooleanString`, `IsByteLength`, `IsFirebasePushId`, `IsFullWidth`, `IsHSL`, `IsHalfWidth`, `IsHash`, `IsHexadecimal`, `IsISRC`, `IsISSN`, `IsMilitaryTime`, `IsMultibyte`, `IsNumberString`, `IsOctal`, `IsRgbColor`, `IsSurrogatePair`, `IsTaxId` and `IsVariableWidth`.
+
+Every one reports under the key upstream reports, follows the package's type rules (a value that is not a string fails rather than passing), and supports `each`, `groups`, `always` and a custom message like the rest. Comparing runtime exports, no decorator upstream exports is missing here any more.
+
+Behaviour was measured against class-validator 0.14.4 rather than assumed, which is how these landed the way they did:
+
+- `IsFirebasePushId` reports under `IsFirebasePushId` — capitalised, unlike every other key.
+- `IsRgbColor` rejects `rgb(0, 0, 0)`: spaces between components are not allowed.
+- `IsByteLength` measures UTF-8 bytes, not characters, so `'é'` counts as two.
+- `IsBase58` accepts `abc`; `IsAscii` rejects the empty string; `IsNumberString` rejects exponent notation.
+- `IsISSN` verifies the mod-11 check digit, so `0378-5954` fails where `0378-5955` passes.
+
+Two limitations, both marked in the compat table: `IsTaxId` recognises only the `en-US` format (upstream takes a locale), and `IsHash` takes the algorithm name but none of the further options.

.changeset/fix-class-to-class-deep-clone.md

@@ -0,0 +1,16 @@
+---
+'@tech-pioneer/data-mapper-class-transformer': major
+---
+
+**Breaking:** `classToClass` / `instanceToInstance` now produce a deep clone, and `@Transform` runs once instead of twice.
+
+It was a `classToPlain` → `plainToClass` round trip carrying the `'classToClass'` transformation type through both legs. Neither leg recursed, because each descends only for its own direction, so nested instances and arrays came out shared with the source — mutating the clone mutated the original. `@Transform` ran on both legs, so a `value + 1` transform produced `value + 2`.
+
+It is now a single recursive pass. A nested value's class is taken from the value itself rather than from `@Type`, matching upstream, which clones a nested instance back into its own class whether or not the property carries one. `Date` is cloned rather than walked as a plain object, and `Map` / `Set` keep their type instead of collapsing to `{}`.
+
+Verified against class-transformer 0.5.1 across nested cloning, class preservation, arrays, Dates, `@Transform` call count and result, and the value an excluded property ends up with: no differences.
+
+Two behaviours worth stating because they are easy to mistake for bugs, and both match upstream:
+
+- `@Exclude()` does **not** remove a property in this direction, unlike class→plain.
+- The target is built with `new`, and an excluded property is never copied onto it, so it holds whatever its field initializer gives it rather than the source's value.

.changeset/fix-constraint-inheritance.md

@@ -0,0 +1,11 @@
+---
+'@tech-pioneer/data-mapper-class-validator': patch
+---
+
+A subclass now validates the constraints it declares, not just the ones it inherits.
+
+Validation metadata lives on the constructor, and the lookup that created it did not check for an _own_ property. A subclass reaches its parent's metadata through the static prototype chain, so `class Child extends Parent` wrote its constraints into `Parent`'s map — and since compiled validators are cached by `metadata.target`, `Child` was then served `Parent`'s validator. Its own constraints never ran and no error was reported for them.
+
+Whether this happened depended on instantiation order: if the subclass was constructed first it created the map and worked, if the parent was constructed first the subclass silently validated only inherited fields. A base DTO with shared fields — the ordinary NestJS arrangement — hits the broken order.
+
+Each class now gets its own metadata. Nothing is merged from the parent, because TC39 field initializers run for the whole hierarchy when a subclass is constructed, so inherited constraints are already registered against the subclass.

.changeset/fix-error-keys-and-reject-shape.md

@@ -0,0 +1,19 @@
+---
+'@tech-pioneer/data-mapper-class-validator': major
+---
+
+**Breaking:** error keys and the `validateOrReject` rejection value now match class-validator 0.14.4.
+
+Consumers read `error.constraints.isUrl` and `catch (errors) { errors.map(…) }`. Both were spelled differently here, so code migrated from upstream read `undefined` and carried on — the failure surfaced later, somewhere else.
+
+Fourteen of 48 measured decorators reported a key upstream does not use. Ten were acronym casing: `isURL` → `isUrl`, `isUUID` → `isUuid`, `isJSON` → `isJson`, `isIP` → `isIp`, `isFQDN` → `isFqdn`, `isISO8601` → `isIso8601`, `isJWT` → `isJwt`, `isMACAddress` → `isMacAddress`, `isISIN` → `isIsin`, `isISBN` → `isIsbn`.
+
+Four reported another constraint's key entirely:
+
+- `@Length` emitted a `minLength` and a `maxLength` constraint. It is now one `isLength` constraint, reported under that key, and `max` is optional as upstream has it.
+- `@IsDateString` delegated to `@IsISO8601` and inherited its key. It now reports `isDateString`.
+- `@IsPositive` was implemented as `min: 0.000001` and reported `min`; `@IsNegative` as `max: -0.000001` reporting `max`. Both now test the sign directly and report `isPositive` / `isNegative`. This also fixes the range: `5e-7` is a positive number and was being rejected.
+
+`validateOrReject` now rejects with the `ValidationError[]` itself instead of a `ValidationFailedError` wrapper, so the upstream idiom works. `validateOrRejectSync` — not an upstream API — throws the array too, so the two do not disagree. The `ValidationFailedError` class is still exported but no longer thrown by either.
+
+All 48 decorators measured against upstream now report identical keys.

.changeset/fix-groups-and-always.md

@@ -0,0 +1,22 @@
+---
+'@tech-pioneer/data-mapper-class-validator': major
+---
+
+**Breaking:** group filtering now follows class-validator 0.14.4, and `always` works.
+
+The filter was inverted in both directions. A constraint carrying `groups` ran _only_ when the caller passed a matching group, so `validate(dto)` with no options silently skipped it — the opposite of upstream, where no filter means no filtering. And a constraint with no groups ran even under a filter that selected other groups, where upstream skips it.
+
+`always` was declared on every decorator and in `ValidatorOptions`, stored in metadata, and never read by the compiler — so the escape hatch upstream provides for exactly this situation did nothing. It is now honoured, per decorator and as a default for the whole call through `ValidatorOptions.always`.
+
+Measured against upstream (checking which constraint actually ran, since with `forbidUnknownValues` a filtered-away object reports an error of its own that is easy to mistake for the constraint running):
+
+| validate options | constraint in group `g1` | ungrouped | `g1` + always |
+| ---------------- | ------------------------ | --------- | ------------- |
+| none             | runs                     | runs      | runs          |
+| `groups: []`     | runs                     | runs      | runs          |
+| `groups: ['g1']` | runs                     | skipped   | runs          |
+| `groups: ['x']`  | skipped                  | skipped   | runs          |
+
+`@IsOptional({ groups })` used the same inverted rule and is fixed with it: the property counts as optional when no filter is set or when its group is selected. `optionalAlways` (`@IsOptional({ always: true })`), stored and never read, now works too.
+
+`strictGroups` remains unimplemented and is still marked so in the compat table.

.changeset/fix-isurl-alias-and-base64.md

@@ -0,0 +1,11 @@
+---
+'@tech-pioneer/data-mapper-class-validator': minor
+---
+
+Export `IsUrl`, and reject base64 strings whose length is not a multiple of four.
+
+`IsUrl` is how class-validator spells it, and the implementation was already here — only the name was missing, so `import { IsUrl }` failed for anyone migrating. Both spellings now resolve to the same decorator, and the error key was already `isUrl`.
+
+`@IsBase64` accepted `'zz'` and `'abc'`. Its pattern allowed a trailing group of two or three characters with no padding, so any length was permitted. Upstream (validator.js, padding on by default) requires a multiple of four. Verified against upstream across twelve inputs, including the padded, unpadded and malformed forms: no differences remain.
+
+One existing test asserted that `'SGVsbG8gV29ybGQ'` — fifteen characters — is valid base64. Upstream rejects it by default and accepts it only under `IsBase64Options.padding: false`, an option this package does not accept; the test now asserts the rejection.

.changeset/fix-nested-class-to-plain.md

@@ -0,0 +1,11 @@
+---
+'@tech-pioneer/data-mapper-class-transformer': patch
+---
+
+`classToPlain` / `instanceToPlain` / `serialize` now descend into nested values, so a nested `@Exclude()` actually runs.
+
+Previously the class->plain direction did not recurse: a nested class instance was copied into the output untouched, carrying every field its own decorators were supposed to remove. A `@Exclude()`d field one level down — the canonical `password` case — reached the serialized output, while the same decorator on a top-level property worked. Nested `@Expose({ name })` renames were dropped for the same reason.
+
+Recursion is not gated on `@Type`: in the class->plain direction the class is known from the value itself, matching class-transformer 0.5.1, which recurses whether or not the property carries a `@Type`. `Date` values are passed through rather than expanded, and plain object literals are copied key-for-key, both verified against upstream.
+
+Note that recursion makes a self-referential object graph throw `RangeError: Maximum call stack size exceeded`, exactly as upstream does without `enableCircularCheck` (an option this package does not implement).

.changeset/fix-wrong-type-values.md

@@ -0,0 +1,13 @@
+---
+'@tech-pioneer/data-mapper-class-validator': major
+---
+
+**Breaking:** a constraint now fails when the value is not of the type it measures.
+
+The generated checks were written as "if the type fits and the value is bad, report an error", so a value of the wrong type fell out of the condition and was reported as valid. `@IsEmail()` passed on the number `5`, `@Min(5)` passed on the string `'a'`, `@ArrayMinSize(2)` passed on `'ab'`, and — most consequentially — every one of them passed on `undefined` and `null`. Upstream's predicates return false for a value they cannot measure, which is an error.
+
+61 of the 84 generated checks changed. Behaviour was compared against class-validator 0.14.4 across 46 decorators and six value shapes each: 321 of 322 comparisons now agree (the remaining difference is an unrelated `@IsBase64` regex that is more permissive than upstream's).
+
+**What this means for existing code.** A decorated property with no value is now an error, exactly as upstream treats it. Code that relied on the old silence needs one of the escape hatches upstream provides for the same situation: `@IsOptional()` on the property, or the `skipUndefinedProperties` / `skipNullProperties` / `skipMissingProperties` validator options. All of them are already implemented here and are covered by tests.
+
+`@IsLatitude` and `@IsLongitude` keep accepting both a number and a numeric string, as upstream does; anything else is now an error.

.changeset/phase2-class-transformer.md

@@ -0,0 +1,7 @@
+---
+'@tech-pioneer/data-mapper-class-transformer': minor
+---
+
+Implement `enableImplicitConversion` (primitive coercion via `@Type`). Remove dead `ClassTransformOptions` fields: `enableCircularCheck`, `exposeUnsetFields`, `targetMaps`, `enableValidation`.
+
+See `docs/compat-class-transformer.md` for the full compatibility table, including the `enableImplicitConversion` array-of-primitives caveat.

.changeset/phase2-class-validator.md

@@ -0,0 +1,9 @@
+---
+'@tech-pioneer/data-mapper-class-validator': minor
+---
+
+Implement previously-dead `ValidatorOptions` (`whitelist`, `forbidNonWhitelisted`, `skipMissingProperties`, `skipNullProperties`, `skipUndefinedProperties`, `stopAtFirstError`, `forbidUnknownValues`), function-form `message`, `ValidationError.target`/`.value` stripping, `registerDecorator`, and `getMetadataStorage`.
+
+Behavior change: `whitelist` now actually strips unknown properties from the validated object (was a silent no-op in v4).
+
+Note: `forbidUnknownValues` defaults to `false` here, diverging from upstream `[email protected]`, which defaults to `true`. See `docs/compat-class-validator.md`.

.changeset/remove-unreachable-legacy-mapper.md

@@ -0,0 +1,8 @@
+---
+'@tech-pioneer/data-mapper-core': patch
+'om-data-mapper': patch
+---
+
+Remove the dead `export * from './core/Mapper'` re-export: the decorator API's `Mapper` already shadowed the legacy class under ES module semantics, so `Mapper.create` was never reachable from the published surface. The ESM post-install simulation now exercises only imports that resolve through the real exports maps.
+
+Documented one behavior change in `docs/migration-v4-to-v5.md`: bracket-index syntax inside a `@Map()` path (`@Map('items[0].name')`) worked by accident in v4 and no longer resolves now that every path segment is emitted as an escaped literal key. Use `@MapFrom`/`@Transform` or a nested mapper for array indexing.

.changeset/review-fixes-class-transformer.md

@@ -0,0 +1,7 @@
+---
+'@tech-pioneer/data-mapper-class-transformer': patch
+---
+
+`enableImplicitConversion` now coerces array-valued `@Type(() => Number|String|Boolean|Date)` properties per element (previously the whole array was passed to the constructor, yielding `NaN`/joined strings).
+
+`@TransformClassToPlain`, `@TransformClassToClass`, and `@TransformPlainToClass` now use static imports instead of a runtime `require('./functions')`, which threw `ReferenceError: require is not defined` for ESM consumers.

.changeset/review-fixes-class-validator.md

@@ -0,0 +1,5 @@
+---
+'@tech-pioneer/data-mapper-class-validator': patch
+---
+
+Review fixes: `stopAtFirstError` no longer drops all errors when a validator is named after an `Object.prototype` member; null-prototype inputs return the no-metadata result instead of throwing; constraint metadata no longer grows on every instantiation for `@Matches`/`@Validate`/`@ValidateBy`; `registerDecorator` enforces every registration (second unnamed inline validators and re-registered classes with new constraints are no longer silently dropped); class-based custom validators report errors under their registered name (upstream-compatible) instead of `custom`; validation metadata is keyed via `Symbol.for` so duplicate package copies interoperate.

.github/FUNDING.yml

@@ -2,4 +2,3 @@
 # https://help.github.com/en/articles/displaying-a-sponsor-button-in-your-repository
 
 github: [Isqanderm]
-

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: Bug Report
 description: Report a bug or unexpected behavior
-title: "[Bug]: "
-labels: ["bug", "triage"]
+title: '[Bug]: '
+labels: ['bug', 'triage']
 body:
   - type: markdown
     attributes:
@@ -55,7 +55,7 @@ body:
       placeholder: |
         ```typescript
         import { Mapper } from 'om-data-mapper';
-        
+
         // Your code here
         ```
       render: typescript
@@ -109,8 +109,8 @@ body:
       label: TypeScript
       description: Are you using TypeScript?
       options:
-        - "Yes"
-        - "No"
+        - 'Yes'
+        - 'No'
     validations:
       required: true
 
@@ -144,4 +144,3 @@ body:
           required: false
         - label: I am using the latest version of om-data-mapper
           required: false
-