@spaceteams/warp 0.1.0 → 0.2.0

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

@@ -1,41 +1,49 @@
-//#region src/middleware.d.ts
-type NoRunOptions = NonNullable<unknown>;
-type NoScopeContext = NonNullable<unknown>;
-type Middleware<AmbientContext, RunOptions = NoRunOptions, ScopeContext = NoScopeContext> = <T>(ctx: AmbientContext, options: Partial<RunOptions>, next: (ctx: AmbientContext & ScopeContext) => Promise<T> | T) => Promise<T> | T;
-//#endregion
 //#region src/run.d.ts
-type Run<AmbientContext, RunOptions, ScopeContext = NoScopeContext> = AmbientContext & {
-  run: <T>(options: RunOptions, inner: (app: Run<AmbientContext & Partial<ScopeContext>, RunOptions, ScopeContext>) => Promise<T> | T) => Promise<T> | T;
+type Run<AmbientContext, ScopeContext = unknown, RunOptions = unknown> = AmbientContext & {
+  run: <T>(options: RunOptions, inner: (app: Run<AmbientContext & ScopeContext, ScopeContext, RunOptions>) => Promise<T> | T) => Promise<T> | T;
 };
 //#endregion
 //#region src/component/index.d.ts
 type NoDeps = NonNullable<unknown>;
 declare const COMPONENT: unique symbol;
-type ComponentRef<Ctx, RunOptions, Out> = {
+type ComponentRef<Ctx, ScopeContext, RunOptions, Out> = {
   readonly [COMPONENT]: true;
   readonly __ctx?: Ctx;
+  readonly __scopeContext?: ScopeContext;
   readonly __runOptions?: RunOptions;
   readonly __out?: Out;
 };
-type ComponentFactory<Ctx, RunOptions, Deps, Out> = (ctx: Run<Ctx & Deps, RunOptions>) => Out;
-type ComponentInput<Ctx, RunOptions, Out> = ComponentRef<Ctx, RunOptions, Out> | Out;
-type Component<Ctx, RunOptions, Deps, Out> = ComponentRef<Ctx, RunOptions, Out> & {
-  factory: ComponentFactory<Ctx, RunOptions, Deps, Out>;
-  deps?: { [K in keyof Deps]: ComponentRef<Ctx, RunOptions, Deps[K]> };
+type ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out> = (ctx: Run<Ctx & Deps, ScopeContext, RunOptions>) => Out;
+type ComponentInput<Ctx, ScopeContext, RunOptions, Out> = ComponentRef<Ctx, ScopeContext, RunOptions, Out> | Out;
+type Component<Ctx, ScopeContext, RunOptions, Deps, Out> = ComponentRef<Ctx, ScopeContext, RunOptions, Out> & {
+  factory: ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out>;
+  deps?: { [K in keyof Deps]: ComponentRef<Ctx, ScopeContext, RunOptions, Deps[K]> };
   name?: string;
 };
-type ComponentDefinition<Ctx, RunOptions, Deps, Out> = {
-  factory: ComponentFactory<Ctx, RunOptions, Deps, Out>;
-  deps?: { [K in keyof Deps]: ComponentInput<Ctx, RunOptions, Deps[K]> };
+type ComponentDefinition<Ctx, ScopeContext, RunOptions, Deps, Out> = {
+  factory: ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out>;
+  deps?: { [K in keyof Deps]: ComponentInput<Ctx, ScopeContext, RunOptions, Deps[K]> };
   name?: string;
 };
-type InferComponentParams<T> = T extends Component<infer Ctx, infer RunOptions, infer Deps, infer Out> ? [Ctx, RunOptions, Deps, Out] : never;
+type InferComponentParams<T> = T extends Component<infer Ctx, infer ScopeContext, infer RunOptions, infer Deps, infer Out> ? [Ctx, ScopeContext, RunOptions, Deps, Out] : never;
 type InferComponentCtx<T> = InferComponentParams<T>[0];
-type InferComponentRunOptions<T> = InferComponentParams<T>[1];
-type InferComponentDeps<T> = InferComponentParams<T>[2];
-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>;
+type InferComponentScopeContext<T> = InferComponentParams<T>[1];
+type InferComponentRunOptions<T> = InferComponentParams<T>[2];
+type InferComponentDeps<T> = InferComponentParams<T>[3];
+type InferComponentOut<T> = InferComponentParams<T>[4];
+declare function brandComponent<T extends object, Ctx, ScopeContext, RunOptions, Out>(obj: T): T & ComponentRef<Ctx, ScopeContext, RunOptions, Out>;
+declare function isComponent(value: unknown): value is Component<unknown, unknown, unknown, unknown, unknown>;
+//#endregion
+//#region src/middleware.d.ts
+type NoRunOptions = NonNullable<unknown>;
+type NoScopeContext = NonNullable<unknown>;
+type Middleware<AmbientContext, RunOptions = NoRunOptions, ScopeContext = NoScopeContext> = <T>(ctx: AmbientContext, options: Partial<RunOptions>, next: (ctx: AmbientContext & ScopeContext) => Promise<T> | T) => Promise<T> | T;
+//#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;
@@ -47,20 +55,24 @@ declare class Runtime<Ctx, ActualContext extends Ctx, ScopeContext, RunOptions,
   constructor(middleware: Middleware<Ctx, RunOptions, ScopeContext>, ctx: ActualContext);
   provide<Extension>(ext: Extension): Runtime<Ctx, ActualContext & Extension, ScopeContext, RunOptions, Requirements>;
   require<Extension>(): Runtime<Ctx, ActualContext, ScopeContext, RunOptions, SafeIntersect<Requirements, Extension>>;
-  resolve: <Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, Out>, ...requirements: OptionalArg<Requirements>) => Out | Promise<Out>;
-  get component(): <Deps, F extends ComponentFactory<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, ReturnType<F>>>(factory: F, deps?: { [T in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps[T]> } | undefined, opts?: {
+  resolve: <Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, ...requirements: OptionalArg<Requirements>) => Out | Promise<Out>;
+  get component(): <Deps, F extends ComponentFactory<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>>(factory: F, deps?: { [T in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[T]> } | undefined, opts?: {
     name?: string | undefined;
-  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, ReturnType<F>>;
-  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?: {
+  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>;
+  get classComponent(): <Deps, Ctor extends new (deps: Run<SafeIntersect<Requirements, ActualContext> & Deps, ScopeContext, RunOptions>) => InstanceType<Ctor>>(ctor: Ctor, deps?: { [K in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[K]> } | undefined, opts?: {
     name?: string | undefined;
-  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, InstanceType<Ctor>>;
+  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, InstanceType<Ctor>>;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "native"): ExplainResult;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "ascii"): string;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "mermaid"): string;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>): ExplainResult;
 }
 //#endregion
 //#region src/runtime/runtime-builder.d.ts
-declare class RuntimeBuilder<AmbientContext, Options, ScopeContext = NoScopeContext> {
+declare class RuntimeBuilder<AmbientContext, ScopeContext = unknown, Options = unknown> {
   private readonly middlewares;
   constructor(middlewares?: Middleware<AmbientContext, Options, ScopeContext>[]);
-  use<A, H, S>(mw: Middleware<A, H, S>): RuntimeBuilder<AmbientContext & A, Options & H, ScopeContext & S>;
+  use<A, S, H>(mw: Middleware<A, H, S>): RuntimeBuilder<AmbientContext & A, ScopeContext & S, Options & H>;
   provide<ActualCtx extends AmbientContext>(ctx: ActualCtx): Runtime<AmbientContext, ActualCtx, ScopeContext, Options, undefined>;
   private buildMiddleware;
 }
@@ -68,4 +80,4 @@ declare class RuntimeBuilder<AmbientContext, Options, ScopeContext = NoScopeCont
 //#region src/runtime/index.d.ts
 declare function buildRuntime(): RuntimeBuilder<Record<string, unknown>, unknown>;
 //#endregion
-export { Component, ComponentDefinition, ComponentFactory, ComponentInput, ComponentRef, InferComponentCtx, InferComponentDeps, InferComponentOut, InferComponentParams, InferComponentRunOptions, Middleware, NoDeps, NoRunOptions, NoScopeContext, Run, brandComponent, buildRuntime, isComponent };
+export { Component, ComponentDefinition, ComponentFactory, ComponentInput, ComponentRef, InferComponentCtx, InferComponentDeps, InferComponentOut, InferComponentParams, InferComponentRunOptions, InferComponentScopeContext, Middleware, NoDeps, NoRunOptions, NoScopeContext, Run, brandComponent, buildRuntime, isComponent };

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.2.0",
   "description": "Type-safe composition with execution scopes ",
   "type": "module",
   "files": [