← Back to all projects
🔗

Open source · vishwajit-vm Contracts v0 built

Strutvane Core & Contracts

The kernel, and the shared types every package speaks

The foundation of Strutvane. @strutvane/contracts holds the shared types and wire protocols — Actor, Permission, TenantContext, QueryFilter, ListQuery, Problem, ResourceManifest, AuditEvent and more — with zero runtime dependencies; it is the only thing the product packages share, and its v0 is built and fully tested. @strutvane/core is the kernel every app boots on: lifecycle, a typed service container, providers, validated config and per-request context.

0 runtime dependencies100% coveragetype-level tests

Built for: Package and plugin authors, and advanced app developers.

Packages on npm

↓ Scroll to explore the problem, architecture and stack

😩

The problem

Plugin ecosystems usually couple packages directly, so one upgrade cascades into all the others — and loosely typed shared objects let mistakes (like comparing a filter value to null) slip into production.

💡

Why it matters

A small, strictly versioned contracts package lets framework, auth and UI evolve independently, and its types are designed so misuse fails to compile.

What you can do with it

01Share Actor, Permission and TenantContext types across every package.
02Describe filters with QueryFilter, including normative NULL rules, and lists with ListQuery / ListResult.
03Decide access through a deny-by-default PermissionProvider.
04Return errors as RFC 9457 Problem objects with code, traceId and field issues.
05Boot an app through core: register → boot → serve, with providers, Zod-validated env and request context via AsyncLocalStorage.

How it’s built

A simplified view of the architecture — follow the dots as a request moves down the layers.

Packages
framework
auth
ui
Kernel
corecontainer · providers · context
Contracts
@strutvane/contractstypes only · 0 deps
Wire
ListQuery · Problem · manifestover HTTP to the UI

A request, step by step

  1. createApp starts the kernel; each package’s provider registers its services, then all providers boot.
  2. Packages import contract types only — never each other.
  3. The container resolves the real implementation, for example the PermissionProvider supplied by auth.
  4. Per-request context (request id, trace id, actor, tenant, locale) flows implicitly through AsyncLocalStorage.
  5. The same contract shapes travel over HTTP, so the UI understands every API the same way.

Tech stack

Language
TypeScript
Testing
Vitesttype tests
Tooling
tsdownBiomeChangesets
Standards
RFC 9457Standard Schema

What I built

  • Built @strutvane/contracts v0: 14 source files, runtime and type-level tests (Vitest type tests), 100% coverage and a publint-clean build via tsdown.
  • Its CI runs Biome, TypeScript, Vitest with coverage, then the build — on every change.
  • Designed types that make misuse a compile error, such as comparing against null or using a permission without a dot.
  • Kept it validator-agnostic through Standard Schema, with no dependency, under strict semver with at most one major version a year.
  • Specified @strutvane/core: a decorator-free typed token container, defineProvider, frozen validated env, typed hooks and events, and a compiled registry instead of runtime file scanning for fast cold starts.

Hard problems & how I solved them

❓ Make misuse impossible, not just documented.

✅ Type-level tests prove that wrong usages fail to compile.

❓ Dependency injection without decorators or reflection.

✅ A typed token container: services are registered and resolved by typed tokens, fully checked by TypeScript.