@vsaas/loopback 12.3.0 → 12.4.0

package/dist/lib/loopback.cjs

@@ -311,6 +311,7 @@ var require_loopback = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports
 	*/
 	require_lib_builtin_models(loopback);
 	loopback.DataSource = juggler.DataSource;
+	loopback.registerNormalizer = juggler.registerNormalizer;
 	function getPackageRoot() {
 		return path.join(__dirname, "..", "..");
 	}

package/dist/lib/rate-limit/remote.cjs

@@ -150,9 +150,11 @@ function installRemoteRateLimiting(app) {
 			});
 		}
 	}
-	app.on("modelRemoted", function() {
-		app.models().forEach(installForModel);
-	});
+	function installForSharedClass(sharedClass) {
+		installForModel(sharedClass?.ctor);
+	}
+	app.on("modelRemoted", installForSharedClass);
+	app.on("remoteMethodAdded", installForSharedClass);
 	app.installRemoteRateLimits = function() {
 		app.models().forEach(installForModel);
 		return app;

package/dist/package.cjs

@@ -2,7 +2,7 @@
 var require_package = /* @__PURE__ */ require("./_virtual/_rolldown/runtime.cjs").__commonJSMin(((exports, module) => {
 	module.exports = {
 		"name": "@vsaas/loopback",
-		"version": "12.3.0",
+		"version": "12.4.0",
 		"description": "Fork of LoopBack 3 framework for building APIs and microservices in Node.js",
 		"keywords": [
 			"StrongLoop",
@@ -117,7 +117,7 @@ var require_package = /* @__PURE__ */ require("./_virtual/_rolldown/runtime.cjs"
 			"express": "catalog:",
 			"isemail": "^3.2.0",
 			"loopback-filters": "^1.1.1",
-			"nodemailer": "^9.0.5",
+			"nodemailer": "catalog:",
 			"otplib": "catalog:",
 			"serve-favicon": "^2.5.1"
 		},

package/docs/application-guide.md

@@ -1031,6 +1031,132 @@ that the validation entrypoint itself remains callback-oriented. In
 promise-first codebases, persisting with `await` is usually the cleanest way to
 run `validatePromise` rules.
 
+### Property normalization
+
+String properties can declare `normalize`, an ordered list of steps applied
+before validation and persistence. With `trim`, a `required` property rejects
+`"   "` instead of storing it.
+
+```json
+"properties": {
+  "email": { "type": "string", "required": true, "normalize": ["trim", "lowercase"] },
+  "name": { "type": "string", "normalize": ["trim", "collapseSpaces", "nfc"] },
+  "nickname": { "type": "string", "normalize": ["trim", "emptyToNull"] },
+  "bio": { "type": "string", "normalize": ["stripHtml", "trim"] },
+  "tags": { "type": ["string"], "normalize": ["trim", "lowercase"] }
+}
+```
+
+Built-in steps:
+
+| Name             | Effect                                                                |
+| ---------------- | --------------------------------------------------------------------- |
+| `trim`           | Remove leading and trailing whitespace                                |
+| `lowercase`      | Lowercase                                                             |
+| `uppercase`      | Uppercase                                                             |
+| `nfc`            | Unicode NFC normalization                                             |
+| `unaccent`       | Remove diacritics (`Ñandú` → `Nandu`)                                 |
+| `collapseSpaces` | Replace whitespace runs, newlines included, with one space            |
+| `emptyToNull`    | Store `""` as `null`; place it after `trim` to also catch blanks      |
+| `stripInvisible` | Remove control, zero-width, bidi-override and BOM characters          |
+| `numeric`        | Keep digits only                                                      |
+| `alphanumeric`   | Keep letters and digits only                                          |
+| `stripHtml`      | Drop tags, comments and `script`/`style` content; keep the plain text |
+
+`stripHtml` neither decodes nor escapes entities: `Tom & Jerry` stays as is
+and `a < b` is kept. It is data hygiene, not XSS protection; still escape on
+output. It keeps no markup, so it is not meant for rich-text fields.
+
+Register project-specific steps before models are defined, for example at the
+top of `server/server.js`, and reference them by name. Inline functions also
+work in programmatic models. A step returning `null` or `undefined` ends the
+pipeline with that value.
+
+```js
+loopback.registerNormalizer('rut', (value) => value.replace(/[.\s]/g, '').toUpperCase());
+```
+
+When it runs:
+
+- On every assignment through the model: `create`, `createAll`, `save`,
+  `patchAttributes`/`updateAttributes`, `updateAttribute`, `replaceById`,
+  `replaceOrCreate`, `patchOrCreate`/`upsert`, `upsertWithWhere`,
+  `findOrCreate`, relation and embedded-model writes, and values set by
+  `before save` hooks. `persist` hooks already see normalized data.
+- On partial updates, only the properties present in the payload are
+  normalized; other stored values are untouched. `updateAll` normalizes its
+  data, and validates the same values it persists.
+- On `where` filters, values compared for equality (`eq`, `neq`, `inq`, `nin`
+  and plain values) are normalized like stored values, so
+  `{ email: ' Ana@X.com ' }` matches `ana@x.com`. Pattern and range operators
+  (`like`, `ilike`, `regexp`, `gt`, `between`, …) are left as written.
+- Not on reads: rows written before a property gained `normalize` are returned
+  as stored. They are normalized the next time they are written through
+  `save()`, so migrate existing data when you add a step that changes it,
+  especially `lowercase`, since equality filters will no longer match the old
+  values.
+- Not inside extended operators (`$set`, `$push`, …) or custom property
+  setters; both receive the value as written.
+
+Unknown step names, or `normalize` on a non-string property, throw when the
+model is defined.
+
+### Property constraints
+
+Properties can declare the JSON Schema keywords that the API explorer already
+publishes, and they are enforced as model validations. They are checked after
+normalization, so `"normalize": "trim"` with `"maxLength": 128` validates the
+trimmed value.
+
+```json
+"properties": {
+  "name": { "type": "string", "required": true, "maxLength": 128, "normalize": "trim" },
+  "code": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
+  "contact": { "type": "string", "format": "email" },
+  "operability": { "type": "number", "min": 0, "max": 100 },
+  "mode": { "type": "string", "enum": ["NONE", "CRON"] },
+  "tags": { "type": ["string"], "maxItems": 20, "maxLength": 32 }
+}
+```
+
+| Keyword                          | Applies to              | Error code                                  |
+| -------------------------------- | ----------------------- | ------------------------------------------- |
+| `minLength`, `maxLength`         | strings                 | `length.min`, `length.max`                  |
+| `pattern`                        | strings                 | `format`                                    |
+| `format`                         | strings                 | `format.email`, `format.uri`, `format.uuid` |
+| `minimum`/`min`, `maximum`/`max` | numbers                 | `range.min`, `range.max`                    |
+| `enum`                           | string, number, boolean | `inclusion`                                 |
+| `minItems`, `maxItems`           | arrays                  | `items.min`, `items.max`                    |
+
+- Lengths count Unicode characters, so an emoji counts as one.
+- Bounds are inclusive. `min`/`max` are aliases of `minimum`/`maximum`.
+- On array properties, `minItems`/`maxItems` apply to the array and the other
+  keywords to each item.
+- `format` validates `email`, `uri` (absolute) and `uuid`. Other formats, such
+  as `date-time` or `int32`, are documentation only.
+- Constraints only check present values: `null` and `undefined` pass, and
+  `required` decides whether a value must be present. An empty string is a
+  value; use `"normalize": ["trim", "emptyToNull"]` to treat blanks as absent.
+- A keyword on a property of the wrong type, or an invalid limit, throws when
+  the model is defined.
+
+Failures are regular validation errors: the write is rejected with
+`ValidationError` (HTTP 422) and `error.details.codes` lists the codes above
+per property.
+
+Constraints run wherever model validation runs: `create`, `save`,
+`patchAttributes`, `replaceById`, `replaceOrCreate`, `upsertWithWhere`, and
+`patchOrCreate` with `validateUpsert: true`. Two writes skip full validation by
+default because their partial data would fail `required`: `updateAll` (unless
+`validateUpdate: true`) and `patchOrCreate` (unless `validateUpsert: true`).
+They still check the constraints of the properties they write. Passing
+`{ validate: false }`, or setting `validateUpdate`/`validateUpsert` or
+`automaticValidation` to `false`, skips both.
+
+Constraints declared on existing models start being enforced when you upgrade.
+Writes of values outside them, including a `patchAttributes` that leaves an
+invalid stored value untouched, will be rejected, so fix stored data first.
+
 ## Optional packages
 
 ### `@vsaas/loopback-component-storage`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsaas/loopback",
-  "version": "12.3.0",
+  "version": "12.4.0",
   "description": "Fork of LoopBack 3 framework for building APIs and microservices in Node.js",
   "keywords": [
     "StrongLoop",
@@ -98,15 +98,15 @@
     "debug": "^2.6.9",
     "depd": "^1.1.2",
     "ejs": "5.0.1",
-    "express": "4.22.2",
+    "express": "4.22.3",
     "isemail": "^3.2.0",
     "loopback-filters": "^1.1.1",
-    "nodemailer": "^9.0.5",
+    "nodemailer": "^9.1.1",
     "otplib": "13.4.1",
     "serve-favicon": "^2.5.1",
-    "@vsaas/loopback-datasource-juggler": "^13.0.1",
-    "@vsaas/remoting": "^13.0.1",
-    "@vsaas/loopback-connector-remote": "^12.0.2"
+    "@vsaas/loopback-connector-remote": "^12.0.2",
+    "@vsaas/loopback-datasource-juggler": "^13.1.0",
+    "@vsaas/remoting": "^13.0.2"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
@@ -124,8 +124,8 @@
     "tsdown": "0.22.14",
     "typescript": "6.0.2",
     "vitest": "4.1.11",
-    "@vsaas/loopback-boot": "^12.0.2",
-    "@vsaas/error-handler": "^12.0.1"
+    "@vsaas/error-handler": "^12.0.1",
+    "@vsaas/loopback-boot": "^12.0.2"
   },
   "engines": {
     "node": ">=24"