@otorp/plugin-utils 1.0.0-staging.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDJ.dev, TDN (TISSOT Development Network)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+[![Latest Release](https://gitlab.com/otorp/plugin-utils/-/badges/release.svg)](https://gitlab.com/otorp/plugin-utils/-/releases)
+[![pipeline status](https://gitlab.com/otorp/plugin-utils/badges/main/pipeline.svg)](https://gitlab.com/otorp/plugin-utils/-/commits/main)
+
+<!-- omit in toc -->
+# @otorp/plugin-utils
+*Registration helpers for [Otorp](https://gitlab.com/tdj.dev/otorp) plugins*
+
+<!-- omit in toc -->
+## 🎯 Objective
+
+Small, init-time utilities extracted from the Otorp core so plugin authors can register modules without duplicating boilerplate or reimplementing the shared symbol registry.
+
+This package does not extend prototypes or run Otorp's alias pass — it only wires your plugin into the registry that **Otorp core** consumes during initialization.
+
+---
+
+<!-- TOC -->
+
+- [📦 Installation](#-installation)
+- [🚀 Quickstart](#-quickstart)
+- [📚 API](#-api)
+  - [`setMod(config)`](#setmodconfig)
+  - [`newErrorHandler(modName?)`](#newerrorhandlermodname)
+  - [`ref(key, value?)`](#refkey-value)
+  - [`root`](#root)
+- [🔌 Plugin registration](#-plugin-registration)
+  - [With `@otorp/plugin-utils` (recommended)](#with-otorpplugin-utils-recommended)
+  - [Manual registration (equivalent)](#manual-registration-equivalent)
+- [❓ FAQ](#-faq)
+- [🤝 Contributing](#-contributing)
+
+<!-- /TOC -->
+
+## 📦 Installation
+
+> **Load order requirement:** this package — and your plugin script — must be registered **before** Otorp core initializes. Otorp deletes itself after its init pass; any plugin registered after that point will be silently ignored.
+
+**npm**
+
+```bash
+npm install @otorp/plugin-utils
+```
+
+```javascript
+import setMod from '@otorp/plugin-utils';
+
+```
+
+---
+
+## 🚀 Quickstart
+
+```javascript
+import setMod from '@otorp/plugin-utils';
+
+setMod({
+  source: 'myPlugin',
+  endpoints: {
+    "HTMLElement": [
+      'myPlugin.customMethod',
+      'myPlugin.meta1.meta2.customMethod'
+    ]
+  },
+  factory(methodName, ...meta) {
+    // methodName: last segment of the query string
+    // meta: everything between source and methodName
+    return function (...args) {
+      // `this` is the DOM instance at call time
+    };
+  }
+});
+```
+
+**Query string anatomy:**
+
+```
+"myPlugin.meta1.meta2.methodName"
+    │       │     │       └── methodName  (passed as first arg to factory)
+    │       └─────┘────────── meta        (spread as remaining args to factory)
+    └────────────────────────── source    (identifies your plugin)
+```
+
+What `setMod` does in one call:
+
+1. Validates the `factory` argument.
+2. Tracks registration count to warn on duplicate source names.
+3. Registers `{ endpoints, aliases, key, count }` in the shared modules Map under `source`.
+4. Creates a unique symbol-like key object with `.throw`, `.warn`, and `.error` helpers attached.
+5. Assigns the factory to `root` under the returned key so Otorp core can invoke it once per resolved endpoint during init.
+
+---
+
+## 📚 API
+
+All exports are init-time helpers. There is no runtime API after Otorp finishes its pass.
+
+### `setMod(config)` (Default Export)
+
+Register a plugin module for Otorp's initialization pass.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `source` | `string` | ✓ | Unique module identifier — used as the Map key and as the first segment of endpoint query strings. |
+| `endpoints` | `Record<string, string[]>` | ✓ | Maps a target prototype name to an array of endpoint query strings (e.g. `{ HTMLElement: ['myPlugin.customMethod'] }`). |
+| `factory` | `Function` | ✓ | Called by Otorp once per resolved endpoint. Receives `(methodName, ...meta)` and must return the function to install on the prototype. |
+| `aliases` | `Record<string, string> \| null` | — | Optional alias map. Defaults to `null`. |
+
+**Returns:** A unique symbol-like key object (`Object(Symbol(source))`) with `.throw`, `.warn`, and `.error` error handlers attached.
+
+---
+
+### `newErrorHandler(modName?)`
+
+Creates a namespaced error handler. The namespace appears in `error.name` so stack traces remain readable.
+
+| Callable | Behaviour |
+| :--- | :--- |
+| `handler(msg, opts?)` | Throws an `Error`. Accepts optional `{ type, cause }`. |
+| `handler.log(msg, opts?)` | `console.error` with the same formatting. |
+| `handler.warn(msg, opts?)` | `console.warn` with the same formatting. |
+
+```javascript
+import { newErrorHandler } from '@otorp/plugin-utils';
+
+const err = newErrorHandler('myPlugin');
+err('Missing endpoint');             // throws exeption "[myPlugin] Missing endpoint"
+err.log('Deprecated alias used');    // error log       "[myPlugin] Deprecated alias used"
+err.warn('Init failed', { cause });  // warning log     "[myPlugin - <cause.name>] Init failed"
+```
+
+---
+
+### `ref(key, value?)`
+
+Read or write an entry in the Otorp namespace (`Symbol.for('otorp:' + key)` on `root`). Designed for registries, configuration objects, and shared tooling.
+
+* Pass a **truthy** `value` to assign and return it.
+* Omit `value` (or pass a falsy one) to read the current value.
+
+> Falsy values cannot be stored through this helper.
+
+---
+
+### `root`
+
+Minifier-friendly alias for `window`. Allows bundlers to mangle the identifier across the codebase, reducing bundle size without impacting runtime behavior.
+
+---
+
+## 🔌 Plugin registration
+
+### With `@otorp/plugin-utils` (recommended)
+
+```javascript
+import setMod from '@otorp/plugin-utils';
+
+const key = setMod({
+  source: 'myPlugin',
+  endpoints: { "HTMLElement": ['myPlugin.customMethod'] },
+  factory(methodName, ...meta) {
+    return function (...args) { /* … */ };
+  }
+});
+
+key.warn('registered'); // "[myPlugin] registered"
+
+```
+
+### Manual registration (equivalent)
+
+If you prefer not to depend on this package, the same contract applies. Core expects a **Map**, tracks registration instances via `count`, and resolves factories from `window` object:
+
+```javascript
+const source = 'myPlugin';
+const pluginKey = Object(Symbol(source));
+const modulesMap = (window[Symbol.for('otorp:modules')] ??= new Map());
+
+// Core tracks duplicates, so you must supply the count.
+const count = (modulesMap.get(source)?.count || 0) + 1;
+
+modulesMap.set(source, {
+  endpoints: { "HTMLElement": ['myPlugin.customMethod'] },
+  aliases: null,
+  key: pluginKey,
+  count
+});
+
+// The factory must be exposed on the global object using the exact symbol object.
+window[pluginKey] = function factory(methodName, ...meta) {
+  return function (...args) { /* … */ };
+};
+```
+
+`setMod` exists so you do not maintain that boilerplate and the error handler logic in every plugin repo.
+
+---
+
+## ❓ FAQ
+
+### Why a separate package?
+
+Otorp originally bundled core, helpers, and plugin utilities together. Splitting `@otorp/plugin-utils` keeps the core lean and gives plugin authors a stable, shared registration layer without copy-pasting registry code.
+
+### Do I need this package to write a plugin?
+
+No. Any script that writes the correct shape into `otorp:modules` and `root[key]` before Otorp initializes will work. This package is the supported shortcut.
+
+---
+
+## 🤝 Contributing
+
+Contributions, bug reports, and feature requests are welcome.
+
+* **Homepage & Wiki:** [gitlab.com/otorp/plugin-utils/-/wikis/home](https://gitlab.com/otorp/plugin-utils/-/wikis/home)
+* **Issue Tracker:** [gitlab.com/otorp/plugin-utils/-/issues](https://gitlab.com/otorp/plugin-utils/-/issues)
+* **Core Otorp Docs:** [gitlab.com/tdj.dev/otorp](https://gitlab.com/tdj.dev/otorp)

package/index.js

@@ -0,0 +1,173 @@
+// ─── Public exports ───────────────────────────────────────────────────────────
+
+
+/** Register an Otorp plugin module for the initialization pass.
+ *
+ * Stores endpoint and aliases metadata in the shared Otorp modules Map,
+ * attaches module-scoped error helpers to the returned key, and installs
+ * the factory on `root` so Otorp core can resolve it during init.
+ *
+ * > **Load order:** must be called before Otorp core initializes.
+ * > Otorp deletes itself after its init pass — late registrations are ignored.
+ *
+ * @param {object} config - Plugin registration payload.
+ * @param {string} config.source - Unique module identifier. Used as the Map
+ *   key and as the first segment of endpoint query strings.
+ * @param {Record<string, string[]>} config.endpoints - Maps a target prototype
+ *   name to an array of endpoint query strings.
+ *   Format: `"source.meta1.meta2.methodName"` — everything between `source`
+ *   and `methodName` is forwarded to `factory` as metadata.
+ *   (e.g. `{ "HTMLElement": ['myPlugin.meta.customMethod'] }`)
+ * @param {Function} config.factory - Called by Otorp once per resolved
+ *   endpoint. Receives `(methodName, ...meta)` and must return the function
+ *   to install on the prototype, where `this` will be the target instance.
+ * @param {Record<string, string>|null} [config.aliases] - Optional alias
+ *   map consumed by Otorp's aliaser during the init pass.
+ * @returns {Object} A unique symbol-like key object (`Object(Symbol(source))`)
+ *   with `.throw`, `.warn`, and `.error` error handlers attached.
+ *   Otorp resolves the factory via `root[key]` — not through `Symbol.for`.
+ *
+ * @example
+ * import setMod from '@otorp/plugin-utils'
+ * const key = setMod({
+ *   source: 'myPlugin',
+ *   endpoints: { "HTMLElement": ['myPlugin.meta.customMethod'] },
+ *   factory(methodName, ...meta) {
+ *     return function (...args) { /* `this` is the DOM instance *\/ };
+ *   }
+ * });
+ *
+ * key.warn('registered'); // "[myPlugin] registered"
+ */
+export default function ({ source, endpoints, factory, aliases = null }) {
+  typeof factory !== 'function' && err("factory must be a function")
+
+  // Non-global Symbol wrapped in Object() so it can carry properties (.throw,
+  // .warn, .error) while remaining usable as a Map/window key.
+  // Symbol.for is intentionally avoided — each registration must be isolated.
+  const key = Object(Symbol(source)), modErr = newErrorHandler(source);
+
+  // Attach scoped error helpers directly on the key so plugin authors can use
+  // them without importing newErrorHandler separately.
+  Object.defineProperties(key, propsDesc(modErr, modErr.log, modErr.warn));
+
+  // Track registration count so Otorp core can warn on duplicate source names
+  // (same source registered twice, or two plugins sharing the same identifier).
+  const count = (get(source)?.count || 0) + 1
+
+  set(source, { endpoints, aliases, key, count });
+
+  // Install factory under the unique key on root. Otorp reads root[key] during
+  // its init pass — it never uses Symbol.for to look up plugin factories.
+  return (root[key] = factory), key;
+}
+
+/** Creates a namespaced error handler.
+ *
+ * Returns a callable that throws an `Error`. The namespace appears in
+ * `error.name` so stack traces remain readable.
+ * `.warn` and `.log` variants emit to the console instead of throwing.
+ *
+ * @param {string} [modName] - Namespace prefix written to `error.name`.
+ * @returns {((msg: string, options?: { type?: string, cause?: any }) => never) & { warn: Function, log: Function }}
+ *
+ * @example
+ * const err = newErrorHandler('myPlugin');
+ * err('Missing endpoint');            // throws    — name: "[myPlugin]"
+ * err.log('Deprecated alias used');   // error log — name: "[myPlugin]"
+ * err.warn('Init failed', { cause }); // warns     — name: "[myPlugin - <cause.name>]"
+ */
+export function newErrorHandler(modName) {
+  let [prefix, separator, suffix] = modName ? [`[${modName}`, "-", "]"] : ["", "", ""];
+
+  /** Builds an Error and delegates to the bound `output` sink. */
+  function genErrHandler(msg, { type: errType, cause } = {}) {
+    const error = new Error(msg, { cause }), actualType = errType || cause?.name;
+    error.name = actualType
+      ? (`${prefix} ${separator} ${actualType + suffix}`).trim()
+      : prefix + suffix;
+    // V8-only: removes genErrHandler from the stack trace.
+    // Falls back to a no-op on other engines — full trace is kept.
+    (Error.captureStackTrace || (x => x))(error, genErrHandler);
+    this.output(error)
+  }
+
+  const myErrHandler = genErrHandler.bind({ output(err) { throw err } })
+  myErrHandler.log = genErrHandler.bind({ output(err) { console.error(err) } })
+  myErrHandler.warn = genErrHandler.bind({ output(err) { console.warn(err) } })
+  return myErrHandler
+}
+
+export const
+
+  /** Minifier-friendly alias for `window`.
+   *
+   * Allows bundlers to mangle the identifier across the codebase,
+   * reducing bundle size without impacting runtime behavior.
+   *
+   * @type {Window}
+   */
+  root = window,
+
+  /** Read or write an entry in the Otorp namespace.
+   *
+   * Keys are stored under `Symbol.for('otorp:' + key)` on `root`.
+   * Designed for registries, configuration objects, and shared tooling —
+   * not for arbitrary value storage. Falsy values cannot be written.
+   *
+   * @param {string} key - Entry name.
+   * @param {*} [value] - Truthy value to store. Omit to read.
+   * @returns {*} The stored or newly assigned value.
+   *
+   * @example
+   * ref('modules', new Map()); // write
+   * ref('modules');            // read → same Map instance
+   */
+  ref = (key, value) => value
+    ? (root[sym(refPrefix + key)] = value)
+    : root[sym(refPrefix + key)];
+
+// ─── Private ──────────────────────────────────────────────────────────────────
+
+
+// Builds the descriptor map passed to `Object.defineProperties` on a plugin key.
+// Mutates `propsDescDummy` in place to avoid a per-call object allocation —
+// safe because defineProperties consumes the descriptors synchronously before
+// this function can be called again.
+function propsDesc(_throw, _error, _warn) {
+  propsDescDummy.throw.value = _throw
+  propsDescDummy.error.value = _error
+  propsDescDummy.warn.value = _warn
+  return propsDescDummy
+}
+
+const
+  /** Error handler for this package's own validation and setup failures. */
+  err = newErrorHandler('@otorp/plugin-utils'),
+
+  /** Cached `Symbol.for` to avoid repeated property lookups on each `ref` call. */
+  sym = Symbol.for,
+
+  /** Namespace prefix used by `ref` to scope all Otorp entries on `root`. */
+  refPrefix = 'otorp:',
+
+  /** Bound Map#get and Map#set for the shared modules Map.
+   *
+   * The Map is retrieved (or created) once at module evaluation time.
+   * Methods are bound directly to avoid prototype lookups on every registration.
+   */
+  [get, set] = (map => [map.get.bind(map), map.set.bind(map)])(
+    ref('modules') || ref('modules', new Map)
+  ),
+
+  /** Reusable descriptor map for attaching error helpers to plugin keys.
+   *
+   * Mutated in place by `propsDesc` before each `Object.defineProperties` call.
+   * The defined properties are non-writable and non-configurable on the target
+   * to prevent plugin authors from accidentally overwriting the error helpers.
+   */
+  propsDescDummy = {
+    throw: { value: null, writable: false, configurable: false },
+    error: { value: null, writable: false, configurable: false },
+    warn: { value: null, writable: false, configurable: false },
+  };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@otorp/plugin-utils",
+  "version": "1.0.0-staging.1",
+  "description": "Plugin registration and error-handling utilities for the Otorp ecosystem — minimal, zero side-effects.",
+  "exports": {
+    ".": "./index.js"
+  },
+  "type": "module",
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "javascript",
+    "otorp",
+    "plugin",
+    "utilities",
+    "error-handler",
+    "registry"
+  ],
+  "homepage": "https://gitlab.com/otorp/plugin-utils/-/wikis/home",
+  "bugs": {
+    "url": "https://gitlab.com/otorp/plugin-utils/-/issues"
+  },
+  "author": "TISSOT Davy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/otorp/plugin-utils.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "release": {
+    "branches": [
+      {
+        "name": "main"
+      },
+      {
+        "name": "develop",
+        "prerelease": "staging",
+        "channel": "staging"
+      }
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "package-lock.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ],
+      "@semantic-release/gitlab"
+    ]
+  }
+}