Otorp.js

A Safe, Governed Prototype Extension Engine

🎯 Objective

Otorp is an architecture-grade governance engine for extending native JavaScript and DOM prototypes safely and consistently.

It does not add any methods by default. Instead, it provides a structured, configuration-driven runtime that plugins and modules use to install aliases or custom methods onto native prototypes — with built-in collision avoidance, naming conventions, and selective exclusion.

• 📦 Installation
• ⚙️ How It Works
• 🛡️ Configuration
• 🔌 Plugins
• ❓ FAQ
• 🤝 Contributing

📦 Installation

Otorp runs a single initialization pass then disappears from memory. All plugins and modules must be registered before Otorp loads.

<!-- 1. Optional configuration -->
<script>
  otorpConfig = { case: 'pascal', prefix: '', conflict: false }
</script>

<!-- 2. Plugins (must come before Otorp) -->
<script src="path/to/my-plugin.js"></script>

<!-- 3. Otorp core (always last) -->
<script src="path/to/otorp.js"></script>

Without at least one plugin or module registered, Otorp does nothing.

⚙️ How It Works

Otorp processes each registered plugin's endpoints during its init pass:

1. Resolves each query string to a native descriptor or a plugin-provided factory.
2. Applies naming conventions (case, prefix) and alias maps.
3. Installs the resulting descriptor on the target prototype via Object.defineProperty — non-enumerable, writable, configurable.
4. Exits. No runtime footprint remains.

Query string format:

"source.meta1.meta2.methodName"
   │                    └── method name installed on the prototype
   │      └────────────── optional metadata forwarded to the factory
   └────────────────────── "Element", "Math", "Document", or a plugin source name

For native sources (Element, Math, Document, Array…), no factory is needed — Otorp retrieves the descriptor directly from the native prototype. For plugin sources, Otorp calls the registered factory with (methodName, ...meta) and installs the returned function.

🛡️ Configuration

All options are optional. Define otorpConfig as a plain object before loading Otorp.

| Option | Type | Default | Description | | :--- | :--- | :---: | :--- | | conflict | boolean | false | false — Safety default: skips any alias that already exists on the target prototype. Prevents overwriting native or third-party properties. true — Semantic lock: installs all aliases unconditionally. Use when you need guaranteed long-term behavioral stability. | | prefix | string | "" | Prepends a string to every alias (e.g. "$" → element.$setAttr()). Eliminates collision risk at the cost of slightly longer names. | | case | string | "camel" | Casing convention for generated aliases. Accepted values: "camel", "pascal", "snake". Non-camel conventions further reduce native collision risk since native methods are always camelCase. | | exclude | string[] | [] | Native method names to skip entirely, regardless of which plugin registers them. Useful for controlled adoption of new native standards. | | warn | boolean | false | When true, logs a summary of all added and skipped methods to the console via console.warn after Otorp's init pass completes. Intended for development and debugging only. |

<script>
  otorpConfig = {
    case: 'pascal',       // → element.SetAttr(), document.Query()
    prefix: '',
    conflict: true,       // Semantic lock — override existing properties
    exclude: ['removeAttribute'],
    warn: true            // Log added/skipped methods via console.warn (dev only)
  }
</script>

🔌 Plugins

Any script that registers into otorp:modules before Otorp loads is a valid plugin. The recommended way is via @otorp/plugin-utils:

import setMod from '@otorp/plugin-utils';

setMod({
  source: 'myPlugin',
  endpoints: {
    HTMLElement: ['myPlugin.customMethod', 'myPlugin.meta.anotherMethod']
  },
  factory(methodName, ...meta) {
    return function (...args) {
      // `this` is the target instance
    };
  },
  aliases: {
    customMethod: ['custom', 'method']
  }
});

For plugins that only alias native methods, factory can be omitted — Otorp resolves descriptors directly from the native prototype.

See @otorp/plugin-utils for the full registration API and @otorp/native-aliases for a reference implementation.

❓ FAQ

Is Otorp a framework? No. It runs once at init time, configures prototypes, and exits. It imposes no project structure, rendering model, or runtime dependency.

Is prototype extension risky?
It can be without governance. Otorp mitigates this with:

1. warn: true — Predictability is the main issue of prototype mutation.List all of otorp's
2. conflict: false (default) — never overwrites existing prototype properties.
3. prefix / case — makes collisions structurally impossible when used.
4. exclude — opt out of specific utility at any time.

Does Otorp add anything by default? No. Without a plugin or module registered, Otorp's init pass completes instantly and leaves no trace.

How does Otorp handle future native additions?

• conflict: false (default): new native methods automatically take precedence over Otorp aliases — no action needed.
• conflict: true: Otorp aliases hold. Use exclude to selectively yield to specific native additions when ready.

🤝 Contributing

Contributions, bug reports, and feature requests are welcome! Please read CONTRIBUTING.md for guidelines.

• Issue Tracker: gitlab.com/tdj.dev/otorp/-/issues
• native-aliases: gitlab.com/otorp/native-aliases
• plugin-utils: gitlab.com/otorp/plugin-utils
• helpers: gitlab.com/otorp/helpers