@spaceteams/warp 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,107 @@
+# 🧵 Warp
+> Compose once. Resolve per request.
+
+`warp` is a small runtime for composing application components and resolving them
+against an ambient context.
+
+It helps structure repositories, services and use cases as an explicit dependency
+graph while keeping request context, transactions, tracing and tests easy to manage.
+
+No container magic. No autowiring. Just explicit composition and scoped execution.
+
+---
+
+## Why “warp”?
+
+The name comes from two places.
+
+In physics, **warp** suggests speed.  
+In weaving, the **warp threads** are the fixed threads that hold a fabric together.
+
+`warp` plays a similar role in your application:
+
+- components form the **threads of a dependency graph**
+- the runtime **weaves them together for a request**
+- cross-cutting concerns like transactions or tracing can be applied **through middleware**
+
+---
+
+## The problem
+
+In most Node.js applications, wiring dependencies eventually becomes messy.
+
+You end up with one of these situations:
+
+- **Manual wiring everywhere**
+```ts
+const repo = createRepo(prisma)
+const service = createService(repo)
+const usecase = createUseCase(service)
+  ```
+- **A container that hides everything**
+```ts
+container.resolve("CreateUserUseCase")
+```
+
+Manual wiring becomes repetitive.
+Containers often introduce hidden magic and runtime errors.
+
+At the same time modern applications need:
+
+- request scoped context
+- transactions
+- tracing and metrics
+- easy test overrides
+
+warp provides a middle ground.
+
+Dependencies stay explicit and typed, but wiring happens once and the runtime handles scoped execution.
+
+## Core idea
+Define a *component graph* once:
+```ts
+const service = component(serviceFactory, {
+  repo: component(repoFactory)
+})
+```
+Resolve it against the *current request context*:
+```ts
+const handler = resolve(service, { requestId })
+handler(params)
+```
+The graph is static.
+The context is supplied when executing.
+
+> Compose once, resolve per request.
+
+## Why warp?
+
+- explicit dependency graphs
+- typed context
+- request-scoped execution
+- middleware for cross-cutting concerns
+- easy testing with overrides
+- no container magic
+
+## Examples
+You can find more examples in the [examples](../examples) project
+
+## When to use it
+
+`warp` is useful if your application has:
+
+- repositories, services and use cases
+- request scoped context
+- transactions or tracing
+- complex dependency wiring
+- tests that need to replace dependencies
+
+## When not to use it
+
+If your application is small and simple manual wiring is enough, you probably don’t need `warp`.
+
+Or if you want to go all-in with [effect](https://effect.website/) anyway.
+
+## Status
+
+Early stage, evolving API.

package/dist/index.d.mts

@@ -37,6 +37,12 @@ type InferComponentOut<T> = InferComponentParams<T>[3];
 declare function brandComponent<T extends object, Ctx, RunOptions, Out>(obj: T): T & ComponentRef<Ctx, RunOptions, Out>;
 declare function isComponent(value: unknown): value is Component<unknown, unknown, unknown, unknown>;
 //#endregion
+//#region src/runtime/explain.d.ts
+type ExplainResult = {
+  name: string | undefined;
+  deps?: Record<string, ExplainResult>;
+};
+//#endregion
 //#region src/runtime/runtime.d.ts
 type SafeIntersect<A, B> = A extends undefined ? B : A & B;
 type OptionalArg<A> = A extends undefined ? [] : [A];
@@ -54,6 +60,10 @@ declare class Runtime<Ctx, ActualContext extends Ctx, ScopeContext, RunOptions,
   get classComponent(): <Deps, Ctor extends new (deps: Run<SafeIntersect<Requirements, ActualContext> & Deps, RunOptions>) => InstanceType<Ctor>>(ctor: Ctor, deps?: { [K in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps[K]> } | undefined, opts?: {
     name?: string | undefined;
   } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, InstanceType<Ctor>>;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, Out>, format: "native"): ExplainResult;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, Out>, format: "ascii"): string;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, Out>, format: "mermaid"): string;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, Out>): ExplainResult;
 }
 //#endregion
 //#region src/runtime/runtime-builder.d.ts

package/dist/index.mjs

@@ -99,6 +99,49 @@ function createResolver(mw) {
 	};
 }
 //#endregion
+//#region src/runtime/explain.ts
+const explain = (c) => {
+	const deps = {};
+	for (const [key, comp] of Object.entries(c.deps ?? {})) deps[key] = explain(comp);
+	return {
+		name: c.name,
+		deps
+	};
+};
+const toAsciiTree = (result, prefix = "", isLast = true) => {
+	const lines = [];
+	const connector = isLast ? "└── " : "├── ";
+	lines.push(prefix + connector + result.name);
+	const deps = Object.entries(result.deps ?? {});
+	const newPrefix = prefix + (isLast ? "    " : "│   ");
+	deps.forEach(([key, dep], index) => {
+		const isLastDep = index === deps.length - 1;
+		const connector = isLastDep ? "└── " : "├── ";
+		lines.push(`${newPrefix}${connector}[${key}]`);
+		const childLines = toAsciiTree(dep, newPrefix + (isLastDep ? "    " : "│   "), true).split("\n").slice(1);
+		lines.push(...childLines);
+	});
+	return lines.join("\n");
+};
+const toMermaid = (result, nodeId, isRoot = true) => {
+	const lines = [];
+	if (isRoot) {
+		lines.push("graph TD");
+		nodeId = result.name ?? "root";
+	}
+	const sanitizedId = nodeId.replace(/[^a-zA-Z0-9_]/g, "_");
+	if (isRoot) lines.push(`    ${sanitizedId}["${result.name}"]`);
+	Object.entries(result.deps ?? {}).forEach(([key, dep]) => {
+		const sanitizedDepId = (dep.name ? `${sanitizedId}_${dep.name}` : `${sanitizedId}_${key}`).replace(/[^a-zA-Z0-9_]/g, "_");
+		const displayName = dep.name ?? key;
+		lines.push(`    ${sanitizedDepId}["${displayName}"]`);
+		lines.push(`    ${sanitizedId} -->|${key}| ${sanitizedDepId}`);
+		const childLines = toMermaid(dep, sanitizedDepId, false).split("\n").slice(1);
+		lines.push(...childLines);
+	});
+	return lines.join("\n");
+};
+//#endregion
 //#region src/runtime/runtime.ts
 var Runtime = class Runtime {
 	resolveFn;
@@ -130,6 +173,14 @@ var Runtime = class Runtime {
 	get classComponent() {
 		return defineClassComponent();
 	}
+	explain(component, format = "native") {
+		const result = explain(component);
+		switch (format) {
+			case "ascii": return toAsciiTree(result);
+			case "mermaid": return toMermaid(result);
+			case "native": return result;
+		}
+	}
 };
 //#endregion
 //#region src/runtime/runtime-builder.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceteams/warp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Type-safe composition with execution scopes ",
   "type": "module",
   "files": [