@taujs/server 0.4.1 → 0.4.3

package/dist/{Config-LCDjtT9m.d.ts → Config-CEhfq8Mm.d.ts}

@@ -23,16 +23,17 @@ interface Logs extends BaseLogger {
     isDebugEnabled(category: DebugCategory): boolean;
 }
 
-type Schema<T> = (input: unknown) => T;
-type LooseSpec = Readonly<Record<string, ServiceMethod<any, Record<string, unknown>> | {
-    handler: ServiceMethod<any, Record<string, unknown>>;
-    params?: Schema<any>;
-    result?: Schema<any>;
-    parsers?: {
-        params?: Schema<any>;
-        result?: Schema<any>;
-    };
-}>>;
+type RegistryCaller<R extends ServiceRegistry = ServiceRegistry> = (serviceName: keyof R & string, methodName: string, args?: JsonObject) => Promise<JsonObject>;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+type JsonObject = {
+    [k: string]: JsonValue;
+};
+type NarrowSchema<T> = {
+    parse: (u: unknown) => T;
+} | ((u: unknown) => T);
 type ServiceContext = {
     signal?: AbortSignal;
     deadlineMs?: number;
@@ -42,20 +43,26 @@ type ServiceContext = {
         id: string;
         roles: string[];
     } | null;
+    call?: (service: string, method: string, args?: JsonObject) => Promise<JsonObject>;
 };
-type ServiceMethod<P, R extends Record<string, unknown>> = (params: P, ctx: ServiceContext) => Promise<R>;
-type ServiceMethodDescriptor<P, R extends Record<string, unknown>> = {
-    handler: ServiceMethod<P, R>;
-    parsers?: {
-        params?: Schema<P>;
-        result?: Schema<R>;
-    };
+declare function withDeadline(signal: AbortSignal | undefined, ms?: number): AbortSignal | undefined;
+type ServiceMethod<P, R extends JsonObject = JsonObject> = (params: P, ctx: ServiceContext) => Promise<R>;
+type ServiceDefinition = Readonly<Record<string, ServiceMethod<any, JsonObject>>>;
+type ServiceRegistry = Readonly<Record<string, ServiceDefinition>>;
+type ServiceDescriptor = {
+    serviceName: string;
+    serviceMethod: string;
+    args?: JsonObject;
 };
-type ServiceRegistry = Readonly<Record<string, Readonly<Record<string, ServiceMethodDescriptor<any, Record<string, unknown>>>>>>;
-declare const defineService: <T extends LooseSpec>(spec: T) => { [K in keyof T]: T[K] extends ServiceMethod<infer P, infer R> ? ServiceMethodDescriptor<P, R> : T[K] extends {
+declare function defineService<T extends Record<string, ServiceMethod<any, JsonObject> | {
+    handler: ServiceMethod<any, JsonObject>;
+    params?: NarrowSchema<any>;
+    result?: NarrowSchema<any>;
+}>>(spec: T): { [K in keyof T]: T[K] extends ServiceMethod<infer P, infer R> ? ServiceMethod<P, R> : T[K] extends {
     handler: ServiceMethod<infer P, infer R_1>;
-} ? ServiceMethodDescriptor<P, R_1> : never; };
+} ? ServiceMethod<P, R_1> : never; };
 declare const defineServiceRegistry: <R extends ServiceRegistry>(registry: R) => R;
+declare function callServiceMethod(registry: ServiceRegistry, serviceName: string, methodName: string, params: JsonObject | undefined, ctx: ServiceContext): Promise<JsonObject>;
 
 type RequestContext<L extends Logs = Logs> = {
     traceId: string;
@@ -73,6 +80,7 @@ type RouteCSPConfig = {
         req: FastifyRequest;
     }) => CSPDirectives);
     generateCSP?: (directives: CSPDirectives, nonce: string, req: FastifyRequest) => string;
+    reportOnly?: boolean;
 };
 type BaseMiddleware = {
     auth?: {
@@ -82,13 +90,12 @@ type BaseMiddleware = {
     };
     csp?: RouteCSPConfig | false;
 };
-type ServiceCall = {
-    serviceName: string;
-    serviceMethod: string;
-    args?: Record<string, unknown>;
+type DataResult = Record<string, unknown> | ServiceDescriptor;
+type RequestServiceContext<L extends Logs = Logs> = RequestContext<L> & {
+    call: RegistryCaller<ServiceRegistry>;
+    headers?: Record<string, string>;
 };
-type DataResult = Record<string, unknown> | ServiceCall;
-type DataHandler<Params extends PathToRegExpParams, L extends Logs = Logs> = (params: Params, ctx: RequestContext<L> & {
+type DataHandler<Params extends PathToRegExpParams, L extends Logs = Logs> = (params: Params, ctx: RequestServiceContext<L> & {
     [key: string]: unknown;
 }) => Promise<DataResult>;
 type PathToRegExpParams = Partial<Record<string, string | string[]>>;
@@ -129,6 +136,35 @@ type CSPViolationReport = {
     disposition?: 'enforce' | 'report';
 };
 
+type ErrorKind = 'infra' | 'upstream' | 'domain' | 'validation' | 'auth' | 'canceled' | 'timeout';
+declare class AppError extends Error {
+    readonly kind: ErrorKind;
+    readonly httpStatus: number;
+    readonly details?: unknown;
+    readonly safeMessage: string;
+    readonly code?: string;
+    constructor(message: string, kind: ErrorKind, options?: {
+        httpStatus?: number;
+        details?: unknown;
+        cause?: unknown;
+        safeMessage?: string;
+        code?: string;
+    });
+    private getSafeMessage;
+    private serialiseValue;
+    toJSON(): any;
+    static notFound(message: string, details?: unknown, code?: string): AppError;
+    static forbidden(message: string, details?: unknown, code?: string): AppError;
+    static badRequest(message: string, details?: unknown, code?: string): AppError;
+    static unprocessable(message: string, details?: unknown, code?: string): AppError;
+    static timeout(message: string, details?: unknown, code?: string): AppError;
+    static canceled(message: string, details?: unknown, code?: string): AppError;
+    static internal(message: string, cause?: unknown, details?: unknown, code?: string): AppError;
+    static upstream(message: string, cause?: unknown, details?: unknown, code?: string): AppError;
+    static serviceUnavailable(message: string, cause?: unknown, details?: unknown, code?: string): AppError;
+    static from(err: unknown, fallback?: string): AppError;
+}
+
 /**
  * τjs [ taujs ] Orchestration System
  * (c) 2024-present Aoede Ltd
@@ -161,15 +197,15 @@ type AppConfig = {
     routes?: AppRoute[];
 };
 type TaujsConfig = {
+    apps: AppConfig[];
+    security?: SecurityConfig;
     server?: {
         host?: string;
         port?: number;
         hmrPort?: number;
     };
-    security?: SecurityConfig;
-    apps: AppConfig[];
 };
 
 declare function defineConfig<T extends TaujsConfig>(config: T): T;
 
-export { type AppConfig as A, type BaseLogger as B, type DebugConfig as D, type InitialRouteParams as I, type ServiceRegistry as S, type TaujsConfig as T, type SecurityConfig as a, type AppRoute as b, defineServiceRegistry as c, defineConfig as d, defineService as e };
+export { type AppConfig as A, type BaseLogger as B, type DebugConfig as D, type InitialRouteParams as I, type RegistryCaller as R, type ServiceRegistry as S, type TaujsConfig as T, type SecurityConfig as a, type AppRoute as b, callServiceMethod as c, defineConfig as d, defineService as e, defineServiceRegistry as f, type ServiceContext as g, AppError as h, withDeadline as w };

package/dist/Config.d.ts

@@ -1,3 +1,3 @@
 import 'fastify';
 import 'vite';
-export { A as AppConfig, b as AppRoute, a as SecurityConfig, T as TaujsConfig, d as defineConfig, e as defineService, c as defineServiceRegistry } from './Config-LCDjtT9m.js';
+export { A as AppConfig, h as AppError, b as AppRoute, R as RegistryCaller, a as SecurityConfig, g as ServiceContext, T as TaujsConfig, c as callServiceMethod, d as defineConfig, e as defineService, f as defineServiceRegistry, w as withDeadline } from './Config-CEhfq8Mm.js';

package/dist/Config.js

@@ -1,19 +1,186 @@
 // src/utils/DataServices.ts
-var defineService = (spec) => {
+import { performance } from "perf_hooks";
+
+// src/logging/AppError.ts
+var HTTP_STATUS = {
+  infra: 500,
+  upstream: 502,
+  domain: 404,
+  validation: 400,
+  auth: 403,
+  canceled: 499,
+  // Client Closed Request (nginx convention)
+  timeout: 504
+};
+var AppError = class _AppError extends Error {
+  kind;
+  httpStatus;
+  details;
+  safeMessage;
+  code;
+  constructor(message, kind, options = {}) {
+    super(message);
+    this.name = "AppError";
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (options.cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: options.cause,
+        enumerable: false,
+        writable: false,
+        configurable: true
+      });
+    }
+    this.kind = kind;
+    this.httpStatus = options.httpStatus ?? HTTP_STATUS[kind];
+    this.details = options.details;
+    this.safeMessage = options.safeMessage ?? this.getSafeMessage(kind, message);
+    this.code = options.code;
+    if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+  }
+  getSafeMessage(kind, message) {
+    return kind === "domain" || kind === "validation" || kind === "auth" ? message : "Internal Server Error";
+  }
+  serialiseValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+    if (value === null || value === void 0) return value;
+    if (typeof value !== "object") return value;
+    if (seen.has(value)) return "[circular]";
+    seen.add(value);
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+        ...value instanceof _AppError && {
+          kind: value.kind,
+          httpStatus: value.httpStatus,
+          code: value.code
+        }
+      };
+    }
+    if (Array.isArray(value)) return value.map((item) => this.serialiseValue(item, seen));
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = this.serialiseValue(val, seen);
+    }
+    return result;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      kind: this.kind,
+      message: this.message,
+      safeMessage: this.safeMessage,
+      httpStatus: this.httpStatus,
+      ...this.code && { code: this.code },
+      details: this.serialiseValue(this.details),
+      stack: this.stack,
+      ...this.cause && {
+        cause: this.serialiseValue(this.cause)
+      }
+    };
+  }
+  static notFound(message, details, code) {
+    return new _AppError(message, "domain", { httpStatus: 404, details, code });
+  }
+  static forbidden(message, details, code) {
+    return new _AppError(message, "auth", { httpStatus: 403, details, code });
+  }
+  static badRequest(message, details, code) {
+    return new _AppError(message, "validation", { httpStatus: 400, details, code });
+  }
+  static unprocessable(message, details, code) {
+    return new _AppError(message, "validation", { httpStatus: 422, details, code });
+  }
+  static timeout(message, details, code) {
+    return new _AppError(message, "timeout", { details, code });
+  }
+  static canceled(message, details, code) {
+    return new _AppError(message, "canceled", { details, code });
+  }
+  static internal(message, cause, details, code) {
+    return new _AppError(message, "infra", { cause, details, code });
+  }
+  static upstream(message, cause, details, code) {
+    return new _AppError(message, "upstream", { cause, details, code });
+  }
+  static serviceUnavailable(message, cause, details, code) {
+    return new _AppError(message, "infra", { httpStatus: 503, cause, details, code });
+  }
+  static from(err, fallback = "Internal error") {
+    return err instanceof _AppError ? err : _AppError.internal(err?.message ?? fallback, err);
+  }
+};
+
+// src/utils/DataServices.ts
+var runSchema = (schema, input) => {
+  if (!schema) return input;
+  return typeof schema.parse === "function" ? schema.parse(input) : schema(input);
+};
+function withDeadline(signal, ms) {
+  if (!ms) return signal;
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort(signal?.reason ?? new Error("Aborted"));
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const t = setTimeout(() => ctrl.abort(new Error("DeadlineExceeded")), ms);
+  ctrl.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", onAbort);
+    },
+    { once: true }
+  );
+  return ctrl.signal;
+}
+function defineService(spec) {
   const out = {};
-  for (const [k, v] of Object.entries(spec)) {
+  for (const [name, v] of Object.entries(spec)) {
     if (typeof v === "function") {
-      out[k] = { handler: v };
+      out[name] = v;
     } else {
-      out[k] = {
-        handler: v.handler,
-        parsers: v.parsers ?? (v.params || v.result ? { params: v.params, result: v.result } : void 0)
+      const { handler, params: paramsSchema, result: resultSchema } = v;
+      out[name] = async (params, ctx) => {
+        const p = runSchema(paramsSchema, params);
+        const r = await handler(p, ctx);
+        return runSchema(resultSchema, r);
       };
     }
   }
-  return out;
-};
-var defineServiceRegistry = (registry) => registry;
+  return Object.freeze(out);
+}
+var defineServiceRegistry = (registry) => Object.freeze(Object.fromEntries(Object.entries(registry).map(([k, v]) => [k, Object.freeze(v)])));
+async function callServiceMethod(registry, serviceName, methodName, params, ctx) {
+  if (ctx.signal?.aborted) throw AppError.timeout("Request canceled");
+  const service = registry[serviceName];
+  if (!service) throw AppError.notFound(`Unknown service: ${serviceName}`);
+  const method = service[methodName];
+  if (!method) throw AppError.notFound(`Unknown method: ${serviceName}.${methodName}`);
+  const logger = ctx.logger?.child?.({
+    component: "service-call",
+    service: serviceName,
+    method: methodName,
+    traceId: ctx.traceId
+  });
+  const t0 = performance.now();
+  try {
+    const result = await method(params ?? {}, ctx);
+    if (typeof result !== "object" || result === null) {
+      throw AppError.internal(`Non-object result from ${serviceName}.${methodName}`);
+    }
+    logger?.debug?.({ ms: +(performance.now() - t0).toFixed(1) }, "Service method ok");
+    return result;
+  } catch (err) {
+    logger?.error?.(
+      {
+        params,
+        error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : String(err),
+        ms: +(performance.now() - t0).toFixed(1)
+      },
+      "Service method failed"
+    );
+    throw err instanceof AppError ? err : err instanceof Error ? AppError.internal(err.message, { cause: err }) : AppError.internal("Unknown error", { details: { err } });
+  }
+}
 
 // src/Config.ts
 function defineConfig(config) {
@@ -21,7 +188,10 @@ function defineConfig(config) {
   return config;
 }
 export {
+  AppError,
+  callServiceMethod,
   defineConfig,
   defineService,
-  defineServiceRegistry
+  defineServiceRegistry,
+  withDeadline
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { FastifyPluginCallback, FastifyPluginAsync, FastifyInstance } from 'fastify';
-import { T as TaujsConfig, S as ServiceRegistry, D as DebugConfig, B as BaseLogger, A as AppConfig } from './Config-LCDjtT9m.js';
-export { I as InitialRouteParams } from './Config-LCDjtT9m.js';
-import 'vite';
+import { T as TaujsConfig, S as ServiceRegistry, D as DebugConfig, B as BaseLogger, A as AppConfig } from './Config-CEhfq8Mm.js';
+export { I as InitialRouteParams } from './Config-CEhfq8Mm.js';
+import { InlineConfig } from 'vite';
 
 type StaticMountEntry = {
     plugin: FastifyPluginCallback<any> | FastifyPluginAsync<any>;
@@ -42,13 +42,93 @@ declare const createServer: (opts: CreateServerOptions) => Promise<CreateServerR
  * including CSR, SSR, streaming, and middleware composition.
  */
 
-declare function taujsBuild({ config, projectRoot, clientBaseDir, isSSRBuild, }: {
+type ViteBuildContext = {
+    appId: string;
+    entryPoint: string;
+    isSSRBuild: boolean;
+    clientRoot: string;
+};
+/**
+ * User-supplied vite config override.
+ * Can be a static config object or a function that receives build context.
+ *
+ * **Plugin order**: Framework applies plugins in this sequence:
+ * 1. `appConfig.plugins` (from taujs.config.ts)
+ * 2. `nodePolyfills({ include: ['stream'] })` (client builds only)
+ * 3. `userViteConfig.plugins` (from this option)
+ *
+ * If you need plugins before nodePolyfills, add them to `appConfig.plugins` instead.
+ *
+ * **Allowed customisations:**
+ * - `plugins`: Appended to framework plugin list
+ * - `define`: Shallow-merged with framework defines
+ * - `css.preprocessorOptions`: Deep-merged by preprocessor engine (scss, less, etc.)
+ * - `build.sourcemap`, `minify`, `terserOptions`: Direct overrides
+ * - `build.rollupOptions.external`: Direct override
+ * - `build.rollupOptions.output.manualChunks`: Merged into output config
+ * - `resolve.*` (except `alias`): Merged with framework resolve config
+ * - `esbuild`, `logLevel`, `optimizeDeps`: Direct overrides
+ *
+ * **Protected fields (cannot override):**
+ * - `root`, `base`, `publicDir`: Framework-controlled per-app paths
+ * - `build.outDir`: Framework manages `dist/client` vs `dist/ssr` separation
+ * - `build.ssr`, `ssrManifest`, `format`, `target`: Framework-controlled for SSR integrity
+ * - `build.rollupOptions.input`: Framework manages entry points
+ * - `resolve.alias`: Use top-level `alias` option in taujsBuild() instead
+ * - `server.*`: Ignored in builds (dev-mode only; configure in DevServer.ts)
+ *
+ * @example
+ * ```ts
+ * // Static config
+ * vite: {
+ *   plugins: [visualizer()],
+ *   build: { sourcemap: 'inline' }
+ * }
+ *
+ * // Function-based (conditional per app/mode)
+ * vite: ({ isSSRBuild, entryPoint }) => ({
+ *   plugins: isSSRBuild ? [] : [visualizer()],
+ *   logLevel: entryPoint === 'admin' ? 'info' : 'warn'
+ * })
+ * ```
+ */
+type ViteConfigOverride = Partial<InlineConfig> | ((ctx: ViteBuildContext) => Partial<InlineConfig>);
+declare function taujsBuild({ config, projectRoot, clientBaseDir, isSSRBuild, alias: userAlias, vite: userViteConfig, }: {
     config: {
         apps: AppConfig[];
     };
     projectRoot: string;
     clientBaseDir: string;
     isSSRBuild?: boolean;
+    /**
+     * Top-level alias overrides. Use this instead of `vite.resolve.alias`.
+     * User aliases are merged with framework defaults; user values win on conflicts.
+     *
+     * Framework provides:
+     * - `@client`: Resolves to current app's root
+     * - `@server`: Resolves to `src/server`
+     * - `@shared`: Resolves to `src/shared`
+     *
+     * @example
+     * ```ts
+     * alias: {
+     *   '@utils': './src/utils',
+     *   '@server': './custom-server', // overrides framework default
+     * }
+     * ```
+     */
+    alias?: Record<string, string>;
+    /** User-supplied Vite config overrides (plugins, tuning, etc.) */
+    vite?: ViteConfigOverride;
 }): Promise<void>;
 
-export { createServer, taujsBuild };
+interface MessageMetaLogger {
+    debug?: (message?: string, meta?: Record<string, unknown>) => unknown;
+    info?: (message?: string, meta?: Record<string, unknown>) => unknown;
+    warn?: (message?: string, meta?: Record<string, unknown>) => unknown;
+    error?: (message?: string, meta?: Record<string, unknown>) => unknown;
+    child?: (bindings: Record<string, unknown>) => MessageMetaLogger | undefined;
+}
+declare function winstonAdapter(winston: MessageMetaLogger): BaseLogger;
+
+export { BaseLogger, createServer, taujsBuild, winstonAdapter };