@supacloud/app 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @supacloud/app
+
+Angular-style application metadata for SupaCloud applications: modules, DI
+tokens, providers, scopes, controllers and commands.
+
+This package is **metadata only**. Decorators attach metadata to classes; the
+SupaCloud compiler (`@supacloud/compiler`) reads that metadata from source,
+validates the dependency graph and generates plain static factories — there is
+no runtime reflection and no `reflect-metadata` dependency.
+
+```ts
+import {
+  Command,
+  Controller,
+  Inject,
+  Injectable,
+  InjectionToken,
+  Module,
+  Post,
+} from "@supacloud/app";
+
+export const CASE_REPOSITORY = new InjectionToken<CaseRepository>("case.repository");
+
+@Injectable()
+export class CaseService {
+  constructor(
+    @Inject(CASE_REPOSITORY) private readonly repository: CaseRepository,
+  ) {}
+}
+
+@Command({ name: "case.accept", permission: "case.accept", transaction: "required" })
+export class AcceptCaseCommand {
+  constructor(private readonly cases: CaseService) {}
+}
+
+@Controller("/cases")
+export class CaseController {
+  constructor(private readonly acceptCase: AcceptCaseCommand) {}
+
+  @Post("/:caseId/accept", { body: CaseAcceptInput })
+  accept() {
+    return this.acceptCase.execute();
+  }
+}
+
+@Module({
+  name: "case",
+  providers: [
+    CaseService,
+    { provide: CASE_REPOSITORY, useClass: DrizzleCaseRepository },
+    AcceptCaseCommand,
+  ],
+  controllers: [CaseController],
+  exports: [CaseService],
+})
+export class CaseModule {}
+```
+
+## Scopes
+
+| Scope | Lifetime | May depend on |
+|---|---|---|
+| `application` (default) | whole function instance | `application` only |
+| `request` | one HTTP request | `application`, `request` |
+| `job` | one background task | `application`, `job` |
+
+The compiler rejects scope violations (e.g. an `application` provider
+depending on a `request` provider) at build time.
+
+## Non-decorator usage
+
+`defineModule(options)` produces the same metadata as `@Module(options)` and
+can be used where decorators are not enabled.

package/dist/context.d.ts

@@ -0,0 +1,14 @@
+import { InjectionToken } from "./token";
+/**
+ * Built-in token resolved from the request-context argument of a compiled
+ * `createRequestScope(services, ctx)` factory. Request-scoped providers that
+ * declare this token as a dependency receive the raw request context.
+ */
+export declare const REQUEST_CONTEXT: InjectionToken<unknown>;
+/**
+ * Built-in token resolved from the job-context argument of a compiled
+ * `createJobScope(services, ctx)` factory. Job-scoped providers that declare
+ * this token as a dependency receive the raw job context (task id, lease,
+ * cancellation signal, ...).
+ */
+export declare const JOB_CONTEXT: InjectionToken<unknown>;

package/dist/decorators.d.ts

@@ -0,0 +1,94 @@
+import type { Provider, Token, Type } from "./provider";
+import type { Scope } from "./scope";
+/**
+ * Decorator metadata keys. Metadata is attached as static properties on the
+ * decorated class so the SupaCloud compiler can read it from the AST *and*
+ * tooling can read it at runtime without reflect-metadata.
+ */
+export declare const INJECTABLE_METADATA = "supacloud:injectable";
+export declare const MODULE_METADATA = "supacloud:module";
+export declare const COMMAND_METADATA = "supacloud:command";
+export declare const QUERY_METADATA = "supacloud:query";
+export declare const CONTROLLER_METADATA = "supacloud:controller";
+export declare const ROUTES_METADATA = "supacloud:routes";
+export declare const INJECT_PARAMS_METADATA = "supacloud:inject-params";
+export interface InjectableOptions {
+    scope?: Scope;
+    /** Explicit constructor dependency tokens, in parameter order. */
+    deps?: Token[];
+}
+export interface InjectableMeta {
+    scope: Scope;
+    deps: Token[];
+}
+export interface ModuleOptions {
+    name: string;
+    imports?: Array<Type<unknown>>;
+    providers?: Provider[];
+    controllers?: Array<Type<unknown>>;
+    commands?: Array<Type<unknown>>;
+    queries?: Array<Type<unknown>>;
+    exports?: Token[];
+}
+export interface ModuleMeta extends Required<Omit<ModuleOptions, "exports">> {
+    exports: Token[];
+}
+export interface CommandOptions {
+    name: string;
+    /** Permission identifier required to execute (e.g. "case.create"). */
+    permission?: string;
+    /** Transaction requirement for the underlying write, e.g. "required". */
+    transaction?: string;
+    /** Audit event name recorded on success, e.g. "case.created". */
+    audit?: string;
+    /** Idempotency strategy, e.g. "required". */
+    idempotency?: string;
+}
+export type CommandMeta = CommandOptions;
+export interface QueryOptions {
+    name: string;
+}
+export type QueryMeta = QueryOptions;
+export interface ControllerMeta {
+    path: string;
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface RouteOptions {
+    /** TypeBox schema (or compatible) for the request body. */
+    body?: unknown;
+    /** TypeBox schema for path params. */
+    params?: unknown;
+    /** TypeBox schema for query string. */
+    query?: unknown;
+    /** TypeBox schema for the response. */
+    response?: unknown;
+}
+export interface RouteDefinition extends RouteOptions {
+    method: HttpMethod;
+    path: string;
+    /** Controller method name. */
+    handler: string;
+}
+export declare function Injectable(options?: InjectableOptions): ClassDecorator;
+export declare function getInjectableMeta(target: object): InjectableMeta | undefined;
+/**
+ * Parameter decorator marking a constructor parameter's injection token.
+ * Only meaningful together with the SupaCloud compiler; no runtime reflection
+ * is performed.
+ */
+export declare function Inject(token: Token): ParameterDecorator;
+export declare function getInjectParams(target: object): Record<number, Token>;
+export declare function Module(options: ModuleOptions): ClassDecorator;
+export declare function getModuleMeta(target: object): ModuleMeta | undefined;
+export declare function Command(options: CommandOptions): ClassDecorator;
+export declare function getCommandMeta(target: object): CommandMeta | undefined;
+export declare function Query(options: QueryOptions): ClassDecorator;
+export declare function getQueryMeta(target: object): QueryMeta | undefined;
+export declare function Controller(path: string): ClassDecorator;
+export declare function getControllerMeta(target: object): ControllerMeta | undefined;
+export declare const Get: (path: string, options?: RouteOptions) => MethodDecorator;
+export declare const Post: (path: string, options?: RouteOptions) => MethodDecorator;
+export declare const Put: (path: string, options?: RouteOptions) => MethodDecorator;
+export declare const Patch: (path: string, options?: RouteOptions) => MethodDecorator;
+export declare const Delete: (path: string, options?: RouteOptions) => MethodDecorator;
+export declare function getRoutes(target: object): RouteDefinition[];

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { SCOPES, DEFAULT_SCOPE, SCOPE_LIFETIME_RANK, isScopeViolation } from "./scope";
+export type { Scope } from "./scope";
+export { InjectionToken } from "./token";
+export type { InjectionTokenOptions } from "./token";
+export { isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider, } from "./provider";
+export type { ClassProvider, ExistingProvider, FactoryProvider, Provider, Token, Type, ValueProvider, } from "./provider";
+export { Command, Controller, Delete, Get, Inject, Injectable, Module, Patch, Post, Put, Query, getCommandMeta, getControllerMeta, getInjectParams, getInjectableMeta, getModuleMeta, getQueryMeta, getRoutes, COMMAND_METADATA, CONTROLLER_METADATA, INJECTABLE_METADATA, INJECT_PARAMS_METADATA, MODULE_METADATA, QUERY_METADATA, ROUTES_METADATA, } from "./decorators";
+export type { CommandMeta, CommandOptions, ControllerMeta, HttpMethod, InjectableMeta, InjectableOptions, ModuleMeta, ModuleOptions, QueryMeta, QueryOptions, RouteDefinition, RouteOptions, } from "./decorators";
+export { defineModule } from "./module";
+export { JOB_CONTEXT, REQUEST_CONTEXT } from "./context";

package/dist/index.js

@@ -0,0 +1,205 @@
+// src/scope.ts
+var SCOPES = ["application", "request", "job"];
+var DEFAULT_SCOPE = "application";
+var SCOPE_LIFETIME_RANK = {
+  application: 0,
+  request: 1,
+  job: 1
+};
+function isScopeViolation(from, to) {
+  return SCOPE_LIFETIME_RANK[to] > SCOPE_LIFETIME_RANK[from];
+}
+// src/token.ts
+class InjectionToken {
+  name;
+  factory;
+  scope;
+  constructor(name, options = {}) {
+    this.name = name;
+    this.factory = options.factory;
+    this.scope = options.scope;
+  }
+  toString() {
+    return `InjectionToken ${this.name}`;
+  }
+}
+// src/provider.ts
+function isClassProvider(provider) {
+  return typeof provider === "object" && provider !== null && "useClass" in provider;
+}
+function isValueProvider(provider) {
+  return typeof provider === "object" && provider !== null && "useValue" in provider;
+}
+function isFactoryProvider(provider) {
+  return typeof provider === "object" && provider !== null && "useFactory" in provider;
+}
+function isExistingProvider(provider) {
+  return typeof provider === "object" && provider !== null && "useExisting" in provider;
+}
+// src/decorators.ts
+var INJECTABLE_METADATA = "supacloud:injectable";
+var MODULE_METADATA = "supacloud:module";
+var COMMAND_METADATA = "supacloud:command";
+var QUERY_METADATA = "supacloud:query";
+var CONTROLLER_METADATA = "supacloud:controller";
+var ROUTES_METADATA = "supacloud:routes";
+var INJECT_PARAMS_METADATA = "supacloud:inject-params";
+function defineMetadata(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    configurable: true,
+    writable: true
+  });
+}
+function readOwnOrInherited(target, key) {
+  return target[key];
+}
+function Injectable(options = {}) {
+  return (target) => {
+    const meta = {
+      scope: options.scope ?? DEFAULT_SCOPE,
+      deps: options.deps ?? []
+    };
+    defineMetadata(target, INJECTABLE_METADATA, meta);
+  };
+}
+function getInjectableMeta(target) {
+  return readOwnOrInherited(target, INJECTABLE_METADATA);
+}
+function Inject(token) {
+  return (target, propertyKey, parameterIndex) => {
+    if (propertyKey !== undefined) {
+      throw new Error("@Inject() is only supported on constructor parameters");
+    }
+    const cls = target;
+    const meta = {
+      ...readOwnOrInherited(cls, INJECT_PARAMS_METADATA)
+    };
+    meta[parameterIndex] = token;
+    defineMetadata(cls, INJECT_PARAMS_METADATA, meta);
+  };
+}
+function getInjectParams(target) {
+  return readOwnOrInherited(target, INJECT_PARAMS_METADATA) ?? {};
+}
+function Module(options) {
+  return (target) => {
+    const meta = {
+      name: options.name,
+      imports: options.imports ?? [],
+      providers: options.providers ?? [],
+      controllers: options.controllers ?? [],
+      commands: options.commands ?? [],
+      queries: options.queries ?? [],
+      exports: options.exports ?? []
+    };
+    defineMetadata(target, MODULE_METADATA, meta);
+  };
+}
+function getModuleMeta(target) {
+  return readOwnOrInherited(target, MODULE_METADATA);
+}
+function Command(options) {
+  return (target) => {
+    defineMetadata(target, COMMAND_METADATA, { ...options });
+  };
+}
+function getCommandMeta(target) {
+  return readOwnOrInherited(target, COMMAND_METADATA);
+}
+function Query(options) {
+  return (target) => {
+    defineMetadata(target, QUERY_METADATA, { ...options });
+  };
+}
+function getQueryMeta(target) {
+  return readOwnOrInherited(target, QUERY_METADATA);
+}
+function Controller(path) {
+  return (target) => {
+    defineMetadata(target, CONTROLLER_METADATA, { path });
+  };
+}
+function getControllerMeta(target) {
+  return readOwnOrInherited(target, CONTROLLER_METADATA);
+}
+function createRouteDecorator(method) {
+  return (path, options = {}) => (target, propertyKey) => {
+    const cls = target.constructor;
+    const routes = [
+      ...readOwnOrInherited(cls, ROUTES_METADATA) ?? []
+    ];
+    routes.push({
+      method,
+      path,
+      handler: String(propertyKey),
+      ...options
+    });
+    defineMetadata(cls, ROUTES_METADATA, routes);
+  };
+}
+var Get = createRouteDecorator("GET");
+var Post = createRouteDecorator("POST");
+var Put = createRouteDecorator("PUT");
+var Patch = createRouteDecorator("PATCH");
+var Delete = createRouteDecorator("DELETE");
+function getRoutes(target) {
+  return readOwnOrInherited(target, ROUTES_METADATA) ?? [];
+}
+// src/module.ts
+function defineModule(options) {
+  class DefinedModule {
+  }
+  Object.defineProperty(DefinedModule, "name", {
+    value: options.name,
+    configurable: true
+  });
+  Module(options)(DefinedModule);
+  return DefinedModule;
+}
+// src/context.ts
+var REQUEST_CONTEXT = new InjectionToken("supacloud.request-context", {
+  scope: "request"
+});
+var JOB_CONTEXT = new InjectionToken("supacloud.job-context", {
+  scope: "job"
+});
+export {
+  COMMAND_METADATA,
+  CONTROLLER_METADATA,
+  Command,
+  Controller,
+  DEFAULT_SCOPE,
+  Delete,
+  Get,
+  INJECTABLE_METADATA,
+  INJECT_PARAMS_METADATA,
+  Inject,
+  Injectable,
+  InjectionToken,
+  JOB_CONTEXT,
+  MODULE_METADATA,
+  Module,
+  Patch,
+  Post,
+  Put,
+  QUERY_METADATA,
+  Query,
+  REQUEST_CONTEXT,
+  ROUTES_METADATA,
+  SCOPES,
+  SCOPE_LIFETIME_RANK,
+  defineModule,
+  getCommandMeta,
+  getControllerMeta,
+  getInjectParams,
+  getInjectableMeta,
+  getModuleMeta,
+  getQueryMeta,
+  getRoutes,
+  isClassProvider,
+  isExistingProvider,
+  isFactoryProvider,
+  isScopeViolation,
+  isValueProvider
+};

package/dist/module.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleOptions } from "./decorators";
+import type { Type } from "./provider";
+/**
+ * Functional equivalent of the `@Module()` decorator for codebases that do
+ * not enable `experimentalDecorators`. Returns a class carrying the same
+ * module metadata, so it can be used interchangeably in `imports` arrays.
+ */
+export declare function defineModule(options: ModuleOptions): Type<unknown>;

package/dist/provider.d.ts

@@ -0,0 +1,38 @@
+import type { InjectionToken } from "./token";
+import type { Scope } from "./scope";
+/** A class usable as a DI token / provider implementation. */
+export interface Type<T> {
+    new (...args: any[]): T;
+}
+/** Anything that can identify a provider: an InjectionToken or a class. */
+export type Token<T = any> = InjectionToken<T> | Type<T>;
+interface BaseProvider {
+    /** Overrides the scope derived from @Injectable / token defaults. */
+    scope?: Scope;
+}
+export interface ClassProvider<T = any> extends BaseProvider {
+    provide: Token<T>;
+    useClass: Type<T>;
+    /** Explicit dependency tokens, positional (constructor order). */
+    deps?: Token[];
+}
+export interface ValueProvider<T = any> extends BaseProvider {
+    provide: Token<T>;
+    useValue: T;
+}
+export interface FactoryProvider<T = any> extends BaseProvider {
+    provide: Token<T>;
+    useFactory: (...deps: any[]) => T;
+    deps?: Token[];
+}
+export interface ExistingProvider<T = any> extends BaseProvider {
+    provide: Token<T>;
+    useExisting: Token<T>;
+}
+/** Class shorthand registers the class as its own token. */
+export type Provider<T = any> = Type<T> | ClassProvider<T> | ValueProvider<T> | FactoryProvider<T> | ExistingProvider<T>;
+export declare function isClassProvider<T>(provider: Provider<T>): provider is ClassProvider<T>;
+export declare function isValueProvider<T>(provider: Provider<T>): provider is ValueProvider<T>;
+export declare function isFactoryProvider<T>(provider: Provider<T>): provider is FactoryProvider<T>;
+export declare function isExistingProvider<T>(provider: Provider<T>): provider is ExistingProvider<T>;
+export {};

package/dist/scope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Provider lifetime scopes.
+ *
+ * `application` providers live for the whole function instance and must never
+ * depend on shorter-lived `request` / `job` providers. `request` providers are
+ * created per HTTP request, `job` providers per background task execution.
+ */
+export declare const SCOPES: readonly ["application", "request", "job"];
+export type Scope = (typeof SCOPES)[number];
+export declare const DEFAULT_SCOPE: Scope;
+/**
+ * Lifetime rank: longer-lived scopes have a lower rank. A provider may only
+ * depend on providers of the same or a longer-lived (lower rank) scope.
+ */
+export declare const SCOPE_LIFETIME_RANK: Record<Scope, number>;
+export declare function isScopeViolation(from: Scope, to: Scope): boolean;

package/dist/token.d.ts

@@ -0,0 +1,18 @@
+import type { Scope } from "./scope";
+export interface InjectionTokenOptions<T> {
+    /** Optional default factory used when no explicit provider is registered. */
+    factory?: () => T;
+    /** Default scope when the token itself is used as a provider. */
+    scope?: Scope;
+}
+/**
+ * Lightweight injection token, modeled after Angular's tree-shakable tokens.
+ * Used as a DI key for interfaces and values that are not classes.
+ */
+export declare class InjectionToken<T> {
+    readonly name: string;
+    readonly factory?: () => T;
+    readonly scope?: Scope;
+    constructor(name: string, options?: InjectionTokenOptions<T>);
+    toString(): string;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@supacloud/app",
+  "version": "0.1.0",
+  "description": "Angular-style application metadata for SupaCloud: modules, DI tokens, providers, scopes, controllers and commands",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts --outdir dist --target node",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit"
+  },
+  "keywords": [
+    "supacloud",
+    "di",
+    "dependency-injection",
+    "module",
+    "elysia"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeunion/supacloud.git",
+    "directory": "packages/app"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  }
+}