@slimlib/injector 1.0.6 → 2.0.0

package/README.md

@@ -2,79 +2,146 @@
 
 Parameter names based dependency injector for nodejs.
 
-*Limitations*
+[Changelog](./CHANGELOG.md)
+
+## API
+
+### createInject()
 
-- does not work with default parameters
-- minification of code is not supported
+Returns a new instance of an injector function to work with.
+
+_Limitations_
+
+- minification of code is not supported (use `createInjectAnnotated` instead)
 - not typesafe
-- classes not supported
 - slower than a normal function call
 
-[Changelog](./CHANGELOG.md)
+### createInjectAnnotated()
 
-## API
+Returns a new instance of an injector function that uses AngularJS-style array annotation for minification safety.
 
-### createInject()
+Instead of parsing parameter names, it expects dependencies to be specified as strings in an array before the function:
+
+```typescript
+inject(["dep1", "dep2", (dep1, dep2) => { ... }]);
+```
 
-returns a new instance of an injector function to work with.
+This allows code to be minified since the dependency names are preserved as strings.
+
+> **Note:** The input array is mutated during injection (the function is removed via `pop()`). Always use inline array literals or create a fresh array for each call if you need to reuse the dependency list.
 
 ### injector(function, scope)
 
-injects arguments into function and invokes it
+Injects arguments into function and invokes it.
 
-`function` - *required*, function to inject parameters and call
-`scope` - *optional*, *default* = `{}`, this argument for the function
+`function` - _required_, function to inject parameters and call (or annotated array for `createInjectAnnotated`)
+`scope` - _optional_, _default_ = `{}`, this argument for the function
 
 ### $provide(key, value)
 
-predefined injectable function
+Predefined injectable function.
 
 `key` - string, required
 `value` - unknown
 
-to get it, inject it into the function
+To get it, inject it into the function:
 
 ```typescript
 inject(($provide: Provider) => {
-    $provide('service', service);
+  $provide("service", service);
 });
 ```
 
-## Example
+## Examples
+
+### Using createInject (development / non-minified)
 
 ```typescript
-import createInject from '@slimlib/injector';
+import { createInject } from "@slimlib/injector";
 
 const inject = createInject();
 
 inject(($provide: Provider) => {
-    $provide('config', {
-        url: 'http://example.com/json',
-        format: 'json'
-    });
+  $provide("config", {
+    url: "http://example.com/json",
+    format: "json",
+  });
 });
 
 inject(async (config: Json) => {
+  const data = await fetch(config.url);
+  const result = config.json ? await data.json() : data;
+  // and so on
+});
+```
+
+### Using createInjectAnnotated (minification-safe)
+
+```typescript
+import { createInjectAnnotated } from "@slimlib/injector";
+
+const inject = createInjectAnnotated();
+
+inject([
+  "$provide",
+  ($provide: Provider) => {
+    $provide("config", {
+      url: "http://example.com/json",
+      format: "json",
+    });
+  },
+]);
+
+inject([
+  "config",
+  async (config: Json) => {
     const data = await fetch(config.url);
     const result = config.json ? await data.json() : data;
     // and so on
+  },
+]);
+```
+
+This style is similar to AngularJS's dependency injection annotation:
+
+```javascript
+// Before minification
+angular.module("App", []).controller("MyController", function ($scope) {
+  $scope.value = "test";
+});
+
+// After minification (broken)
+angular.module("App", []).controller("MyController", function (a) {
+  a.value = "test";
 });
+
+// With array annotation (works after minification)
+angular.module("App", []).controller("MyController", [
+  "$scope",
+  function (a) {
+    a.value = "test";
+  },
+]);
 ```
 
+## Build-time Swapping
+
+You can use `createInject` during development and swap to `createInjectAnnotated` at build time for production. This can be done with build tools like Rollup, Webpack, or esbuild by aliasing the import.
+
 # FAQ
 
 1. Is it a good solution to mock something in unit tests?
 
-- no, please use [jest](https://jestjs.io/), [vitest](https://vitest.dev/), [proxyquire](https://www.npmjs.com/package/proxyquire), [proxyrequire](https://www.npmjs.com/package/proxyrequire) and other similar approaches to mock modules.
+- No, please use [jest](https://jestjs.io/), [vitest](https://vitest.dev/), [proxyquire](https://www.npmjs.com/package/proxyquire), [proxyrequire](https://www.npmjs.com/package/proxyrequire) and other similar approaches to mock modules.
 
 2. Is it a good solution to use in frontend code?
 
-- no, it will not work after minification
+- `createInject` will not work after minification, but `createInjectAnnotated` is designed to work with minified code.
 
 3. Is it good for nodejs applications?
 
-- only in some edge cases, please use singletons/factories/something else if possible
+- Only in some edge cases, please use singletons/factories/something else if possible.
 
 # License
 
-[MIT](https://github.com/kshutkin/slimlib/blob/main/LICENSE)
+[MIT](https://github.com/kshutkin/slimlib/blob/main/LICENSE)

package/package.json

@@ -1,27 +1,25 @@
 {
   "type": "module",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "name": "@slimlib/injector",
   "description": "Parameter names based dependency injector for nodejs",
   "license": "MIT",
   "author": "Konstantin Shutkin",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "default": "./dist/index.mjs"
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
     },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
+  "types": "./types/index.d.ts",
   "files": [
-    "dist"
+    "types"
   ],
-  "engines": {
-    "node": ">=15"
+  "dependencies": {
+    "@slimlib/get-parameter-names": "^1.0.0"
   },
   "repository": {
     "type": "git",
@@ -36,8 +34,5 @@
     "injector",
     "dependency injection",
     "nodejs"
-  ],
-  "dependencies": {
-    "get-parameter-names": "0.3.0"
-  }
+  ]
 }

package/src/index.js

@@ -0,0 +1,58 @@
+import { getParameterNames } from '@slimlib/get-parameter-names';
+
+/**
+ * @typedef {(key: string, value: unknown) => void} Provider
+ */
+
+/**
+ * @typedef {[...string[], (...args: any[]) => any]} AnnotatedFunction
+ */
+
+/**
+ * @returns {<F extends (...args: any[]) => any>(func: F, scope?: object) => ReturnType<F>}
+ */
+export function createInject() {
+    /** @type {Record<string, unknown>} */
+    const dependencies = Object.create(null);
+
+    dependencies.$provide = /** @type {Provider} */ (
+        (key, value) => {
+            dependencies[key] = value;
+        }
+    );
+
+    return (func, scope = {}) =>
+        func.apply(
+            scope,
+            getParameterNames(func).map((/** @type {string} */ key) => dependencies[key])
+        );
+}
+
+/**
+ * Creates an injector that uses AngularJS-style array annotation for minification safety.
+ * Instead of parsing parameter names, it expects dependencies to be specified as strings
+ * in an array before the function: ['dep1', 'dep2', function(dep1, dep2) { ... }]
+ * @returns {<F extends (...args: any[]) => any>(funcOrArray: F | [...string[], F], scope?: object) => ReturnType<F>}
+ */
+export function createInjectAnnotated() {
+    /** @type {Record<string, unknown>} */
+    const dependencies = Object.create(null);
+
+    dependencies.$provide = /** @type {Provider} */ (
+        (key, value) => {
+            dependencies[key] = value;
+        }
+    );
+
+    return (funcOrArray, scope = {}) => {
+        if (Array.isArray(funcOrArray)) {
+            const func = /** @type {(...args: any[]) => any} */ (funcOrArray.pop());
+            return func.apply(
+                scope,
+                /** @type {string[]} */ (funcOrArray).map(key => dependencies[key])
+            );
+        }
+        // If not an array, just call the function with no dependencies
+        return funcOrArray.apply(scope, []);
+    };
+}

package/types/index.d.ts

@@ -0,0 +1,15 @@
+declare module '@slimlib/injector' {
+	export function createInject(): <F extends (...args: any[]) => any>(func: F, scope?: object) => ReturnType<F>;
+	/**
+	 * Creates an injector that uses AngularJS-style array annotation for minification safety.
+	 * Instead of parsing parameter names, it expects dependencies to be specified as strings
+	 * in an array before the function: ['dep1', 'dep2', function(dep1, dep2) { ... }]
+	 * */
+	export function createInjectAnnotated(): <F extends (...args: any[]) => any>(funcOrArray: F | [...string[], F], scope?: object) => ReturnType<F>;
+	export type Provider = (key: string, value: unknown) => void;
+	export type AnnotatedFunction = [...string[], (...args: any[]) => any];
+
+	export {};
+}
+
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1,17 @@
+{
+	"version": 3,
+	"file": "index.d.ts",
+	"names": [
+		"createInject",
+		"createInjectAnnotated",
+		"Provider",
+		"AnnotatedFunction"
+	],
+	"sources": [
+		"../src/index.js"
+	],
+	"sourcesContent": [
+		null
+	],
+	"mappings": ";iBAagBA,YAAYA;;;;;;iBAuBZC,qBAAqBA;aAjCeC,QAAQA;aAIPC,iBAAiBA"
+}

package/dist/index.cjs

@@ -1,15 +0,0 @@
-'use strict';
-
-var getParameterNames = require('get-parameter-names');
-
-var index = () => {
-    const dependencies = Object.create(null);
-    dependencies['$provide'] = (key, value) => {
-        dependencies[key] = value;
-    };
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return (func, scope = {}) => func.apply(scope, getParameterNames(func)
-        .map((key) => dependencies[key]));
-};
-
-module.exports = index;

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export type Provider = (key: string, value: unknown) => void;
-declare const _default: () => <F extends (...args: any[]) => any>(func: F, scope?: object) => ReturnType<F>;
-export default _default;

package/dist/index.mjs

@@ -1,13 +0,0 @@
-import getParameterNames from 'get-parameter-names';
-
-var index = () => {
-    const dependencies = Object.create(null);
-    dependencies['$provide'] = (key, value) => {
-        dependencies[key] = value;
-    };
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return (func, scope = {}) => func.apply(scope, getParameterNames(func)
-        .map((key) => dependencies[key]));
-};
-
-export { index as default };