@vertz/core 0.2.0 → 0.2.1

package/README.md

@@ -629,6 +629,50 @@ router.post('/send', {
 });
 ```
 
+### Environment Validation
+
+`createEnv` validates environment variables against a schema at startup, returning a frozen, typed configuration object.
+
+```typescript
+import { createEnv } from '@vertz/core';
+import { s } from '@vertz/schema';
+
+const env = createEnv({
+  schema: s.object({
+    DATABASE_URL: s.string(),
+    PORT: s.coerce.number().default(3000),
+    NODE_ENV: s.enum(['development', 'production', 'test']),
+  }),
+});
+
+// env.DATABASE_URL — fully typed, validated, immutable
+```
+
+By default, `createEnv` reads from `process.env`. You can pass an explicit `env` record instead — useful for edge runtimes (Cloudflare Workers, Deno Deploy) or testing:
+
+```typescript
+// Edge runtime — pass env explicitly
+const env = createEnv({
+  schema: s.object({
+    DATABASE_URL: s.string(),
+    API_KEY: s.string(),
+  }),
+  env: context.env, // Cloudflare Workers env bindings
+});
+
+// Testing — inject controlled values
+const env = createEnv({
+  schema: s.object({ PORT: s.coerce.number() }),
+  env: { PORT: '4000' },
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `schema` | `Schema<T>` | A `@vertz/schema` schema to validate against |
+| `env` | `Record<string, string \| undefined>` | Explicit env record. Defaults to `process.env` with a `typeof process` guard for non-Node runtimes |
+| `load` | `string[]` | Dotenv file paths to load before validation |
+
 ### Custom Server Adapters
 
 Use the `.handler` property to integrate with custom servers:

package/dist/index.d.ts

@@ -213,25 +213,39 @@ interface CorsConfig {
 	maxAge?: number;
 	exposedHeaders?: string[];
 }
-interface DomainDefinition {
+interface EntityDefinition {
+	readonly kind?: string;
 	readonly name: string;
-	readonly type: string;
-	readonly table: unknown;
-	readonly exposedRelations: Record<string, unknown>;
+	readonly model: unknown;
 	readonly access: Record<string, unknown>;
-	readonly handlers: Record<string, unknown>;
+	readonly before: Record<string, unknown>;
+	readonly after: Record<string, unknown>;
 	readonly actions: Record<string, unknown>;
+	readonly relations: Record<string, unknown>;
+}
+/**
+* An entity route entry generated by @vertz/server's route generator.
+* Core doesn't know about entity internals — it just registers these as handlers.
+*/
+interface EntityRouteEntry {
+	method: string;
+	path: string;
+	handler: (ctx: Record<string, unknown>) => Promise<Response>;
 }
 interface AppConfig {
 	basePath?: string;
 	version?: string;
 	cors?: CorsConfig;
-	/** Domain definitions for auto-CRUD route generation */
-	domains?: DomainDefinition[];
-	/** API prefix for domain routes (default: '/api/') */
+	/** Entity definitions for auto-CRUD route generation */
+	entities?: EntityDefinition[];
+	/** API prefix for entity routes (default: '/api/') */
 	apiPrefix?: string;
 	/** Enable response schema validation in dev mode (logs warnings but doesn't break response) */
 	validateResponses?: boolean;
+	/** Internal: pre-built entity route handlers injected by @vertz/server */
+	_entityRoutes?: EntityRouteEntry[];
+	/** Internal: factory for creating DB adapters per entity (used by @vertz/server) */
+	_entityDbFactory?: (entityDef: EntityDefinition) => unknown;
 }
 interface ListenOptions {
 	hostname?: string;
@@ -290,6 +304,7 @@ import { Schema as Schema3 } from "@vertz/schema";
 interface EnvConfig<T = unknown> {
 	load?: string[];
 	schema: Schema3<T>;
+	env?: Record<string, string | undefined>;
 }
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 type HttpStatusCode = 200 | 201 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 502 | 503 | 504;
@@ -300,7 +315,13 @@ declare class VertzException extends Error {
 	readonly code: string;
 	readonly details?: unknown;
 	constructor(message: string, statusCode?: number, code?: string, details?: unknown);
-	toJSON(): Record<string, unknown>;
+	toJSON(): {
+		error: {
+			code: string;
+			message: string;
+			details?: unknown;
+		};
+	};
 }
 declare class BadRequestException extends VertzException {
 	constructor(message: string, details?: unknown);
@@ -326,7 +347,16 @@ declare class ValidationException extends VertzException {
 		path: string;
 		message: string;
 	}>);
-	toJSON(): Record<string, unknown>;
+	toJSON(): {
+		error: {
+			code: string;
+			message: string;
+			details?: ReadonlyArray<{
+				path: string;
+				message: string;
+			}>;
+		};
+	};
 }
 declare class InternalServerErrorException extends VertzException {
 	constructor(message: string, details?: unknown);
@@ -347,121 +377,6 @@ declare const vertz: {
 	readonly server: typeof createApp;
 };
 /**
-* Symbol used to brand Result objects to prevent accidental matches with user data.
-* Using a Symbol makes it impossible for user objects to accidentally match isResult().
-*/
-declare const RESULT_BRAND: unique symbol;
-/**
-* Result type for explicit error handling in route handlers.
-*
-* This provides an alternative to exception-based error handling,
-* making error cases visible in type signatures.
-*
-* @example
-* ```typescript
-* router.get('/:id', {
-*   handler: async (ctx) => {
-*     const user = await ctx.userService.find(ctx.params.id);
-*     if (!user) {
-*       return err(404, { message: 'User not found' });
-*     }
-*     return ok({ id: user.id, name: user.name });
-*   }
-* });
-* ```
-*/
-/**
-* Represents a successful result containing data.
-*/
-interface Ok<T> {
-	readonly ok: true;
-	readonly data: T;
-	readonly [RESULT_BRAND]: true;
-}
-/**
-* Represents an error result containing status code and error body.
-*/
-interface Err<E> {
-	readonly ok: false;
-	readonly status: number;
-	readonly body: E;
-	readonly [RESULT_BRAND]: true;
-}
-/**
-* A discriminated union type representing either a success (Ok) or failure (Err).
-*
-* @typeParam T - The type of the success data
-* @typeParam E - The type of the error body
-*
-* @example
-* ```typescript
-* type UserResult = Result<{ id: number; name: string }, { message: string }>;
-* ```
-*/
-type Result<
-	T,
-	E = unknown
-> = Ok<T> | Err<E>;
-/**
-* Creates a successful Result containing the given data.
-*
-* @param data - The success data
-* @returns An Ok result with the data
-*
-* @example
-* ```typescript
-* return ok({ id: 1, name: 'John' });
-* ```
-*/
-declare function ok<T>(data: T): Ok<T>;
-/**
-* Creates an error Result with the given status code and body.
-*
-* @param status - HTTP status code for the error
-* @param body - Error body/response
-* @returns An Err result with status and body
-*
-* @example
-* ```typescript
-* return err(404, { message: 'Not found' });
-* ```
-*/
-declare function err<E>(status: number, body: E): Err<E>;
-/**
-* Type guard to check if a Result is Ok.
-*
-* @param result - The result to check
-* @returns True if the result is Ok
-*
-* @example
-* ```typescript
-* if (isOk(result)) {
-*   console.log(result.data);
-* }
-* ```
-*/
-declare function isOk<
-	T,
-	E
->(result: Result<T, E>): result is Ok<T>;
-/**
-* Type guard to check if a Result is Err.
-*
-* @param result - The result to check
-* @returns True if the result is Err
-*
-* @example
-* ```typescript
-* if (isErr(result)) {
-*   console.log(result.status, result.body);
-* }
-* ```
-*/
-declare function isErr<
-	T,
-	E
->(result: Result<T, E>): result is Err<E>;
-/**
 * Creates an HTTP server. Preferred entry point for building Vertz services.
 * @since 0.2.0
 */
@@ -470,4 +385,4 @@ declare const createServer: (config: AppConfig) => AppBuilder;
 * @deprecated Use `createServer` instead. `createApp` will be removed in v0.3.0.
 */
 declare const createApp2: (config: AppConfig) => AppBuilder;
-export { vertz, ok, makeImmutable, isOk, isErr, err, deepFreeze, createServer, createModuleDef, createModule, createMiddleware, createImmutableProxy, createEnv, createApp2 as createApp, VertzException, ValidationException, UnauthorizedException, ServiceUnavailableException, ServiceFactory, ServiceDef, ServiceBootInstruction, ServerHandle, ServerAdapter, RouterDef, RouteInfo, Result, ResolveInjectMap, RawRequest, Ok, NotFoundException, NamedServiceDef, NamedRouterDef, NamedModuleDef, NamedModule, NamedMiddlewareDef, ModuleDef, ModuleBootInstruction, Module, MiddlewareDef, ListenOptions, InternalServerErrorException, Infer2 as InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, ExtractMethods, Err, EnvConfig, Deps, DeepReadonly, Ctx, CorsConfig, ConflictException, BootSequence, BootInstruction, BadRequestException, AppConfig, AppBuilder, AccumulateProvides };
+export { vertz, makeImmutable, deepFreeze, createServer, createModuleDef, createModule, createMiddleware, createImmutableProxy, createEnv, createApp2 as createApp, VertzException, ValidationException, UnauthorizedException, ServiceUnavailableException, ServiceFactory, ServiceDef, ServiceBootInstruction, ServerHandle, ServerAdapter, RouterDef, RouteInfo, ResolveInjectMap, RawRequest, NotFoundException, NamedServiceDef, NamedRouterDef, NamedModuleDef, NamedModule, NamedMiddlewareDef, ModuleDef, ModuleBootInstruction, Module, MiddlewareDef, ListenOptions, InternalServerErrorException, Infer2 as InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, ExtractMethods, EnvConfig, EntityRouteEntry, Deps, DeepReadonly, Ctx, CorsConfig, ConflictException, BootSequence, BootInstruction, BadRequestException, AppConfig, AppBuilder, AccumulateProvides };

package/dist/index.js

@@ -18,7 +18,19 @@ import {
   parseBody,
   parseRequest,
   runMiddlewareChain
-} from "./shared/chunk-c77pg5gx.js";
+} from "./shared/chunk-k596zpc6.js";
+
+// src/result.ts
+var RESULT_BRAND = Symbol.for("vertz.result");
+function isOk(result) {
+  return result.ok === true;
+}
+function isResult(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const obj = value;
+  return obj[RESULT_BRAND] === true;
+}
 
 // src/server/cors.ts
 var DEFAULT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
@@ -77,27 +89,6 @@ function applyCorsHeaders(config, request, response) {
   });
 }
 
-// src/result.ts
-var RESULT_BRAND = Symbol.for("vertz.result");
-function ok(data) {
-  return { ok: true, data, [RESULT_BRAND]: true };
-}
-function err(status, body) {
-  return { ok: false, status, body, [RESULT_BRAND]: true };
-}
-function isOk(result) {
-  return result.ok === true;
-}
-function isErr(result) {
-  return result.ok === false;
-}
-function isResult(value) {
-  if (value === null || typeof value !== "object")
-    return false;
-  const obj = value;
-  return obj[RESULT_BRAND] === true;
-}
-
 // src/app/app-runner.ts
 function createResponseWithCors(data, status, config, request) {
   const response = createJsonResponse(data, status);
@@ -107,14 +98,12 @@ function createResponseWithCors(data, status, config, request) {
   return response;
 }
 function validateSchema(schema, value, label) {
-  try {
-    return schema.parse(value);
-  } catch (error) {
-    if (error instanceof BadRequestException)
-      throw error;
-    const message = error instanceof Error ? error.message : `Invalid ${label}`;
+  const result = schema.parse(value);
+  if (!result.ok) {
+    const message = result.error instanceof Error ? result.error.message : `Invalid ${label}`;
     throw new BadRequestException(message);
   }
+  return result.data;
 }
 function resolveServices(registrations) {
   const serviceMap = new Map;
@@ -124,7 +113,7 @@ function resolveServices(registrations) {
         let parsedOptions = {};
         if (service.options && options) {
           const parsed = service.options.safeParse(options);
-          if (parsed.success) {
+          if (parsed.ok) {
             parsedOptions = parsed.data;
           } else {
             throw new Error(`Invalid options for service ${service.moduleName}: ${parsed.error.issues.map((i) => i.message).join(", ")}`);
@@ -189,6 +178,17 @@ function buildHandler(config, registrations, globalMiddlewares) {
   const resolvedMiddlewares = resolveMiddlewares(globalMiddlewares);
   const serviceMap = resolveServices(registrations);
   registerRoutes(trie, basePath, registrations, serviceMap);
+  if (config._entityRoutes) {
+    for (const route of config._entityRoutes) {
+      const entry = {
+        handler: route.handler,
+        options: {},
+        services: {},
+        middlewares: []
+      };
+      trie.add(route.method, route.path, entry);
+    }
+  }
   return async (request) => {
     try {
       if (config.cors) {
@@ -201,9 +201,9 @@ function buildHandler(config, registrations, globalMiddlewares) {
       if (!match) {
         const allowed = trie.getAllowedMethods(parsed.path);
         if (allowed.length > 0) {
-          return createJsonResponse({ error: "MethodNotAllowed", message: "Method Not Allowed", statusCode: 405 }, 405, { allow: allowed.join(", ") });
+          return createJsonResponse({ error: { code: "MethodNotAllowed", message: "Method Not Allowed" } }, 405, { allow: allowed.join(", ") });
         }
-        return createJsonResponse({ error: "NotFound", message: "Not Found", statusCode: 404 }, 404);
+        return createJsonResponse({ error: { code: "NotFound", message: "Not Found" } }, 404);
       }
       const body = await parseBody(request);
       const raw = {
@@ -246,10 +246,9 @@ function buildHandler(config, registrations, globalMiddlewares) {
         if (isOk(result)) {
           const data = result.data;
           if (config.validateResponses && entry.responseSchema) {
-            try {
-              entry.responseSchema.parse(data);
-            } catch (error) {
-              const message = error instanceof Error ? error.message : "Response schema validation failed";
+            const validation = entry.responseSchema.parse(data);
+            if (!validation.ok) {
+              const message = validation.error instanceof Error ? validation.error.message : "Response schema validation failed";
               console.warn(`[vertz] Response validation warning: ${message}`);
             }
           }
@@ -260,10 +259,9 @@ function buildHandler(config, registrations, globalMiddlewares) {
           if (config.validateResponses && entry.errorsSchema) {
             const errorSchema = entry.errorsSchema[errorStatus];
             if (errorSchema) {
-              try {
-                errorSchema.parse(errorBody);
-              } catch (error) {
-                const message = error instanceof Error ? `Error schema validation failed for status ${errorStatus}: ${error.message}` : `Error schema validation failed for status ${errorStatus}`;
+              const validation = errorSchema.parse(errorBody);
+              if (!validation.ok) {
+                const message = validation.error instanceof Error ? `Error schema validation failed for status ${errorStatus}: ${validation.error.message}` : `Error schema validation failed for status ${errorStatus}`;
                 console.warn(`[vertz] Response validation warning: ${message}`);
               }
             }
@@ -272,14 +270,13 @@ function buildHandler(config, registrations, globalMiddlewares) {
         }
       }
       if (config.validateResponses && entry.responseSchema) {
-        try {
-          entry.responseSchema.parse(result);
-        } catch (error) {
-          const message = error instanceof Error ? error.message : "Response schema validation failed";
+        const validation = entry.responseSchema.parse(result);
+        if (!validation.ok) {
+          const message = validation.error instanceof Error ? validation.error.message : "Response schema validation failed";
           console.warn(`[vertz] Response validation warning: ${message}`);
         }
       }
-      const response = result === undefined ? new Response(null, { status: 204 }) : createJsonResponse(result);
+      const response = result === undefined ? new Response(null, { status: 204 }) : result instanceof Response ? result : createJsonResponse(result);
       if (config.cors) {
         return applyCorsHeaders(config.cors, request, response);
       }
@@ -367,6 +364,7 @@ function createApp(config) {
   let globalMiddlewares = [];
   let cachedHandler = null;
   const registeredRoutes = [];
+  const entityRoutes = [];
   const builder = {
     register(module, options) {
       registrations.push({ module, options });
@@ -395,35 +393,47 @@ function createApp(config) {
       const adapter = detectAdapter();
       const serverHandle = await adapter.listen(port ?? DEFAULT_PORT, builder.handler, options);
       if (options?.logRoutes !== false) {
-        const routes = collectRoutes(config.basePath ?? "", registrations);
+        const moduleRoutes = collectRoutes(config.basePath ?? "", registrations);
+        const routes = [...moduleRoutes, ...entityRoutes];
         const url = `http://${serverHandle.hostname}:${serverHandle.port}`;
         console.log(formatRouteLog(url, routes));
       }
       return serverHandle;
     }
   };
-  if (config.domains && config.domains.length > 0) {
+  if (config._entityRoutes) {
+    for (const route of config._entityRoutes) {
+      const info = { method: route.method, path: route.path };
+      registeredRoutes.push(info);
+      entityRoutes.push(info);
+    }
+  } else if (config.entities && config.entities.length > 0) {
     const rawPrefix = config.apiPrefix === undefined ? "/api/" : config.apiPrefix;
-    for (const domain of config.domains) {
-      const domainPath = rawPrefix === "" ? "/" + domain.name : (rawPrefix.endsWith("/") ? rawPrefix : rawPrefix + "/") + domain.name;
-      registeredRoutes.push({ method: "GET", path: domainPath });
-      registeredRoutes.push({ method: "GET", path: `${domainPath}/:id` });
-      registeredRoutes.push({ method: "POST", path: domainPath });
-      registeredRoutes.push({ method: "PUT", path: `${domainPath}/:id` });
-      registeredRoutes.push({ method: "DELETE", path: `${domainPath}/:id` });
-      if (domain.actions) {
-        for (const actionName of Object.keys(domain.actions)) {
-          registeredRoutes.push({ method: "POST", path: `${domainPath}/:id/${actionName}` });
+    for (const entity of config.entities) {
+      const entityPath = rawPrefix === "" ? `/${entity.name}` : (rawPrefix.endsWith("/") ? rawPrefix : `${rawPrefix}/`) + entity.name;
+      const routes = [
+        { method: "GET", path: entityPath },
+        { method: "GET", path: `${entityPath}/:id` },
+        { method: "POST", path: entityPath },
+        { method: "PATCH", path: `${entityPath}/:id` },
+        { method: "DELETE", path: `${entityPath}/:id` }
+      ];
+      if (entity.actions) {
+        for (const actionName of Object.keys(entity.actions)) {
+          routes.push({ method: "POST", path: `${entityPath}/:id/${actionName}` });
         }
       }
+      registeredRoutes.push(...routes);
+      entityRoutes.push(...routes);
     }
   }
   return builder;
 }
 // src/env/env-validator.ts
 function createEnv(config) {
-  const result = config.schema.safeParse(process.env);
-  if (!result.success) {
+  const envRecord = config.env ?? (typeof process !== "undefined" ? process.env : {});
+  const result = config.schema.safeParse(envRecord);
+  if (!result.ok) {
     throw new Error(`Environment validation failed:
 ${result.error.message}`);
   }
@@ -511,11 +521,7 @@ var createApp2 = (...args) => {
 };
 export {
   vertz,
-  ok,
   makeImmutable,
-  isOk,
-  isErr,
-  err,
   deepFreeze,
   createServer,
   createModuleDef,

package/dist/internals.js

@@ -6,7 +6,7 @@ import {
   parseBody,
   parseRequest,
   runMiddlewareChain
-} from "./shared/chunk-c77pg5gx.js";
+} from "./shared/chunk-k596zpc6.js";
 export {
   runMiddlewareChain,
   parseRequest,

package/dist/shared/{chunk-c77pg5gx.js → chunk-k596zpc6.js}

@@ -41,7 +41,7 @@ function deepFreeze(obj, visited = new WeakSet) {
 
 // src/immutability/make-immutable.ts
 function makeImmutable(obj, contextName) {
-  if (true) {
+  if (typeof process !== "undefined" && true) {
     return createImmutableProxy(obj, contextName);
   }
   return obj;
@@ -65,7 +65,7 @@ function validateCollisions(config) {
   }
 }
 function buildCtx(config) {
-  if (true) {
+  if (typeof process !== "undefined" && true) {
     validateCollisions(config);
   }
   return makeImmutable({
@@ -98,11 +98,11 @@ class VertzException extends Error {
   }
   toJSON() {
     return {
-      error: this.name,
-      message: this.message,
-      statusCode: this.statusCode,
-      code: this.code,
-      ...this.details !== undefined && { details: this.details }
+      error: {
+        code: this.code,
+        message: this.message,
+        ...this.details !== undefined && { details: this.details }
+      }
     };
   }
 }
@@ -110,57 +110,60 @@ class VertzException extends Error {
 // src/exceptions/http-exceptions.ts
 class BadRequestException extends VertzException {
   constructor(message, details) {
-    super(message, 400, undefined, details);
+    super(message, 400, "BadRequest", details);
   }
 }
 
 class UnauthorizedException extends VertzException {
   constructor(message, details) {
-    super(message, 401, undefined, details);
+    super(message, 401, "Unauthorized", details);
   }
 }
 
 class ForbiddenException extends VertzException {
   constructor(message, details) {
-    super(message, 403, undefined, details);
+    super(message, 403, "Forbidden", details);
   }
 }
 
 class NotFoundException extends VertzException {
   constructor(message, details) {
-    super(message, 404, undefined, details);
+    super(message, 404, "NotFound", details);
   }
 }
 
 class ConflictException extends VertzException {
   constructor(message, details) {
-    super(message, 409, undefined, details);
+    super(message, 409, "Conflict", details);
   }
 }
 
 class ValidationException extends VertzException {
   errors;
   constructor(errors) {
-    super("Validation failed", 422, undefined, undefined);
+    super("Validation failed", 422, "ValidationError", undefined);
     this.errors = errors;
   }
   toJSON() {
     return {
-      ...super.toJSON(),
-      errors: this.errors
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.errors
+      }
     };
   }
 }
 
 class InternalServerErrorException extends VertzException {
   constructor(message, details) {
-    super(message, 500, undefined, details);
+    super(message, 500, "InternalError", details);
   }
 }
 
 class ServiceUnavailableException extends VertzException {
   constructor(message, details) {
-    super(message, 503, undefined, details);
+    super(message, 503, "ServiceUnavailable", details);
   }
 }
 // src/middleware/middleware-runner.ts
@@ -334,7 +337,7 @@ function createErrorResponse(error) {
   if (error instanceof VertzException) {
     return createJsonResponse(error.toJSON(), error.statusCode);
   }
-  return createJsonResponse({ error: "InternalServerError", message: "Internal Server Error", statusCode: 500 }, 500);
+  return createJsonResponse({ error: { code: "InternalServerError", message: "Internal Server Error" } }, 500);
 }
 
 export { createImmutableProxy, deepFreeze, makeImmutable, buildCtx, VertzException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, ConflictException, ValidationException, InternalServerErrorException, ServiceUnavailableException, runMiddlewareChain, Trie, parseRequest, parseBody, createJsonResponse, createErrorResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "license": "MIT",
   "description": "Vertz core framework primitives",
@@ -30,15 +30,16 @@
   ],
   "scripts": {
     "build": "bunup",
-    "test": "vitest run",
+    "test": "bun test",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vertz/schema": "workspace:*"
+    "@vertz/schema": "0.2.1"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.3.1",
     "@vitest/coverage-v8": "^4.0.18",
     "bunup": "latest",
     "typescript": "^5.7.0",