Description

Goals

• Provide a reliable, validated RPC layer across distributed client, server, and UI runtimes.
• Eliminate runtime bugs using strict schema validation with Zod.
• Support contract-driven communication methods with full TypeScript safety.
• Enable retry logic and timeout handling across distributed runtime conditions.

• Fournir une couche RPC fiable et validée entre les runtimes client, serveur et UI distribués.
• Éliminer les bugs runtime grâce à une validation de schéma stricte avec Zod.
• Prendre en charge des méthodes de communication basées sur des contrats avec toute la sécurité TypeScript.
• Permettre la logique de retry et la gestion des timeouts dans des conditions d'exécution distribuées.

Features

• Built for distributed runtime environments: Supports communication across client, server, and UI layers with a consistent, contract-driven interface.
• Contract-driven design: Define RPC methods with Zod schemas and auto-generate fully-typed APIs with runtime validation.
• Cross-environment communication: Handles bi-directional calls between Client ⇄ Server, Client ⇄ UI, and UI ⇄ Client.
• Retry and timeout handling: Built-in support for configurable retry strategies, delay enforcement, and timeout safeguards.
• Runtime environment safety: Prevents incorrect usage by validating the execution context before sending or handling RPC calls.
• Response routing and cleanup: Uses UUIDs to track and clean up response listeners automatically for better memory and safety control.

• Conçu pour les environnements d'exécution distribués: Prend en charge la communication entre les couches client, serveur et UI avec une interface cohérente basée sur des contrats.
• Design basé sur des contrats: Définissez des méthodes RPC avec des schémas Zod et générez automatiquement des APIs entièrement typées avec validation runtime.
• Communication cross-environnement: Gère les appels bidirectionnels entre Client ⇄ Server, Client ⇄ UI et UI ⇄ Client.
• Gestion des retry et timeouts: Support intégré pour des stratégies de retry configurables, l'application de délais et des protections timeout.
• Sécurité de l'environnement d'exécution: Empêche une utilisation incorrecte en validant le contexte d'exécution avant d'envoyer ou de gérer des appels RPC.
• Routage des réponses et nettoyage: Utilise des UUIDs pour suivre et nettoyer automatiquement les listeners de réponse pour un meilleur contrôle de la mémoire.

Usage

• // 1. Define a contract using Zod for type-safe args and return values
  import { z } from 'zod';
  import { Contract } from '@smaiill/evo';
  
  const userContract = new Contract({
    getUser: {
      args: z.object({ id: z.number() }),
      returns: z.object({ name: z.string(), email: z.string() }),
    },
  }).build();

• // 2. Define a server-side RPC listener (RS = server, RC = client)
  userContract.createListener('rs', 'rc', {
    getUser: async ({ id }) => {
      // Simulate user data fetching
      return { name: 'Alice', email: 'alice@example.com' };
    },
  });

• // 3. Define a client-side API (RC = client, RS = server)
  const api = userContract.createApi('rc', 'rs');
  
  // Make a request to the server from the client
  const user = await api.getUser({ id: 1 });
  // Output: { name: string; email: string }

• // 4. Add retry options to make the method more resilient
  const contractWithRetry = new Contract({
    getUser: {
      args: z.object({ id: z.number() }),
      returns: z.object({ name: z.string() }),
      retryOptions: {
        max: 3,          // Max 3 attempts
        delay: 1000,     // Wait 1 second between retries
        forceDelay: false,
      },
    },
  }).build();

• // 5. Global timeout for all API calls in the contract (in ms)
  const contractWithTimeout = new Contract(
    {
      getUser: {
        args: z.object({ id: z.number() }),
        returns: z.object({ name: z.string() }),
      },
    },
    {
      timeout: 5000, // 5 seconds max timeout for RPC calls
    }
  ).build();

Learning outcomes

• Built a runtime-safe, contract-based RPC system for a multi-environment game framework
• Applied deep type inference and validation using TypeScript and Zod

• Construction d'un système RPC sûr à l'exécution et basé sur des contrats
• Application d'une inférence de types profonde et d'une validation avec TypeScript et Zod