@danceroutine/tango-adapters-core 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Del Moral Lopez
+
+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,82 @@
+# @danceroutine/tango-adapters-core
+
+`@danceroutine/tango-adapters-core` defines the contract that every Tango web-framework adapter implements.
+
+Most Tango application developers will never need this package directly, because they will install a concrete adapter such as `@danceroutine/tango-adapters-express` or `@danceroutine/tango-adapters-next`. This package exists so that Tango can support multiple host frameworks while providing a sane standardization surface for Tango to integrate against. If you are building a new adapter for Fastify, Hono, Koa, or another runtime, this is the boundary you implement against.
+
+## Install
+
+```bash
+pnpm add @danceroutine/tango-adapters-core
+```
+
+## Use cases
+
+Reach for this package when you are working on adapter infrastructure rather than on an application:
+
+- you are implementing a new Tango adapter for a host framework
+- you want to type a function that accepts any Tango-compatible adapter
+- you are reading the adapter layer and want the canonical contract first
+
+If you are building an application, install the concrete adapter for your framework instead.
+
+## Adapter contract
+
+Tango keeps its resource and viewset layer independent of any one HTTP framework. That architectural choice is what allows the same API layer to run inside Express, Next.js, and future integrations. The adapter contract is the point where a framework-specific request lifecycle is translated into Tango's handler model.
+
+That means an adapter is responsible for questions such as:
+
+- how the host framework passes requests and route params
+- how Tango handlers are invoked
+- how a Tango response is turned back into the framework's response type
+
+The contract stays narrow so that adapter authors can focus on translation, rather than having to reimplement Tango's higher-level behavior.
+
+## Quick example
+
+```ts
+import type { FrameworkAdapter } from '@danceroutine/tango-adapters-core';
+
+function registerAdapter(adapter: FrameworkAdapter): FrameworkAdapter {
+    return adapter;
+}
+```
+
+In practice, you usually implement `FrameworkAdapter` in a package of your own and then expose framework-specific registration helpers on top of it.
+
+## Public API
+
+The root export includes:
+
+- `FrameworkAdapter`, the main adapter contract
+- `FrameworkAdapterOptions`, the shared options type
+- `FRAMEWORK_ADAPTER_BRAND` and `isFrameworkAdapter`, which support runtime identification of adapter instances
+
+You can import these from the package root or from the `adapter` subpath, if you're used to Django's domain-drill-down style import paths:
+
+```ts
+import type { FrameworkAdapter } from '@danceroutine/tango-adapters-core';
+import { adapter } from '@danceroutine/tango-adapters-core';
+```
+
+## Documentation
+
+- Official documentation: <https://tangowebframework.dev>
+- Architecture topic: <https://tangowebframework.dev/topics/architecture>
+- Contributor package catalog: <https://tangowebframework.dev/contributors/package-catalog>
+
+## Development
+
+```bash
+pnpm --filter @danceroutine/tango-adapters-core build
+pnpm --filter @danceroutine/tango-adapters-core typecheck
+pnpm --filter @danceroutine/tango-adapters-core test
+```
+
+For the wider contributor workflow, use:
+
+- <https://tangowebframework.dev/contributing>
+
+## License
+
+MIT

package/dist/adapter/FrameworkAdapter.d.ts

@@ -8,9 +8,14 @@ import type { RequestContext, BaseUser } from '@danceroutine/tango-resources';
 export interface FrameworkAdapter<TResponse = Response, THandlerType = unknown, TRequest = unknown> {
     adapt(handler: (ctx: RequestContext, ...args: unknown[]) => Promise<TResponse>, options?: FrameworkAdapterOptions<TRequest>): THandlerType;
 }
+export declare const FRAMEWORK_ADAPTER_BRAND: "tango.adapter.framework";
 /**
  * Options for the framework adapter.
  */
 export interface FrameworkAdapterOptions<TRequest = unknown> {
     getUser?: (request: TRequest) => Promise<BaseUser | null> | BaseUser | null;
 }
+/**
+ * Runtime guard for framework adapter instances using Tango branding.
+ */
+export declare function isFrameworkAdapter(value: unknown): value is FrameworkAdapter;

package/dist/adapter/index.d.ts

@@ -2,3 +2,4 @@
  * Domain boundary barrel: centralizes this subdomain's public contract.
  */
 export type { FrameworkAdapter, FrameworkAdapterOptions } from './FrameworkAdapter';
+export { FRAMEWORK_ADAPTER_BRAND, isFrameworkAdapter } from './FrameworkAdapter';

package/dist/adapter/index.js

@@ -1 +1,3 @@
-import "../adapter-D6a8o0SO.js";
+import { FRAMEWORK_ADAPTER_BRAND, isFrameworkAdapter } from "../adapter-zLqtqfpR.js";
+
+export { FRAMEWORK_ADAPTER_BRAND, isFrameworkAdapter };

package/dist/adapter-zLqtqfpR.js

@@ -0,0 +1,19 @@
+import { __export } from "./chunk-BkvOhyD0.js";
+
+//#region src/adapter/FrameworkAdapter.ts
+const FRAMEWORK_ADAPTER_BRAND = "tango.adapter.framework";
+function isFrameworkAdapter(value) {
+	return typeof value === "object" && value !== null && typeof value.adapt === "function" && value.__tangoBrand === FRAMEWORK_ADAPTER_BRAND;
+}
+
+//#endregion
+//#region src/adapter/index.ts
+var adapter_exports = {};
+__export(adapter_exports, {
+	FRAMEWORK_ADAPTER_BRAND: () => FRAMEWORK_ADAPTER_BRAND,
+	isFrameworkAdapter: () => isFrameworkAdapter
+});
+
+//#endregion
+export { FRAMEWORK_ADAPTER_BRAND, adapter_exports, isFrameworkAdapter };
+//# sourceMappingURL=adapter-zLqtqfpR.js.map

package/dist/adapter-zLqtqfpR.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-zLqtqfpR.js","names":["value: unknown"],"sources":["../src/adapter/FrameworkAdapter.ts","../src/adapter/index.ts"],"sourcesContent":["import type { RequestContext, BaseUser } from '@danceroutine/tango-resources';\n/**\n * Adapter interface for integrating Tango with a given framework.\n * @template TResponse - The response type.\n * @template THandlerType - The handler type.\n * @template TRequest - The request type.\n */\nexport interface FrameworkAdapter<TResponse = Response, THandlerType = unknown, TRequest = unknown> {\n    adapt(\n        handler: (ctx: RequestContext, ...args: unknown[]) => Promise<TResponse>,\n        options?: FrameworkAdapterOptions<TRequest>\n    ): THandlerType;\n}\n\nexport const FRAMEWORK_ADAPTER_BRAND = 'tango.adapter.framework' as const;\n\n/**\n * Options for the framework adapter.\n */\nexport interface FrameworkAdapterOptions<TRequest = unknown> {\n    getUser?: (request: TRequest) => Promise<BaseUser | null> | BaseUser | null;\n}\n\ntype FrameworkAdapterShape = {\n    __tangoBrand?: unknown;\n    adapt?: unknown;\n};\n\n/**\n * Runtime guard for framework adapter instances using Tango branding.\n */\nexport function isFrameworkAdapter(value: unknown): value is FrameworkAdapter {\n    return (\n        typeof value === 'object' &&\n        value !== null &&\n        typeof (value as FrameworkAdapterShape).adapt === 'function' &&\n        (value as FrameworkAdapterShape).__tangoBrand === FRAMEWORK_ADAPTER_BRAND\n    );\n}\n","/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport type { FrameworkAdapter, FrameworkAdapterOptions } from './FrameworkAdapter';\nexport { FRAMEWORK_ADAPTER_BRAND, isFrameworkAdapter } from './FrameworkAdapter';\n"],"mappings":";;;MAca,0BAA0B;AAiBhC,SAAS,mBAAmBA,OAA2C;AAC1E,eACW,UAAU,YACjB,UAAU,eACF,MAAgC,UAAU,cACjD,MAAgC,iBAAiB;AAEzD"}

package/dist/chunk-BkvOhyD0.js

@@ -0,0 +1,12 @@
+
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+
+//#endregion
+export { __export };

package/dist/domain/index.d.ts

@@ -0,0 +1,3 @@
+export { InternalHttpMethod } from './internal/InternalHttpMethod';
+export { InternalActionScope } from './internal/InternalActionScope';
+export { InternalActionMatchKind } from './internal/InternalActionMatchKind';

package/dist/domain/index.js

@@ -0,0 +1,3 @@
+import { InternalActionMatchKind, InternalActionScope, InternalHttpMethod } from "../domain-12_cfgMU.js";
+
+export { InternalActionMatchKind, InternalActionScope, InternalHttpMethod };

package/dist/domain/internal/InternalActionMatchKind.d.ts

@@ -0,0 +1,5 @@
+export declare const InternalActionMatchKind: {
+    readonly DETAIL: "detail";
+    readonly COLLECTION: "collection";
+    readonly METHOD_NOT_ALLOWED: "method_not_allowed";
+};

package/dist/domain/internal/InternalActionScope.d.ts

@@ -0,0 +1,4 @@
+export declare const InternalActionScope: {
+    readonly DETAIL: "detail";
+    readonly COLLECTION: "collection";
+};

package/dist/domain/internal/InternalHttpMethod.d.ts

@@ -0,0 +1,7 @@
+export declare const InternalHttpMethod: {
+    readonly GET: "GET";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly PATCH: "PATCH";
+    readonly DELETE: "DELETE";
+};

package/dist/domain-12_cfgMU.js

@@ -0,0 +1,38 @@
+import { __export } from "./chunk-BkvOhyD0.js";
+
+//#region src/domain/internal/InternalHttpMethod.ts
+const InternalHttpMethod = {
+	GET: "GET",
+	POST: "POST",
+	PUT: "PUT",
+	PATCH: "PATCH",
+	DELETE: "DELETE"
+};
+
+//#endregion
+//#region src/domain/internal/InternalActionScope.ts
+const InternalActionScope = {
+	DETAIL: "detail",
+	COLLECTION: "collection"
+};
+
+//#endregion
+//#region src/domain/internal/InternalActionMatchKind.ts
+const InternalActionMatchKind = {
+	DETAIL: "detail",
+	COLLECTION: "collection",
+	METHOD_NOT_ALLOWED: "method_not_allowed"
+};
+
+//#endregion
+//#region src/domain/index.ts
+var domain_exports = {};
+__export(domain_exports, {
+	InternalActionMatchKind: () => InternalActionMatchKind,
+	InternalActionScope: () => InternalActionScope,
+	InternalHttpMethod: () => InternalHttpMethod
+});
+
+//#endregion
+export { InternalActionMatchKind, InternalActionScope, InternalHttpMethod, domain_exports };
+//# sourceMappingURL=domain-12_cfgMU.js.map

package/dist/domain-12_cfgMU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-12_cfgMU.js","names":[],"sources":["../src/domain/internal/InternalHttpMethod.ts","../src/domain/internal/InternalActionScope.ts","../src/domain/internal/InternalActionMatchKind.ts","../src/domain/index.ts"],"sourcesContent":["export const InternalHttpMethod = {\n    GET: 'GET',\n    POST: 'POST',\n    PUT: 'PUT',\n    PATCH: 'PATCH',\n    DELETE: 'DELETE',\n} as const;\n","export const InternalActionScope = {\n    DETAIL: 'detail',\n    COLLECTION: 'collection',\n} as const;\n","export const InternalActionMatchKind = {\n    DETAIL: 'detail',\n    COLLECTION: 'collection',\n    METHOD_NOT_ALLOWED: 'method_not_allowed',\n} as const;\n","export { InternalHttpMethod } from './internal/InternalHttpMethod';\nexport { InternalActionScope } from './internal/InternalActionScope';\nexport { InternalActionMatchKind } from './internal/InternalActionMatchKind';\n"],"mappings":";;;MAAa,qBAAqB;CAC9B,KAAK;CACL,MAAM;CACN,KAAK;CACL,OAAO;CACP,QAAQ;AACX;;;;MCNY,sBAAsB;CAC/B,QAAQ;CACR,YAAY;AACf;;;;MCHY,0BAA0B;CACnC,QAAQ;CACR,YAAY;CACZ,oBAAoB;AACvB"}

package/dist/index.d.ts

@@ -3,4 +3,7 @@
  * top-level symbols for TS-native ergonomic imports.
  */
 export * as adapter from './adapter/index';
+export * as domain from './domain/index';
 export type { FrameworkAdapter, FrameworkAdapterOptions } from './adapter/index';
+export { FRAMEWORK_ADAPTER_BRAND, isFrameworkAdapter } from './adapter/index';
+export { InternalHttpMethod, InternalActionScope, InternalActionMatchKind } from './domain/index';

package/dist/index.js

@@ -1,3 +1,4 @@
-import { adapter_exports } from "./adapter-D6a8o0SO.js";
+import { FRAMEWORK_ADAPTER_BRAND, adapter_exports, isFrameworkAdapter } from "./adapter-zLqtqfpR.js";
+import { InternalActionMatchKind, InternalActionScope, InternalHttpMethod, domain_exports } from "./domain-12_cfgMU.js";
 
-export { adapter_exports as adapter };
+export { FRAMEWORK_ADAPTER_BRAND, InternalActionMatchKind, InternalActionScope, InternalHttpMethod, adapter_exports as adapter, domain_exports as domain, isFrameworkAdapter };

package/package.json

@@ -1,49 +1,55 @@
 {
-    "name": "@danceroutine/tango-adapters-core",
-    "version": "0.1.0",
-    "description": "Core types and utilities for Tango adapters",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./adapter": {
-            "types": "./dist/adapter/index.d.ts",
-            "import": "./dist/adapter/index.js"
-        }
+  "name": "@danceroutine/tango-adapters-core",
+  "version": "1.0.0",
+  "description": "Core types and utilities for Tango adapters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "files": [
-        "dist"
-    ],
-    "scripts": {
-        "build": "tsdown",
-        "test": "vitest run --coverage",
-        "test:watch": "vitest",
-        "typecheck": "tsc --noEmit"
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
     },
-    "keywords": [
-        "tango",
-        "adapters",
-        "core",
-        "adapter"
-    ],
-    "author": "Pedro Del Moral Lopez",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/danceroutine/tango.git",
-        "directory": "packages/adapters/core"
-    },
-    "dependencies": {
-        "@danceroutine/tango-resources": "workspace:*"
-    },
-    "devDependencies": {
-        "@types/node": "^22.9.0",
-        "tsdown": "^0.4.0",
-        "typescript": "^5.6.3",
-        "vitest": "^4.0.6"
+    "./domain": {
+      "types": "./dist/domain/index.d.ts",
+      "import": "./dist/domain/index.js"
     }
-}
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "tango",
+    "adapters",
+    "core",
+    "adapter"
+  ],
+  "author": "Pedro Del Moral Lopez",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danceroutine/tango.git",
+    "directory": "packages/adapters/core"
+  },
+  "dependencies": {
+    "@danceroutine/tango-resources": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsdown": "^0.4.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.6"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "pnpm run typecheck:prod && pnpm run typecheck:test",
+    "typecheck:prod": "tsc --noEmit -p tsconfig.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.tests.json"
+  }
+}

package/dist/adapter-D6a8o0SO.js

@@ -1,7 +0,0 @@
-
-//#region src/adapter/index.ts
-var adapter_exports = {};
-
-//#endregion
-export { adapter_exports };
-//# sourceMappingURL=adapter-D6a8o0SO.js.map

package/dist/adapter-D6a8o0SO.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter-D6a8o0SO.js","names":[],"sources":["../src/adapter/index.ts"],"sourcesContent":["/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport type { FrameworkAdapter, FrameworkAdapterOptions } from './FrameworkAdapter';\n"],"mappings":""}