@arkormx/plugin-clear-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 h3ravel
+
+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,95 @@
+# @arkormx/plugin-clear-router
+
+Clear Router plugin for resolving Arkormx models from route parameters.
+
+```ts
+import { Router } from 'clear-router/express'
+import { clearRouterPlugin } from '@arkormx/plugin-clear-router'
+
+Router.use(clearRouterPlugin)
+```
+
+## What it does
+
+When a controller action is decorated with `@Bind()`, the plugin checks each bound argument. If the argument type extends `arkormx`'s `Model`, the plugin resolves the matching route parameter and passes the hydrated model instance to the controller.
+
+```ts
+import { Bind } from 'clear-router/decorators'
+import { Controller } from 'clear-router'
+import { User } from './models/User'
+
+class UserController extends Controller {
+    @Bind()
+    async show (user: User) {
+        return {
+            data: user,
+        }
+    }
+}
+
+Router.get('/users/:user', [UserController, 'show'])
+```
+
+For `/users/1`, the `user` argument is resolved with:
+
+```ts
+await User.query().find('1', 'id')
+```
+
+Non-model arguments continue to resolve through Clear Router's container.
+
+## Route Parameter Names
+
+The plugin derives the route parameter name from the model class name:
+
+| Model class | Route parameter |
+| --- | --- |
+| `User` | `:user` or `{user}` |
+| `Profile` | `:profile` or `{profile}` |
+| `UserModel` | `:user` or `{user}` |
+
+Both Clear Router parameter styles are supported:
+
+```ts
+Router.get('/users/:user', [UserController, 'show'])
+Router.get('/users/{user}', [UserController, 'show'])
+```
+
+## Custom Binding Fields
+
+Use `:name:field` or `{name:field}` to resolve by a non-primary column:
+
+```ts
+Router.get('/users/{user:email}', [UserController, 'show'])
+```
+
+For `/users/jane@example.com`, the plugin runs:
+
+```ts
+await User.query().find('jane@example.com', 'email')
+```
+
+## Custom Model Resolution
+
+Models can override the default lookup by defining `resolveRouteBinding`:
+
+```ts
+import { Model } from 'arkormx'
+
+export class User extends Model {
+    async resolveRouteBinding (value: unknown, field = 'id') {
+        return await User.query()
+            .whereKey(field as 'id', value as never)
+            .firstOrFail()
+    }
+}
+```
+
+The method receives the raw route value and the binding field, if one was provided in the route.
+
+## Development
+
+```sh
+pnpm test
+pnpm build
+```

package/dist/index.cjs

@@ -0,0 +1,88 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let clear_router_decorators_setup = require("clear-router/decorators/setup");
+let arkormx = require("arkormx");
+let clear_router_core = require("clear-router/core");
+
+//#region src/helpers.ts
+async function resolveRouteBinding(modelClass, value, field) {
+	const instance = new modelClass();
+	if (typeof instance.resolveRouteBinding === "function") return await instance.resolveRouteBinding(value, field);
+	const resolvedField = field ?? modelClass.getPrimaryKey();
+	return await modelClass.query().where({ [resolvedField]: value }).firstOrFail();
+}
+const isModel = (cls) => {
+	return typeof cls === "function" && cls.prototype instanceof arkormx.Model;
+};
+const getRouteBindingName = (modelClass) => {
+	return modelClass.name.replace(/Model$/, "").replace(/^[A-Z]/, (letter) => letter.toLowerCase());
+};
+
+//#endregion
+//#region src/RouteBindingParamExtractor.ts
+var RouteBindingParamExtractor = class {
+	static extract(routePath, requestPath, params, bindingName) {
+		const routeSegments = this.normalizePath(routePath);
+		const requestSegments = this.normalizePath(requestPath);
+		const positionalParams = routeSegments.map((segment, index) => {
+			const match = this.getRouteParamMatch(segment);
+			if (!match) return;
+			return {
+				name: match.name,
+				field: match.field,
+				value: requestSegments[index]
+			};
+		}).filter((param) => {
+			return Boolean(param);
+		});
+		const matched = positionalParams.find((param) => {
+			return param?.name === bindingName;
+		});
+		if (matched) return matched;
+		const fallbackValues = Object.values(params);
+		const bindingIndex = positionalParams.findIndex((param) => {
+			return param?.name === bindingName;
+		});
+		if (bindingIndex >= 0) return {
+			name: bindingName,
+			value: fallbackValues[bindingIndex]
+		};
+	}
+	static normalizePath(path) {
+		return path.split("/").filter(Boolean);
+	}
+	static getRouteParamMatch(segment) {
+		const colonMatch = segment.match(/^:([^/?#:]+)(?::([^/?#]+))?$/);
+		if (colonMatch) return {
+			name: colonMatch[1],
+			field: colonMatch[2]
+		};
+		const braceMatch = segment.match(/^\{([^}:]+)(?::([^}]+))?\}$/);
+		if (braceMatch) return {
+			name: braceMatch[1],
+			field: braceMatch[2]
+		};
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const clearRouterPlugin = (0, clear_router_core.definePlugin)({
+	name: "plugin-clear-router",
+	async setup({ resolveArguments, configureDefaults }) {
+		configureDefaults({ container: {
+			enabled: true,
+			autoDiscover: true
+		} });
+		resolveArguments(async ({ request, tokens }) => {
+			return await Promise.all(tokens.map(async (token) => {
+				if (!isModel(token)) return await clear_router_decorators_setup.Container.resolve(token, request.ctx, true);
+				const binding = RouteBindingParamExtractor.extract(request.route.path, request.path, request.params, getRouteBindingName(token));
+				if (!binding) return await clear_router_decorators_setup.Container.resolve(token, request.ctx, true);
+				return await resolveRouteBinding(token, binding.value, binding.field);
+			}));
+		});
+	}
+});
+
+//#endregion
+exports.clearRouterPlugin = clearRouterPlugin;

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+import * as clear_router_core0 from "clear-router/core";
+
+//#region src/types.d.ts
+interface Options {
+  /**
+   * Absolute path or path relative to cwd where models are stored
+   *
+   * @default arkormx default paths.models config
+   */
+  modelsPath?: string;
+}
+//#endregion
+//#region src/index.d.ts
+declare const clearRouterPlugin: clear_router_core0.ClearRouterPlugin<Options>;
+//#endregion
+export { clearRouterPlugin };

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import { Model } from "arkormx";
+import * as clear_router_core0 from "clear-router/core";
+
+//#region src/types.d.ts
+interface Options {
+  /**
+   * Absolute path or path relative to cwd where models are stored
+   *
+   * @default arkormx default paths.models config
+   */
+  modelsPath?: string;
+}
+//#endregion
+//#region src/index.d.ts
+declare const clearRouterPlugin: clear_router_core0.ClearRouterPlugin<Options>;
+//#endregion
+export { clearRouterPlugin };

package/dist/index.mjs

@@ -0,0 +1,87 @@
+import { Container } from "clear-router/decorators/setup";
+import { Model } from "arkormx";
+import { definePlugin } from "clear-router/core";
+
+//#region src/helpers.ts
+async function resolveRouteBinding(modelClass, value, field) {
+	const instance = new modelClass();
+	if (typeof instance.resolveRouteBinding === "function") return await instance.resolveRouteBinding(value, field);
+	const resolvedField = field ?? modelClass.getPrimaryKey();
+	return await modelClass.query().where({ [resolvedField]: value }).firstOrFail();
+}
+const isModel = (cls) => {
+	return typeof cls === "function" && cls.prototype instanceof Model;
+};
+const getRouteBindingName = (modelClass) => {
+	return modelClass.name.replace(/Model$/, "").replace(/^[A-Z]/, (letter) => letter.toLowerCase());
+};
+
+//#endregion
+//#region src/RouteBindingParamExtractor.ts
+var RouteBindingParamExtractor = class {
+	static extract(routePath, requestPath, params, bindingName) {
+		const routeSegments = this.normalizePath(routePath);
+		const requestSegments = this.normalizePath(requestPath);
+		const positionalParams = routeSegments.map((segment, index) => {
+			const match = this.getRouteParamMatch(segment);
+			if (!match) return;
+			return {
+				name: match.name,
+				field: match.field,
+				value: requestSegments[index]
+			};
+		}).filter((param) => {
+			return Boolean(param);
+		});
+		const matched = positionalParams.find((param) => {
+			return param?.name === bindingName;
+		});
+		if (matched) return matched;
+		const fallbackValues = Object.values(params);
+		const bindingIndex = positionalParams.findIndex((param) => {
+			return param?.name === bindingName;
+		});
+		if (bindingIndex >= 0) return {
+			name: bindingName,
+			value: fallbackValues[bindingIndex]
+		};
+	}
+	static normalizePath(path) {
+		return path.split("/").filter(Boolean);
+	}
+	static getRouteParamMatch(segment) {
+		const colonMatch = segment.match(/^:([^/?#:]+)(?::([^/?#]+))?$/);
+		if (colonMatch) return {
+			name: colonMatch[1],
+			field: colonMatch[2]
+		};
+		const braceMatch = segment.match(/^\{([^}:]+)(?::([^}]+))?\}$/);
+		if (braceMatch) return {
+			name: braceMatch[1],
+			field: braceMatch[2]
+		};
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const clearRouterPlugin = definePlugin({
+	name: "plugin-clear-router",
+	async setup({ resolveArguments, configureDefaults }) {
+		configureDefaults({ container: {
+			enabled: true,
+			autoDiscover: true
+		} });
+		resolveArguments(async ({ request, tokens }) => {
+			return await Promise.all(tokens.map(async (token) => {
+				if (!isModel(token)) return await Container.resolve(token, request.ctx, true);
+				const binding = RouteBindingParamExtractor.extract(request.route.path, request.path, request.params, getRouteBindingName(token));
+				if (!binding) return await Container.resolve(token, request.ctx, true);
+				return await resolveRouteBinding(token, binding.value, binding.field);
+			}));
+		});
+	}
+});
+
+//#endregion
+export { clearRouterPlugin };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@arkormx/plugin-clear-router",
+  "version": "0.1.0",
+  "description": "Clear Router plugin for resolving Arkormx models from route parameters.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "resora",
+    "clear-router",
+    "express",
+    "h3",
+    "plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "arkormx": "2.0.7"
+  },
+  "peerDependencies": {
+    "clear-router": "^2.6.0"
+  },
+  "peerDependenciesMeta": {
+    "clear-router": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "clear-router": "^2.6.0",
+    "express": "^5.2.1",
+    "parasito": "^0.1.6"
+  },
+  "scripts": {
+    "test": "vitest run tests/*.spec.ts",
+    "build": "tsdown",
+    "lint": "eslint src tests --ext .ts",
+    "version:patch": "pnpm version patch"
+  }
+}