@spaceteams/warp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spaceteams
+
+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/dist/index.d.mts

@@ -0,0 +1,71 @@
+//#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;
+};
+//#endregion
+//#region src/component/index.d.ts
+type NoDeps = NonNullable<unknown>;
+declare const COMPONENT: unique symbol;
+type ComponentRef<Ctx, RunOptions, Out> = {
+  readonly [COMPONENT]: true;
+  readonly __ctx?: Ctx;
+  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]> };
+  name?: string;
+};
+type ComponentDefinition<Ctx, RunOptions, Deps, Out> = {
+  factory: ComponentFactory<Ctx, RunOptions, Deps, Out>;
+  deps?: { [K in keyof Deps]: ComponentInput<Ctx, 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 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>;
+//#endregion
+//#region src/runtime/runtime.d.ts
+type SafeIntersect<A, B> = A extends undefined ? B : A & B;
+type OptionalArg<A> = A extends undefined ? [] : [A];
+declare class Runtime<Ctx, ActualContext extends Ctx, ScopeContext, RunOptions, Requirements = undefined> {
+  private readonly middleware;
+  private readonly ctx;
+  private readonly resolveFn;
+  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?: {
+    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?: {
+    name?: string | undefined;
+  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, RunOptions, Deps, InstanceType<Ctor>>;
+}
+//#endregion
+//#region src/runtime/runtime-builder.d.ts
+declare class RuntimeBuilder<AmbientContext, Options, ScopeContext = NoScopeContext> {
+  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>;
+  provide<ActualCtx extends AmbientContext>(ctx: ActualCtx): Runtime<AmbientContext, ActualCtx, ScopeContext, Options, undefined>;
+  private buildMiddleware;
+}
+//#endregion
+//#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 };

package/dist/index.mjs

@@ -0,0 +1,168 @@
+//#region src/component/index.ts
+const COMPONENT = Symbol("component");
+function brandComponent(obj) {
+	Object.defineProperty(obj, COMPONENT, {
+		value: true,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	return obj;
+}
+function isComponent(value) {
+	return typeof value === "object" && value !== null && value[COMPONENT] === true;
+}
+//#endregion
+//#region src/component/class-component.ts
+function defineClassComponent() {
+	return (ctor, deps, opts) => {
+		const factory = (ctx) => {
+			return new ctor(ctx);
+		};
+		return brandComponent({
+			factory,
+			deps,
+			name: opts?.name ?? ctor.name
+		});
+	};
+}
+//#endregion
+//#region src/component/functional-component.ts
+function defineFunctionalComponent() {
+	return (factory, deps, opts) => {
+		return brandComponent({
+			factory,
+			deps,
+			name: opts?.name
+		});
+	};
+}
+//#endregion
+//#region src/runtime/create-resolver.ts
+function createResolver(mw) {
+	return (root, ctx) => {
+		const stack = [];
+		const checkCyclicDependency = (depPath) => {
+			const depName = depPath.split(".").at(-1);
+			if (!depName) return;
+			for (const stackPath of stack) if (stackPath.split(".").includes(depName)) throw new Error(`Cyclic dependency: ${[...stack, depPath].join(" -> ")}`);
+		};
+		const withStackTracking = (depPath, fn) => {
+			stack.push(depPath);
+			try {
+				return fn();
+			} finally {
+				stack.pop();
+			}
+		};
+		const defineDependencyProperty = (target, depName, depPath, depComp, scopeCtx, cache) => {
+			Object.defineProperty(target, depName, {
+				enumerable: true,
+				configurable: false,
+				get() {
+					if (cache.has(depName)) return cache.get(depName);
+					checkCyclicDependency(depPath);
+					const out = withStackTracking(depPath, () => bindInScope(depComp, scopeCtx, depPath));
+					cache.set(depName, out);
+					return out;
+				}
+			});
+		};
+		const attachDependencies = (runCtx, deps, scopeCtx, pathPrefix, cache) => {
+			for (const [depName, depComp] of Object.entries(deps)) defineDependencyProperty(runCtx, depName, pathPrefix ? `${pathPrefix}.${depName}` : depName, depComp, scopeCtx, cache);
+		};
+		const createBaseRunContext = (scopeCtx) => {
+			return {
+				...scopeCtx,
+				run: (nestedOptions, nestedInner) => runWithContext(scopeCtx, nestedOptions, nestedInner)
+			};
+		};
+		const bindInScope = (comp, scopeCtx, path) => {
+			const localDepCache = /* @__PURE__ */ new Map();
+			const runCtx = createBaseRunContext(scopeCtx);
+			if (!isComponent(comp)) return comp;
+			attachDependencies(runCtx, comp.deps ?? {}, scopeCtx, path, localDepCache);
+			return comp.factory(runCtx);
+		};
+		const makeRootRunContext = (scopeCtx) => {
+			const rootCache = /* @__PURE__ */ new Map();
+			const runCtx = createBaseRunContext(scopeCtx);
+			attachDependencies(runCtx, root.deps ?? {}, scopeCtx, "", rootCache);
+			return runCtx;
+		};
+		const runWithContext = async (currentCtx, options, inner) => {
+			return await mw(currentCtx, options, (scopedCtx) => {
+				return inner(makeRootRunContext(scopedCtx));
+			});
+		};
+		return root.factory(makeRootRunContext(ctx));
+	};
+}
+//#endregion
+//#region src/runtime/runtime.ts
+var Runtime = class Runtime {
+	resolveFn;
+	constructor(middleware, ctx) {
+		this.middleware = middleware;
+		this.ctx = ctx;
+		this.resolveFn = createResolver(middleware);
+	}
+	provide(ext) {
+		return new Runtime(this.middleware, {
+			...this.ctx,
+			...ext
+		});
+	}
+	require() {
+		return new Runtime(this.middleware, this.ctx);
+	}
+	resolve = (component, ...requirements) => {
+		const req = requirements[0];
+		const ctx = req ? {
+			...this.ctx,
+			...req
+		} : { ...this.ctx };
+		return this.resolveFn(component, ctx);
+	};
+	get component() {
+		return defineFunctionalComponent();
+	}
+	get classComponent() {
+		return defineClassComponent();
+	}
+};
+//#endregion
+//#region src/runtime/runtime-builder.ts
+var RuntimeBuilder = class RuntimeBuilder {
+	middlewares;
+	constructor(middlewares = []) {
+		this.middlewares = middlewares;
+	}
+	use(mw) {
+		return new RuntimeBuilder([...this.middlewares, mw]);
+	}
+	provide(ctx) {
+		return new Runtime(this.buildMiddleware(), ctx);
+	}
+	buildMiddleware() {
+		const middlewares = this.middlewares;
+		return function composed(ctx, options, next) {
+			let index = -1;
+			const dispatch = (i, currentCtx) => {
+				if (i <= index) throw new Error("next() called multiple times");
+				index = i;
+				const mw = middlewares[i];
+				if (!mw) return next(currentCtx);
+				return mw(currentCtx, options, (nextCtx) => dispatch(i + 1, nextCtx));
+			};
+			return dispatch(0, ctx);
+		};
+	}
+};
+//#endregion
+//#region src/runtime/index.ts
+function buildRuntime() {
+	return new RuntimeBuilder();
+}
+//#endregion
+export { brandComponent, buildRuntime, isComponent };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@spaceteams/warp",
+  "version": "0.1.0",
+  "description": "Type-safe composition with execution scopes ",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spaceteams/warp.git",
+    "directory": "warp"
+  },
+  "keywords": [
+    "dependency-injection",
+    "composition",
+    "context",
+    "runtime",
+    "middleware",
+    "typescript",
+    "request-scoped",
+    "dependency-graph"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}