@reactive-contracts/server 0.1.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mariano Álvarez
+
+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/README.md

@@ -0,0 +1,143 @@
+# @reactive-contracts/server
+
+Server-side implementation utilities for Reactive Contracts.
+
+## Installation
+
+```bash
+npm install @reactive-contracts/server @reactive-contracts/core
+# or
+yarn add @reactive-contracts/server @reactive-contracts/core
+# or
+pnpm add @reactive-contracts/server @reactive-contracts/core
+```
+
+## Usage
+
+### Implementing a Contract
+
+```typescript
+import { implementContract } from '@reactive-contracts/server';
+import { UserProfileContract } from './contracts/user-profile.contract';
+
+export const UserProfileResolver = implementContract(UserProfileContract, {
+  async resolve({ userId }, context) {
+    const user = await db.users.findById(userId);
+    const activity = await db.activity.getForUser(userId);
+    
+    return {
+      user: {
+        id: user.id,
+        name: user.name,
+        avatar: user.avatarUrl,
+        joinedAt: user.createdAt,
+      },
+      activity: {
+        postsCount: activity.posts,
+        lastActive: activity.lastSeen,
+      },
+    };
+  },
+
+  cache: {
+    ttl: '5m',
+    staleWhileRevalidate: '1h',
+    tags: (params) => [`user:${params.userId}`],
+  },
+});
+```
+
+### With Validation
+
+```typescript
+export const CreateUserResolver = implementContract(CreateUserContract, {
+  async resolve(params, context) {
+    const user = await db.users.create(params);
+    return user;
+  },
+
+  validate: (params) => {
+    return params.email.includes('@') && params.name.length > 0;
+  },
+
+  onError: (error, params, context) => {
+    console.error('Failed to create user:', error);
+  },
+});
+```
+
+### Using in an API Endpoint
+
+```typescript
+import { UserProfileResolver } from './resolvers/user-profile.resolver';
+
+// Express example
+app.get('/api/users/:userId', async (req, res) => {
+  try {
+    const result = await UserProfileResolver.execute(
+      { userId: req.params.userId },
+      { user: req.user }
+    );
+    
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+## API
+
+### `implementContract(contract, implementation)`
+
+Creates a contract resolver for server-side implementation.
+
+**Parameters:**
+- `contract`: Contract definition
+- `implementation`: Implementation config
+  - `resolve`: Resolver function `(params, context) => data | Promise<data>`
+  - `validate?`: Validation function `(params) => boolean | Promise<boolean>`
+  - `cache?`: Caching configuration
+    - `ttl?`: Time to live (e.g., '5m', '1h')
+    - `staleWhileRevalidate?`: Stale cache duration
+    - `tags?`: Cache tag generator function
+  - `onError?`: Error handler function
+
+**Returns:** ContractResolver object with:
+- `contract`: The original contract
+- `implementation`: The implementation config
+- `execute`: Function to execute the resolver
+
+### Resolver Context
+
+The context object passed to resolvers can include:
+- `request?`: HTTP request object
+- `headers?`: Request headers
+- `user?`: Authenticated user
+- Any custom properties you add
+
+### Cache Configuration
+
+- `ttl`: How long to cache the result (e.g., '5m' for 5 minutes)
+- `staleWhileRevalidate`: How long to serve stale data while revalidating
+- `tags`: Function that returns cache tags for invalidation
+
+### Latency Monitoring
+
+The server automatically monitors latency and logs warnings when constraints are exceeded:
+
+```typescript
+// If contract has: latency: max('100ms')
+// And execution takes 350ms, a warning will be logged
+```
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+- Resolver functions are typed based on contract shape
+- Context is fully typed
+- Parameters are validated at compile time
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,167 @@
+'use strict';
+
+// src/implementContract.ts
+function implementContract(contract, implementation) {
+  if (!implementation.resolve || typeof implementation.resolve !== "function") {
+    throw new Error(`Contract ${contract.definition.name} must have a resolve function`);
+  }
+  const execute = async (params, context = {}) => {
+    try {
+      if (implementation.validate) {
+        const isValid = await implementation.validate(params);
+        if (!isValid) {
+          throw new Error("Parameter validation failed");
+        }
+      }
+      const startTime = Date.now();
+      const result = await implementation.resolve(params, context);
+      const executionTime = Date.now() - startTime;
+      if (contract.definition.constraints?.latency) {
+        const maxLatency = parseLatency(contract.definition.constraints.latency.max);
+        if (executionTime > maxLatency) {
+          console.warn(
+            `Contract ${contract.definition.name} exceeded latency constraint: ${executionTime}ms > ${maxLatency}ms`
+          );
+        }
+      }
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Unknown error");
+      implementation.onError?.(err, params, context);
+      throw err;
+    }
+  };
+  return {
+    contract,
+    implementation,
+    execute
+  };
+}
+function parseLatency(latency) {
+  const match = latency.match(/^(\d+)(ms|s|m)$/);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid latency format: ${latency}`);
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 60 * 1e3;
+    default:
+      throw new Error(`Unknown latency unit: ${unit}`);
+  }
+}
+
+// src/express.ts
+function createContractHandler(resolver) {
+  return async (req, res, next) => {
+    try {
+      const startTime = Date.now();
+      const { params = {}, contract: contractName } = req.body;
+      if (contractName && contractName !== resolver.contract.definition.name) {
+        res.status(400).json({
+          error: "Contract name mismatch",
+          expected: resolver.contract.definition.name,
+          received: contractName
+        });
+        return;
+      }
+      const reqWithUser = req;
+      const userValue = reqWithUser.user;
+      const result = await resolver.execute(params, {
+        user: typeof userValue === "object" && userValue !== null ? userValue : void 0,
+        // If using auth middleware
+        headers: req.headers,
+        ip: req.ip
+      });
+      const executionTime = Date.now() - startTime;
+      const latencyStatus = evaluateLatencyStatus(resolver.contract, executionTime);
+      res.json({
+        data: result,
+        status: {
+          latency: latencyStatus,
+          freshness: "fresh",
+          availability: "available"
+        },
+        metadata: {
+          executionTime,
+          cacheHit: false,
+          derivedAt: "origin"
+        }
+      });
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function createContractRouter(resolvers) {
+  return async (req, res, next) => {
+    try {
+      const contractName = req.params.contract || req.body.contract;
+      if (!contractName) {
+        res.status(400).json({
+          error: "Contract name is required"
+        });
+        return;
+      }
+      const resolver = resolvers[contractName];
+      if (!resolver) {
+        res.status(404).json({
+          error: "Contract not found",
+          contract: contractName,
+          available: Object.keys(resolvers)
+        });
+        return;
+      }
+      const handler = createContractHandler(resolver);
+      await handler(req, res, next);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function evaluateLatencyStatus(contract, actualLatency) {
+  const latencyConstraint = contract.definition.constraints?.latency;
+  if (!latencyConstraint) {
+    return "normal";
+  }
+  const maxLatency = parseLatencyToMs(latencyConstraint.max);
+  if (maxLatency === null) {
+    return "normal";
+  }
+  if (actualLatency <= maxLatency) {
+    return "normal";
+  } else if (actualLatency <= maxLatency * 1.5) {
+    return "degraded";
+  } else {
+    return "violated";
+  }
+}
+function parseLatencyToMs(latency) {
+  const match = latency.match(/^(\d+)(ms|s|m)$/);
+  if (!match || !match[1] || !match[2]) {
+    return null;
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 60 * 1e3;
+    default:
+      return null;
+  }
+}
+
+exports.createContractHandler = createContractHandler;
+exports.createContractRouter = createContractRouter;
+exports.implementContract = implementContract;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/implementContract.ts","../src/express.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Contract } from '@reactive-contracts/core';\nimport type { ContractImplementation, ContractResolver, ResolverContext } from './types.js';\n\n/**\n * Implement a contract resolver on the server side\n *\n * @example\n * ```typescript\n * const UserProfileResolver = implementContract<\n *   { userId: string },\n *   { user: { id: string; name: string } }\n * >(UserProfileContract, {\n *   async resolve({ userId }, context) {\n *     const user = await db.users.findById(userId);\n *     return {\n *       user: {\n *         id: user.id,\n *         name: user.name,\n *         avatar: user.avatarUrl,\n *       },\n *     };\n *   },\n *   cache: {\n *     ttl: '5m',\n *     tags: (params) => [`user:${params.userId}`],\n *   },\n * });\n * ```\n */\nexport function implementContract<TParams, TData>(\n  contract: Contract,\n  implementation: ContractImplementation<TParams, TData>\n): ContractResolver<TParams, TData> {\n  // Validate implementation\n  if (!implementation.resolve || typeof implementation.resolve !== 'function') {\n    throw new Error(`Contract ${contract.definition.name} must have a resolve function`);\n  }\n\n  const execute = async (params: TParams, context: ResolverContext = {}): Promise<TData> => {\n    try {\n      // Validate params if validator provided\n      if (implementation.validate) {\n        const isValid = await implementation.validate(params);\n        if (!isValid) {\n          throw new Error('Parameter validation failed');\n        }\n      }\n\n      // Execute the resolver\n      const startTime = Date.now();\n      const result = await implementation.resolve(params, context);\n      const executionTime = Date.now() - startTime;\n\n      // Check latency constraints\n      if (contract.definition.constraints?.latency) {\n        const maxLatency = parseLatency(contract.definition.constraints.latency.max);\n        if (executionTime > maxLatency) {\n          console.warn(\n            `Contract ${contract.definition.name} exceeded latency constraint: ${executionTime}ms > ${maxLatency}ms`\n          );\n        }\n      }\n\n      return result;\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error('Unknown error');\n\n      // Call error handler if provided\n      implementation.onError?.(err, params, context);\n\n      throw err;\n    }\n  };\n\n  return {\n    contract,\n    implementation,\n    execute,\n  };\n}\n\n/**\n * Parse latency string to milliseconds\n */\nfunction parseLatency(latency: string): number {\n  const match = latency.match(/^(\\d+)(ms|s|m)$/);\n  if (!match || !match[1] || !match[2]) {\n    throw new Error(`Invalid latency format: ${latency}`);\n  }\n\n  const value = parseInt(match[1], 10);\n  const unit = match[2];\n\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    default:\n      throw new Error(`Unknown latency unit: ${unit}`);\n  }\n}\n","import type { Request, Response, NextFunction } from 'express';\nimport type { Contract } from '@reactive-contracts/core';\nimport type { ContractResolver } from './types.js';\n\n/**\n * Create an Express handler for a contract resolver\n */\nexport function createContractHandler<TParams, TData>(\n  resolver: ContractResolver<TParams, TData>\n): (req: Request, res: Response, next: NextFunction) => Promise<void> {\n  return async (req: Request, res: Response, next: NextFunction) => {\n    try {\n      const startTime = Date.now();\n\n      // Extract params from request body\n      const { params = {}, contract: contractName } = req.body;\n\n      // Validate contract name matches\n      if (contractName && contractName !== resolver.contract.definition.name) {\n        res.status(400).json({\n          error: 'Contract name mismatch',\n          expected: resolver.contract.definition.name,\n          received: contractName,\n        });\n        return;\n      }\n\n      // Execute the contract\n      const reqWithUser = req as unknown as Record<string, unknown>;\n      const userValue = reqWithUser.user;\n      const result = await resolver.execute(params, {\n        user:\n          typeof userValue === 'object' && userValue !== null\n            ? (userValue as Record<string, unknown>)\n            : undefined, // If using auth middleware\n        headers: req.headers as Record<string, string>,\n        ip: req.ip,\n      });\n\n      const executionTime = Date.now() - startTime;\n\n      // Evaluate latency status\n      const latencyStatus = evaluateLatencyStatus(resolver.contract, executionTime);\n\n      // Send response\n      res.json({\n        data: result,\n        status: {\n          latency: latencyStatus,\n          freshness: 'fresh',\n          availability: 'available',\n        },\n        metadata: {\n          executionTime,\n          cacheHit: false,\n          derivedAt: 'origin',\n        },\n      });\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Create an Express router for multiple contract resolvers\n * Uses Record with generic resolver type for flexibility\n */\nexport function createContractRouter<\n  TResolvers extends Record<string, ContractResolver<unknown, unknown>>,\n>(resolvers: TResolvers): (req: Request, res: Response, next: NextFunction) => Promise<void> {\n  return async (req: Request, res: Response, next: NextFunction) => {\n    try {\n      // Extract contract name from URL or body\n      const contractName = req.params.contract || req.body.contract;\n\n      if (!contractName) {\n        res.status(400).json({\n          error: 'Contract name is required',\n        });\n        return;\n      }\n\n      const resolver = resolvers[contractName];\n\n      if (!resolver) {\n        res.status(404).json({\n          error: 'Contract not found',\n          contract: contractName,\n          available: Object.keys(resolvers),\n        });\n        return;\n      }\n\n      // Delegate to contract handler\n      const handler = createContractHandler(resolver);\n      await handler(req, res, next);\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Evaluate latency status based on contract constraints\n */\nfunction evaluateLatencyStatus(\n  contract: Contract,\n  actualLatency: number\n): 'normal' | 'degraded' | 'violated' {\n  const latencyConstraint = contract.definition.constraints?.latency;\n\n  if (!latencyConstraint) {\n    return 'normal';\n  }\n\n  const maxLatency = parseLatencyToMs(latencyConstraint.max);\n  if (maxLatency === null) {\n    return 'normal';\n  }\n\n  if (actualLatency <= maxLatency) {\n    return 'normal';\n  } else if (actualLatency <= maxLatency * 1.5) {\n    return 'degraded';\n  } else {\n    return 'violated';\n  }\n}\n\n/**\n * Parse latency string to milliseconds\n */\nfunction parseLatencyToMs(latency: string): number | null {\n  const match = latency.match(/^(\\d+)(ms|s|m)$/);\n  if (!match || !match[1] || !match[2]) {\n    return null;\n  }\n\n  const value = parseInt(match[1], 10);\n  const unit = match[2];\n\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    default:\n      return null;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { Contract } from '@reactive-contracts/core';
+import { Request as Request$1, Response, NextFunction } from 'express';
+
+interface ResolverContext {
+    request?: Request;
+    headers?: Record<string, string>;
+    user?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+type ResolverFn<TParams, TData, TContext extends ResolverContext = ResolverContext> = (params: TParams, context: TContext) => Promise<TData> | TData;
+interface CacheConfig<TParams> {
+    ttl?: string;
+    staleWhileRevalidate?: string;
+    tags?: (params: TParams) => string[];
+}
+interface ContractImplementation<TParams, TData, TContext extends ResolverContext = ResolverContext> {
+    resolve: ResolverFn<TParams, TData, TContext>;
+    cache?: CacheConfig<TParams>;
+    validate?: (params: TParams) => boolean | Promise<boolean>;
+    onError?: (error: Error, params: TParams, context: TContext) => void;
+}
+interface ContractResolver<TParams, TData> {
+    contract: Contract;
+    implementation: ContractImplementation<TParams, TData>;
+    execute: (params: TParams, context?: ResolverContext) => Promise<TData>;
+}
+
+declare function implementContract<TParams, TData>(contract: Contract, implementation: ContractImplementation<TParams, TData>): ContractResolver<TParams, TData>;
+
+declare function createContractHandler<TParams, TData>(resolver: ContractResolver<TParams, TData>): (req: Request$1, res: Response, next: NextFunction) => Promise<void>;
+declare function createContractRouter<TResolvers extends Record<string, ContractResolver<unknown, unknown>>>(resolvers: TResolvers): (req: Request$1, res: Response, next: NextFunction) => Promise<void>;
+
+export { type CacheConfig, type ContractImplementation, type ContractResolver, type ResolverContext, type ResolverFn, createContractHandler, createContractRouter, implementContract };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { Contract } from '@reactive-contracts/core';
+import { Request as Request$1, Response, NextFunction } from 'express';
+
+interface ResolverContext {
+    request?: Request;
+    headers?: Record<string, string>;
+    user?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+type ResolverFn<TParams, TData, TContext extends ResolverContext = ResolverContext> = (params: TParams, context: TContext) => Promise<TData> | TData;
+interface CacheConfig<TParams> {
+    ttl?: string;
+    staleWhileRevalidate?: string;
+    tags?: (params: TParams) => string[];
+}
+interface ContractImplementation<TParams, TData, TContext extends ResolverContext = ResolverContext> {
+    resolve: ResolverFn<TParams, TData, TContext>;
+    cache?: CacheConfig<TParams>;
+    validate?: (params: TParams) => boolean | Promise<boolean>;
+    onError?: (error: Error, params: TParams, context: TContext) => void;
+}
+interface ContractResolver<TParams, TData> {
+    contract: Contract;
+    implementation: ContractImplementation<TParams, TData>;
+    execute: (params: TParams, context?: ResolverContext) => Promise<TData>;
+}
+
+declare function implementContract<TParams, TData>(contract: Contract, implementation: ContractImplementation<TParams, TData>): ContractResolver<TParams, TData>;
+
+declare function createContractHandler<TParams, TData>(resolver: ContractResolver<TParams, TData>): (req: Request$1, res: Response, next: NextFunction) => Promise<void>;
+declare function createContractRouter<TResolvers extends Record<string, ContractResolver<unknown, unknown>>>(resolvers: TResolvers): (req: Request$1, res: Response, next: NextFunction) => Promise<void>;
+
+export { type CacheConfig, type ContractImplementation, type ContractResolver, type ResolverContext, type ResolverFn, createContractHandler, createContractRouter, implementContract };

package/dist/index.js

@@ -0,0 +1,163 @@
+// src/implementContract.ts
+function implementContract(contract, implementation) {
+  if (!implementation.resolve || typeof implementation.resolve !== "function") {
+    throw new Error(`Contract ${contract.definition.name} must have a resolve function`);
+  }
+  const execute = async (params, context = {}) => {
+    try {
+      if (implementation.validate) {
+        const isValid = await implementation.validate(params);
+        if (!isValid) {
+          throw new Error("Parameter validation failed");
+        }
+      }
+      const startTime = Date.now();
+      const result = await implementation.resolve(params, context);
+      const executionTime = Date.now() - startTime;
+      if (contract.definition.constraints?.latency) {
+        const maxLatency = parseLatency(contract.definition.constraints.latency.max);
+        if (executionTime > maxLatency) {
+          console.warn(
+            `Contract ${contract.definition.name} exceeded latency constraint: ${executionTime}ms > ${maxLatency}ms`
+          );
+        }
+      }
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Unknown error");
+      implementation.onError?.(err, params, context);
+      throw err;
+    }
+  };
+  return {
+    contract,
+    implementation,
+    execute
+  };
+}
+function parseLatency(latency) {
+  const match = latency.match(/^(\d+)(ms|s|m)$/);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid latency format: ${latency}`);
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 60 * 1e3;
+    default:
+      throw new Error(`Unknown latency unit: ${unit}`);
+  }
+}
+
+// src/express.ts
+function createContractHandler(resolver) {
+  return async (req, res, next) => {
+    try {
+      const startTime = Date.now();
+      const { params = {}, contract: contractName } = req.body;
+      if (contractName && contractName !== resolver.contract.definition.name) {
+        res.status(400).json({
+          error: "Contract name mismatch",
+          expected: resolver.contract.definition.name,
+          received: contractName
+        });
+        return;
+      }
+      const reqWithUser = req;
+      const userValue = reqWithUser.user;
+      const result = await resolver.execute(params, {
+        user: typeof userValue === "object" && userValue !== null ? userValue : void 0,
+        // If using auth middleware
+        headers: req.headers,
+        ip: req.ip
+      });
+      const executionTime = Date.now() - startTime;
+      const latencyStatus = evaluateLatencyStatus(resolver.contract, executionTime);
+      res.json({
+        data: result,
+        status: {
+          latency: latencyStatus,
+          freshness: "fresh",
+          availability: "available"
+        },
+        metadata: {
+          executionTime,
+          cacheHit: false,
+          derivedAt: "origin"
+        }
+      });
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function createContractRouter(resolvers) {
+  return async (req, res, next) => {
+    try {
+      const contractName = req.params.contract || req.body.contract;
+      if (!contractName) {
+        res.status(400).json({
+          error: "Contract name is required"
+        });
+        return;
+      }
+      const resolver = resolvers[contractName];
+      if (!resolver) {
+        res.status(404).json({
+          error: "Contract not found",
+          contract: contractName,
+          available: Object.keys(resolvers)
+        });
+        return;
+      }
+      const handler = createContractHandler(resolver);
+      await handler(req, res, next);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function evaluateLatencyStatus(contract, actualLatency) {
+  const latencyConstraint = contract.definition.constraints?.latency;
+  if (!latencyConstraint) {
+    return "normal";
+  }
+  const maxLatency = parseLatencyToMs(latencyConstraint.max);
+  if (maxLatency === null) {
+    return "normal";
+  }
+  if (actualLatency <= maxLatency) {
+    return "normal";
+  } else if (actualLatency <= maxLatency * 1.5) {
+    return "degraded";
+  } else {
+    return "violated";
+  }
+}
+function parseLatencyToMs(latency) {
+  const match = latency.match(/^(\d+)(ms|s|m)$/);
+  if (!match || !match[1] || !match[2]) {
+    return null;
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 60 * 1e3;
+    default:
+      return null;
+  }
+}
+
+export { createContractHandler, createContractRouter, implementContract };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/implementContract.ts","../src/express.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Contract } from '@reactive-contracts/core';\nimport type { ContractImplementation, ContractResolver, ResolverContext } from './types.js';\n\n/**\n * Implement a contract resolver on the server side\n *\n * @example\n * ```typescript\n * const UserProfileResolver = implementContract<\n *   { userId: string },\n *   { user: { id: string; name: string } }\n * >(UserProfileContract, {\n *   async resolve({ userId }, context) {\n *     const user = await db.users.findById(userId);\n *     return {\n *       user: {\n *         id: user.id,\n *         name: user.name,\n *         avatar: user.avatarUrl,\n *       },\n *     };\n *   },\n *   cache: {\n *     ttl: '5m',\n *     tags: (params) => [`user:${params.userId}`],\n *   },\n * });\n * ```\n */\nexport function implementContract<TParams, TData>(\n  contract: Contract,\n  implementation: ContractImplementation<TParams, TData>\n): ContractResolver<TParams, TData> {\n  // Validate implementation\n  if (!implementation.resolve || typeof implementation.resolve !== 'function') {\n    throw new Error(`Contract ${contract.definition.name} must have a resolve function`);\n  }\n\n  const execute = async (params: TParams, context: ResolverContext = {}): Promise<TData> => {\n    try {\n      // Validate params if validator provided\n      if (implementation.validate) {\n        const isValid = await implementation.validate(params);\n        if (!isValid) {\n          throw new Error('Parameter validation failed');\n        }\n      }\n\n      // Execute the resolver\n      const startTime = Date.now();\n      const result = await implementation.resolve(params, context);\n      const executionTime = Date.now() - startTime;\n\n      // Check latency constraints\n      if (contract.definition.constraints?.latency) {\n        const maxLatency = parseLatency(contract.definition.constraints.latency.max);\n        if (executionTime > maxLatency) {\n          console.warn(\n            `Contract ${contract.definition.name} exceeded latency constraint: ${executionTime}ms > ${maxLatency}ms`\n          );\n        }\n      }\n\n      return result;\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error('Unknown error');\n\n      // Call error handler if provided\n      implementation.onError?.(err, params, context);\n\n      throw err;\n    }\n  };\n\n  return {\n    contract,\n    implementation,\n    execute,\n  };\n}\n\n/**\n * Parse latency string to milliseconds\n */\nfunction parseLatency(latency: string): number {\n  const match = latency.match(/^(\\d+)(ms|s|m)$/);\n  if (!match || !match[1] || !match[2]) {\n    throw new Error(`Invalid latency format: ${latency}`);\n  }\n\n  const value = parseInt(match[1], 10);\n  const unit = match[2];\n\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    default:\n      throw new Error(`Unknown latency unit: ${unit}`);\n  }\n}\n","import type { Request, Response, NextFunction } from 'express';\nimport type { Contract } from '@reactive-contracts/core';\nimport type { ContractResolver } from './types.js';\n\n/**\n * Create an Express handler for a contract resolver\n */\nexport function createContractHandler<TParams, TData>(\n  resolver: ContractResolver<TParams, TData>\n): (req: Request, res: Response, next: NextFunction) => Promise<void> {\n  return async (req: Request, res: Response, next: NextFunction) => {\n    try {\n      const startTime = Date.now();\n\n      // Extract params from request body\n      const { params = {}, contract: contractName } = req.body;\n\n      // Validate contract name matches\n      if (contractName && contractName !== resolver.contract.definition.name) {\n        res.status(400).json({\n          error: 'Contract name mismatch',\n          expected: resolver.contract.definition.name,\n          received: contractName,\n        });\n        return;\n      }\n\n      // Execute the contract\n      const reqWithUser = req as unknown as Record<string, unknown>;\n      const userValue = reqWithUser.user;\n      const result = await resolver.execute(params, {\n        user:\n          typeof userValue === 'object' && userValue !== null\n            ? (userValue as Record<string, unknown>)\n            : undefined, // If using auth middleware\n        headers: req.headers as Record<string, string>,\n        ip: req.ip,\n      });\n\n      const executionTime = Date.now() - startTime;\n\n      // Evaluate latency status\n      const latencyStatus = evaluateLatencyStatus(resolver.contract, executionTime);\n\n      // Send response\n      res.json({\n        data: result,\n        status: {\n          latency: latencyStatus,\n          freshness: 'fresh',\n          availability: 'available',\n        },\n        metadata: {\n          executionTime,\n          cacheHit: false,\n          derivedAt: 'origin',\n        },\n      });\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Create an Express router for multiple contract resolvers\n * Uses Record with generic resolver type for flexibility\n */\nexport function createContractRouter<\n  TResolvers extends Record<string, ContractResolver<unknown, unknown>>,\n>(resolvers: TResolvers): (req: Request, res: Response, next: NextFunction) => Promise<void> {\n  return async (req: Request, res: Response, next: NextFunction) => {\n    try {\n      // Extract contract name from URL or body\n      const contractName = req.params.contract || req.body.contract;\n\n      if (!contractName) {\n        res.status(400).json({\n          error: 'Contract name is required',\n        });\n        return;\n      }\n\n      const resolver = resolvers[contractName];\n\n      if (!resolver) {\n        res.status(404).json({\n          error: 'Contract not found',\n          contract: contractName,\n          available: Object.keys(resolvers),\n        });\n        return;\n      }\n\n      // Delegate to contract handler\n      const handler = createContractHandler(resolver);\n      await handler(req, res, next);\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Evaluate latency status based on contract constraints\n */\nfunction evaluateLatencyStatus(\n  contract: Contract,\n  actualLatency: number\n): 'normal' | 'degraded' | 'violated' {\n  const latencyConstraint = contract.definition.constraints?.latency;\n\n  if (!latencyConstraint) {\n    return 'normal';\n  }\n\n  const maxLatency = parseLatencyToMs(latencyConstraint.max);\n  if (maxLatency === null) {\n    return 'normal';\n  }\n\n  if (actualLatency <= maxLatency) {\n    return 'normal';\n  } else if (actualLatency <= maxLatency * 1.5) {\n    return 'degraded';\n  } else {\n    return 'violated';\n  }\n}\n\n/**\n * Parse latency string to milliseconds\n */\nfunction parseLatencyToMs(latency: string): number | null {\n  const match = latency.match(/^(\\d+)(ms|s|m)$/);\n  if (!match || !match[1] || !match[2]) {\n    return null;\n  }\n\n  const value = parseInt(match[1], 10);\n  const unit = match[2];\n\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    default:\n      return null;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@reactive-contracts/server",
+  "version": "0.1.0-beta",
+  "description": "Server-side implementation utilities for Reactive Contracts",
+  "keywords": [
+    "contracts",
+    "server",
+    "backend",
+    "api"
+  ],
+  "homepage": "https://github.com/creativoma/reactive-contracts",
+  "bugs": {
+    "url": "https://github.com/creativoma/reactive-contracts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/creativoma/reactive-contracts.git",
+    "directory": "packages/server"
+  },
+  "license": "MIT",
+  "author": "Reactive Contracts Contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@reactive-contracts/core": "0.1.0-beta"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist"
+  }
+}