@mapomodule/utils 2.0.0-beta.4 → 2.0.0-beta.6

package/README.md

@@ -1,33 +1,37 @@
 # @mapomodule/utils
 
-Typed utility helpers shared across all `@mapomodule/*` packages.
-
-## Utilities
-
-| Export              | Description                                                                                                |
-| ------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `deepMerge`         | Recursively merges two plain objects                                                                       |
-| `getNestedValue`    | Reads a value from a dotted path (e.g. `"user.address.city"`)                                              |
-| `setNestedValue`    | Returns a new object with a value set at a dotted path                                                     |
-| `objectDiff`        | Returns only the keys that differ between two objects — used for differential PATCH requests               |
-| `formatDate`        | Formats a `Date` or ISO string with a token-based format string (`YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`)     |
-| `debounce`          | Returns a debounced version of a function                                                                  |
-| `slotNamespace`     | Filters and strips a prefix from a Vue `Slots` object — used to forward a slot subset to a child component |
-| `buildRouteTree`    | Converts a flat `RouteRecordNormalized[]` into a nested `MenuNode[]` tree for sidebar rendering            |
-| `normalizeEndpoint` | Ensures an API endpoint string has exactly one leading and one trailing slash — used by `useCrud`          |
+Plain TypeScript helpers shared by the `@mapomodule/*` packages: object and path utilities, formatting, endpoint normalization, menu trees and JSON Schema conditionals. No Vue, no Nuxt, no side effects, so they are safe in server code and tests.
 
-## Installation
+It is not a Nuxt module and nothing is auto-imported: import what you need.
 
-```bash
-pnpm add @mapomodule/utils
+```ts
+import { debounce, deepMerge, slugify } from "@mapomodule/utils";
+import { applyConditionals } from "@mapomodule/utils/jsonSchema";
 ```
 
-## Dev workflow
+## Installation
 
 ```bash
-pnpm dev:utils   # from monorepo root — tsc --watch
+pnpm add @mapomodule/utils@next
 ```
 
----
+Apps already get it through `mapomodule`, but with pnpm's strict layout an app can import it only if the package is declared in its own `dependencies`. Mapo v2 is published on the `next` dist-tag while it is in beta.
+
+## What's inside
+
+| Area                                                                      | Exports                                                                                                                               |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Objects                                                                   | `deepMerge`, `deepClone`, `objectDiff`, `filterObj`, `findPropPaths`                                                                  |
+| Nested paths                                                              | `getNestedValue`, `setNestedValue`, `setNestedValueMutating`                                                                          |
+| Files                                                                     | `isFile`, `isBlob`, `isFileOrBlob`, `filesInObject`                                                                                   |
+| Formatting                                                                | `formatDate`, `humanFileSize`, `slugify`                                                                                              |
+| Timing                                                                    | `debounce`                                                                                                                            |
+| Endpoints                                                                 | `normalizeEndpoint`, `splitEndpointParams`                                                                                            |
+| Slots and menus                                                           | `slotNamespace`, `buildRouteTree`, `calcMaxMenuNestDepth`, the `MenuNode` type                                                        |
+| JSON Schema (`@mapomodule/utils/jsonSchema`, also exported from the root) | `matchesSchema`, `applyConditionals`, `hasConditionals`, `resolveSchema`, `extractDefs`, `getDefaultForSchema`, the `JSONSchema` type |
+
+## Documentation
 
-> The helpers in this package are ported from the Mapo v1 legacy codebase. As v2 development progresses, individual helpers may be added, removed, or replaced — and the package itself may be dissolved if its contents are better placed elsewhere.
+- [@mapomodule/utils](https://lotrekagency.github.io/mapo-new/modules/utils): every helper with examples
+- [Composable & Function API Reference](https://lotrekagency.github.io/mapo-new/modules/api): signatures, including the JSON Schema helpers
+- [Import Guide](https://lotrekagency.github.io/mapo-new/guide/imports)

package/dist/debounce.js

@@ -5,15 +5,20 @@
  *
  * @param fn Function to debounce.
  * @param ms Debounce delay in milliseconds.
- * @returns A debounced function with the same argument signature as `fn`.
+ * @returns A debounced function with the same argument signature as `fn`, and a `cancel()` method.
  */
 export function debounce(fn, ms) {
     let timer;
-    return function (...args) {
+    const debounced = function (...args) {
         clearTimeout(timer);
         timer = setTimeout(() => {
             fn.apply(this, args);
         }, ms);
     };
+    debounced.cancel = () => {
+        clearTimeout(timer);
+        timer = undefined;
+    };
+    return debounced;
 }
 //# sourceMappingURL=debounce.js.map

package/dist/debounce.js.map

@@ -1 +1 @@
-{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../src/debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,EAA2B,EAC3B,EAAU;IAEV,IAAI,KAAgD,CAAC;IACrD,OAAO,UAAyB,GAAG,IAAO;QACxC,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../src/debounce.ts"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,EAA2B,EAC3B,EAAU;IAEV,IAAI,KAAgD,CAAC;IACrD,MAAM,SAAS,GAAG,UAAyB,GAAG,IAAO;QACnD,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAiB,CAAC;IAClB,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE;QACtB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,YAAY,EACZ,aAAa,EACb,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,YAAY,EACZ,aAAa,EACb,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/types/debounce.d.ts

@@ -1,3 +1,12 @@
+/** A debounced function: called like the original, plus `cancel()`. */
+export interface Debounced<A extends unknown[]> {
+    (...args: A): void;
+    /**
+     * Drops the pending call, if any. Call it when the owner goes away (in a
+     * component, `onBeforeUnmount`), so a late call cannot act on the next page.
+     */
+    cancel(): void;
+}
 /**
  * Creates a debounced wrapper that delays invocation until calls stop for `ms` milliseconds.
  *
@@ -5,7 +14,7 @@
  *
  * @param fn Function to debounce.
  * @param ms Debounce delay in milliseconds.
- * @returns A debounced function with the same argument signature as `fn`.
+ * @returns A debounced function with the same argument signature as `fn`, and a `cancel()` method.
  */
-export declare function debounce<A extends unknown[]>(fn: (...args: A) => unknown, ms: number): (...args: A) => void;
+export declare function debounce<A extends unknown[]>(fn: (...args: A) => unknown, ms: number): Debounced<A>;
 //# sourceMappingURL=debounce.d.ts.map

package/dist/types/debounce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC1C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC3B,EAAE,EAAE,MAAM,GACT,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAQtB"}
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/debounce.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE;IAC5C,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC1C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC3B,EAAE,EAAE,MAAM,GACT,SAAS,CAAC,CAAC,CAAC,CAad"}

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export { objectDiff } from "./objectDiff.js";
 export { formatDate } from "./formatDate.js";
 export { humanFileSize, slugify } from "./formatters.js";
 export { debounce } from "./debounce.js";
+export type { Debounced } from "./debounce.js";
 export { slotNamespace } from "./slotNamespace.js";
 export { buildRouteTree, calcMaxMenuNestDepth } from "./menuHelpers.js";
 export type { MenuNode } from "./menuHelpers.js";

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,YAAY,EACZ,aAAa,EACb,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,YAAY,EACZ,aAAa,EACb,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/types/jsonSchema/types.d.ts

@@ -42,6 +42,12 @@ export interface JSONSchema {
     /** Standard JSON Schema. Consumers should render the field disabled, not drop it. */
     readOnly?: boolean;
     writeOnly?: boolean;
+    /**
+     * Extension: this property holds one value per language. Camomilla publishes it
+     * on the flat form schema served by OPTIONS. Without it a derived form renders
+     * translated fields as plain ones, which ignore the language tabs around them.
+     */
+    translatable?: boolean;
     _nullable?: boolean;
     [key: string]: unknown;
 }

package/dist/types/jsonSchema/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/jsonSchema/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/jsonSchema/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapomodule/utils",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.6",
   "description": "Mapo typed utilities",
   "type": "module",
   "license": "MIT",