External LibrariesType Definitions

Type Definitions

Provide TypeScript types for better developer experience.

Why Provide Types?

When you register a Type URL, ReAPI provides:

  • Autocomplete in the web editor
  • Parameter hints when using generators
  • Error detection for incorrect usage
  • Documentation on hover

Generating Types

The template automatically generates types during build:

npm run build
 
# Output:
# dist/build.umd.js  (bundle)
# dist/build.d.ts    (types)

TypeScript Config

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "dist",
    "emitDeclarationOnly": false
  }
}

Rollup Config

// rollup.config.js
import dts from "rollup-plugin-dts";
 
export default [
  // Bundle config
  {
    input: "src/index.ts",
    output: { file: "dist/build.umd.js", format: "umd" },
  },
  // Types config
  {
    input: "src/index.ts",
    output: { file: "dist/build.d.ts", format: "es" },
    plugins: [dts()],
  },
];

Type Structure

Your .d.ts file should expose the library interface:

// dist/build.d.ts
 
export interface AssertionFunction {
  id: string;
  name: string;
  description?: string;
  enabled: boolean;
  deprecated: boolean;
  tested: boolean;
  function: (value: unknown, expected?: unknown) => void | Promise<void>;
}
 
export interface ValueFunction {
  id: string;
  name: string;
  description?: string;
  enabled: boolean;
  deprecated: boolean;
  tested: boolean;
  function: (options?: unknown) => unknown | Promise<unknown>;
}
 
// Exported arrays
export declare const $$AssertionFunctions: AssertionFunction[];
export declare const $$ValueFunctions: ValueFunction[];
 
// Utility functions
export declare function hashSHA256(data: string): string;
export declare function formatCurrency(amount: number, currency?: string): string;

Global Type Declarations

Include types for ReAPI runtime globals in your project:

// src/types/globals.d.ts
 
// Context and variables
declare const $context: Record<string, any>;
declare const $vars: Record<string, any>;
declare const $secrets: Record<string, any>;
 
// Server configuration
declare const $server: {
  id: string;
  name: string;
  baseUrl: string;
};
 
// Authentication
declare const $auth: {
  type: "bearer" | "apiKey" | "basic" | "none";
  headers: Record<string, string>;
  token?: string;
  apiKey?: string;
};
 
// Request/Response (in hooks)
declare const $request: {
  url: string;
  method: string;
  headers: Record<string, string>;
  query: Record<string, string>;
  body: any;
  timeout: number;
};
 
declare const $response: {
  status: number;
  statusText: string;
  headers: Record<string, string>;
  body: any;
  responseTime: number;
};
 
// Functions
declare function $addAssertionResult(result: {
  passed: boolean;
  message: string;
  operator: string;
  leftValue: any;
  rightValue: any;
}): void;
 
declare function $log(
  level: "info" | "warn" | "error" | "debug",
  message: string,
  data?: any
): void;
 
declare function $reportApiRequest(report: {
  method: string;
  url: string;
  status: number;
  duration: number;
  requestHeaders?: Record<string, string>;
  requestBody?: any;
  responseHeaders?: Record<string, string>;
  responseBody?: any;
}): void;
 
// Built-in libraries
declare const _: typeof import("lodash");
declare const faker: typeof import("@faker-js/faker").faker;
declare const z: typeof import("zod").z;
declare const ky: typeof import("ky").default;
declare const luxon: typeof import("luxon");

Documenting Parameters

Use JSDoc comments for rich documentation:

/**
 * Generates test user data
 * @param options - Configuration options
 * @param options.role - User role (default: "user")
 * @param options.verified - Whether user is verified (default: false)
 * @param options.count - Number of users to generate (default: 1)
 * @returns Generated user object(s)
 * @example
 * // Generate single admin user
 * generateTestUser({ role: "admin", verified: true })
 * 
 * // Generate 5 regular users
 * generateTestUser({ count: 5 })
 */
export function generateTestUser(options?: {
  role?: "admin" | "user" | "guest";
  verified?: boolean;
  count?: number;
}): User | User[];

Registering Type URL

In ReAPI External Libraries settings:

Type URL: https://unpkg.com/@your-org/test-lib@1.0.0/dist/build.d.ts

After registering:

  • Hover over functions shows documentation
  • Parameters show type hints
  • Autocomplete suggests available methods

Type URL Sources

npm + unpkg

https://unpkg.com/@your-org/test-lib@1.0.0/dist/build.d.ts

npm + jsDelivr

https://cdn.jsdelivr.net/npm/@your-org/test-lib@1.0.0/dist/build.d.ts

Self-hosted

https://your-cdn.com/libs/test-lib/1.0.0/build.d.ts

Best Practices

Keep Types in Sync

Types should match the actual implementation:

// ❌ Bad: Types don't match implementation
// types: generateUser(name: string)
// impl: generateUser(options: { name: string })
 
// ✅ Good: Types match exactly
// types: generateUser(options?: { name?: string })
// impl: generateUser(options?: { name?: string })

Export All Public APIs

// ✅ Export everything users might need
export { $$AssertionFunctions } from "./assertions";
export { $$ValueFunctions } from "./generators";
export { hashSHA256, formatCurrency } from "./utils";
export type { User, Order, PaymentConfig } from "./types";

Version Types with Code

Types should be published with the same version:

npm version patch  # Updates both code and types
npm publish        # Publishes both
Registration & SyncTroubleshooting