ts-procedures 5.9.1 → 5.10.2

package/src/client/hooks.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, vi } from 'vitest'
+import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
+import type {
+  BeforeRequestContext,
+  AfterResponseContext,
+  ErrorContext,
+  ClientHooks,
+} from './types.js'
+
+// ── helpers ───────────────────────────────────────────────
+
+function makeBeforeCtx(overrides?: Partial<BeforeRequestContext>): BeforeRequestContext {
+  return {
+    procedureName: 'TestProcedure',
+    scope: 'test',
+    request: { url: 'https://example.com', method: 'GET' },
+    ...overrides,
+  }
+}
+
+function makeAfterCtx(overrides?: Partial<AfterResponseContext>): AfterResponseContext {
+  return {
+    procedureName: 'TestProcedure',
+    scope: 'test',
+    request: { url: 'https://example.com', method: 'GET' },
+    response: { status: 200, headers: {}, body: null },
+    ...overrides,
+  }
+}
+
+function makeErrorCtx(overrides?: Partial<ErrorContext>): ErrorContext {
+  return {
+    procedureName: 'TestProcedure',
+    scope: 'test',
+    request: { url: 'https://example.com', method: 'GET' },
+    error: new Error('something went wrong'),
+    ...overrides,
+  }
+}
+
+// ── runBeforeRequest ──────────────────────────────────────
+
+describe('runBeforeRequest', () => {
+  it('runs global hook then local hook in order', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => { order.push('global'); return ctx },
+    }
+    const localHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => { order.push('local'); return ctx },
+    }
+    const ctx = makeBeforeCtx()
+    await runBeforeRequest(ctx, globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('passes the (possibly mutated) context from global to local', async () => {
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: { ...ctx.request, url: 'https://mutated.example.com' },
+      }),
+    }
+    let receivedUrl = ''
+    const localHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => { receivedUrl = ctx.request.url; return ctx },
+    }
+    const ctx = makeBeforeCtx()
+    await runBeforeRequest(ctx, globalHooks, localHooks)
+    expect(receivedUrl).toBe('https://mutated.example.com')
+  })
+
+  it('returns the final mutated context', async () => {
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({ ...ctx, scope: 'mutated-by-global' }),
+    }
+    const localHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({ ...ctx, scope: ctx.scope + '-then-local' }),
+    }
+    const ctx = makeBeforeCtx()
+    const result = await runBeforeRequest(ctx, globalHooks, localHooks)
+    expect(result.scope).toBe('mutated-by-global-then-local')
+  })
+
+  it('handles async hooks', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: async (ctx) => { order.push('global'); return ctx },
+    }
+    const localHooks: ClientHooks = {
+      onBeforeRequest: async (ctx) => { order.push('local'); return ctx },
+    }
+    await runBeforeRequest(makeBeforeCtx(), globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('skips undefined global hook gracefully', async () => {
+    const localHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({ ...ctx, scope: 'local-only' }),
+    }
+    const result = await runBeforeRequest(makeBeforeCtx(), {}, localHooks)
+    expect(result.scope).toBe('local-only')
+  })
+
+  it('skips undefined local hook gracefully', async () => {
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({ ...ctx, scope: 'global-only' }),
+    }
+    const result = await runBeforeRequest(makeBeforeCtx(), globalHooks, undefined)
+    expect(result.scope).toBe('global-only')
+  })
+
+  it('skips both hooks gracefully when neither defined', async () => {
+    const ctx = makeBeforeCtx()
+    const result = await runBeforeRequest(ctx, {}, undefined)
+    expect(result).toEqual(ctx)
+  })
+})
+
+// ── runAfterResponse ──────────────────────────────────────
+
+describe('runAfterResponse', () => {
+  it('runs global then local hook', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = { onAfterResponse: () => { order.push('global') } }
+    const localHooks: ClientHooks = { onAfterResponse: () => { order.push('local') } }
+    await runAfterResponse(makeAfterCtx(), globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('handles async hooks', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = {
+      onAfterResponse: async () => { order.push('global') },
+    }
+    const localHooks: ClientHooks = {
+      onAfterResponse: async () => { order.push('local') },
+    }
+    await runAfterResponse(makeAfterCtx(), globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('skips undefined hooks gracefully', async () => {
+    // Should not throw
+    await runAfterResponse(makeAfterCtx(), {}, undefined)
+  })
+
+  it('returns void', async () => {
+    const result = await runAfterResponse(makeAfterCtx(), {}, undefined)
+    expect(result).toBeUndefined()
+  })
+})
+
+// ── runOnError ────────────────────────────────────────────
+
+describe('runOnError', () => {
+  it('runs global then local hook', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = { onError: () => { order.push('global') } }
+    const localHooks: ClientHooks = { onError: () => { order.push('local') } }
+    await runOnError(makeErrorCtx(), globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('handles async hooks', async () => {
+    const order: string[] = []
+    const globalHooks: ClientHooks = { onError: async () => { order.push('global') } }
+    const localHooks: ClientHooks = { onError: async () => { order.push('local') } }
+    await runOnError(makeErrorCtx(), globalHooks, localHooks)
+    expect(order).toEqual(['global', 'local'])
+  })
+
+  it('skips undefined hooks gracefully', async () => {
+    await runOnError(makeErrorCtx(), {}, undefined)
+  })
+
+  it('returns void', async () => {
+    const result = await runOnError(makeErrorCtx(), {}, undefined)
+    expect(result).toBeUndefined()
+  })
+
+  it('receives the error in context', async () => {
+    const receivedErrors: unknown[] = []
+    const globalHooks: ClientHooks = {
+      onError: (ctx) => { receivedErrors.push(ctx.error) },
+    }
+    const err = new Error('boom')
+    await runOnError(makeErrorCtx({ error: err }), globalHooks, undefined)
+    expect(receivedErrors[0]).toBe(err)
+  })
+})

package/src/client/index.test.ts

@@ -0,0 +1,290 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createClient } from './index.js'
+import { ClientRequestError } from './errors.js'
+import type {
+  ClientAdapter,
+  AdapterRequest,
+  AdapterResponse,
+  AdapterStreamResponse,
+  ClientHooks,
+  CallDescriptor,
+  StreamDescriptor,
+  ClientInstance,
+} from './types.js'
+
+// ── helpers ───────────────────────────────────────────────
+
+async function* makeAsyncIterable<T>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item
+  }
+}
+
+function makeAdapter(
+  responseBody: unknown = { ok: true },
+  streamItems: unknown[] = []
+): ClientAdapter {
+  return {
+    request: vi.fn(async (_req: AdapterRequest): Promise<AdapterResponse> => ({
+      status: 200,
+      headers: {},
+      body: responseBody,
+    })),
+    stream: vi.fn(async (_req: AdapterRequest): Promise<AdapterStreamResponse> => ({
+      status: 200,
+      headers: {},
+      body: makeAsyncIterable(streamItems),
+    })),
+  }
+}
+
+function makeCallDescriptor(overrides?: Partial<CallDescriptor>): CallDescriptor {
+  return {
+    name: 'GetUser',
+    scope: 'users',
+    path: '/users',
+    method: 'GET',
+    kind: 'rpc',
+    params: { id: '1' },
+    ...overrides,
+  }
+}
+
+function makeStreamDescriptor(overrides?: Partial<StreamDescriptor>): StreamDescriptor {
+  return {
+    name: 'WatchUsers',
+    scope: 'users',
+    path: '/stream/users',
+    method: 'POST',
+    kind: 'stream',
+    streamMode: 'sse',
+    params: {},
+    ...overrides,
+  }
+}
+
+// ── createClient ──────────────────────────────────────────
+
+describe('createClient', () => {
+  it('creates a client with typed scope callables', () => {
+    const adapter = makeAdapter()
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: (id: string) =>
+            instance.call<{ id: string; name: string }>(
+              makeCallDescriptor({ params: { id } }),
+            ),
+        },
+      }),
+    })
+
+    expect(client).toHaveProperty('users')
+    expect(client.users).toHaveProperty('getUser')
+    expect(typeof client.users.getUser).toBe('function')
+  })
+
+  it('executes procedure calls through the adapter', async () => {
+    const adapter = makeAdapter({ id: '1', name: 'Alice' })
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: (id: string) =>
+            instance.call<{ id: string; name: string }>(
+              makeCallDescriptor({ params: { id } }),
+            ),
+        },
+      }),
+    })
+
+    const result = await client.users.getUser('1')
+    expect(adapter.request).toHaveBeenCalledOnce()
+    expect(result).toEqual({ id: '1', name: 'Alice' })
+  })
+
+  it('throws ClientRequestError on non-2xx from scope callable', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<AdapterResponse> => ({
+        status: 404,
+        headers: {},
+        body: { message: 'Not Found' },
+      })),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: {},
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: (id: string) =>
+            instance.call<unknown>(makeCallDescriptor({ params: { id } })),
+        },
+      }),
+    })
+
+    await expect(client.users.getUser('99')).rejects.toThrow(ClientRequestError)
+  })
+
+  it('applies global hooks to all calls', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: {},
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: { ...ctx.request, headers: { 'x-api-key': 'secret' } },
+      }),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      hooks: globalHooks,
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: () => instance.call<unknown>(makeCallDescriptor()),
+        },
+      }),
+    })
+
+    await client.users.getUser()
+    expect(capturedHeaders[0]?.['x-api-key']).toBe('secret')
+  })
+
+  it('streaming works — SSE yield and return via client.stream()', async () => {
+    const sseItems = [
+      { data: { n: 1 }, event: 'tick' },
+      { data: { n: 2 }, event: 'tick' },
+      { data: { total: 2 }, event: 'return' },
+    ]
+    const adapter = makeAdapter({}, sseItems)
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        updates: {
+          watch: () => instance.stream<{ n: number }, { total: number }>(
+            makeStreamDescriptor({ streamMode: 'sse' })
+          ),
+        },
+      }),
+    })
+
+    const stream = client.updates.watch()
+
+    const yielded: { n: number }[] = []
+    for await (const item of stream) {
+      yielded.push(item)
+    }
+
+    expect(yielded).toEqual([{ n: 1 }, { n: 2 }])
+    await expect(stream.result).resolves.toEqual({ total: 2 })
+  })
+
+  it('streaming works — text mode yields raw chunks', async () => {
+    const chunks = ['line1\n', 'line2\n']
+    const adapter = makeAdapter({}, chunks)
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        logs: {
+          tail: () => instance.stream<string, void>(
+            makeStreamDescriptor({ streamMode: 'text', name: 'TailLogs', scope: 'logs' })
+          ),
+        },
+      }),
+    })
+
+    const stream = client.logs.tail()
+    const received: string[] = []
+    for await (const chunk of stream) {
+      received.push(chunk)
+    }
+    expect(received).toEqual(chunks)
+    await expect(stream.result).resolves.toBeUndefined()
+  })
+
+  it('stream() is synchronous — returns TypedStream immediately (no await needed)', () => {
+    const adapter = makeAdapter({}, [])
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      scopes: (instance: ClientInstance) => ({
+        updates: {
+          watch: () => instance.stream<string, void>(makeStreamDescriptor()),
+        },
+      }),
+    })
+
+    // Must be synchronous — no await
+    const stream = client.updates.watch()
+    expect(typeof stream[Symbol.asyncIterator]).toBe('function')
+    expect(stream).toHaveProperty('result')
+    expect(stream.result).toBeInstanceOf(Promise)
+  })
+
+  it('applies global hooks to streams', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
+      stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: makeAsyncIterable([]) }
+      }),
+    }
+
+    const globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: { ...ctx.request, headers: { 'x-stream-key': 'stream-secret' } },
+      }),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      hooks: globalHooks,
+      scopes: (instance: ClientInstance) => ({
+        updates: {
+          watch: () => instance.stream<string, void>(makeStreamDescriptor()),
+        },
+      }),
+    })
+
+    const stream = client.updates.watch()
+    for await (const _ of stream) { /* drain */ }
+
+    expect(capturedHeaders[0]?.['x-stream-key']).toBe('stream-secret')
+  })
+
+  it('barrel exports: re-exports ClientRequestError', async () => {
+    // This verifies the exports are accessible — the import at the top covers this
+    const { ClientRequestError: CRE } = await import('./index.js')
+    expect(CRE).toBeDefined()
+  })
+})

package/src/client/request-builder.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from 'vitest'
+import { interpolatePath, buildAdapterRequest } from './request-builder.js'
+import { ClientPathParamError } from './errors.js'
+import type { CallDescriptor } from './types.js'
+
+// ── interpolatePath ───────────────────────────────────────
+
+describe('interpolatePath', () => {
+  it('returns path unchanged when no params are present', () => {
+    expect(interpolatePath('/users', {}, 'GetUsers')).toBe('/users')
+  })
+
+  it('replaces a single :param with the provided value', () => {
+    expect(interpolatePath('/users/:id', { id: '42' }, 'GetUser')).toBe('/users/42')
+  })
+
+  it('replaces multiple :params in one path', () => {
+    expect(
+      interpolatePath('/orgs/:orgId/users/:userId', { orgId: 'acme', userId: '7' }, 'GetUser')
+    ).toBe('/orgs/acme/users/7')
+  })
+
+  it('URI-encodes param values', () => {
+    expect(interpolatePath('/users/:name', { name: 'hello world' }, 'GetUser')).toBe(
+      '/users/hello%20world'
+    )
+  })
+
+  it('throws ClientPathParamError when a required param is missing', () => {
+    expect(() => interpolatePath('/users/:id', {}, 'GetUser')).toThrow(ClientPathParamError)
+  })
+
+  it('throws with descriptive message containing the param name and path', () => {
+    expect(() => interpolatePath('/users/:id', {}, 'GetUser')).toThrow(/id/)
+    expect(() => interpolatePath('/users/:id', {}, 'GetUser')).toThrow(/\/users\/:id/)
+  })
+
+  it('is a no-op when path has no :params', () => {
+    expect(interpolatePath('/static/path', {}, 'Foo')).toBe('/static/path')
+  })
+})
+
+// ── buildAdapterRequest ───────────────────────────────────
+
+describe('buildAdapterRequest', () => {
+  const base: Omit<CallDescriptor, 'kind' | 'params'> = {
+    name: 'GetUser',
+    scope: 'users',
+    path: '/users/:id',
+    method: 'GET',
+  }
+
+  it('RPC: sends flat params as JSON body', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/rpc/GetUser',
+      kind: 'rpc',
+      params: { userId: '42', extra: true },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toBe('https://api.example.com/rpc/GetUser')
+    expect(req.method).toBe('GET')
+    expect(req.body).toEqual({ userId: '42', extra: true })
+    expect(req.headers).toBeUndefined()
+  })
+
+  it('stream: sends flat params as JSON body (same as RPC)', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/stream/Updates',
+      kind: 'stream',
+      params: { filter: 'active' },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toBe('https://api.example.com/stream/Updates')
+    expect(req.body).toEqual({ filter: 'active' })
+  })
+
+  it('API: interpolates pathParams into URL', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/users/:id',
+      kind: 'api',
+      params: { pathParams: { id: '99' } },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toBe('https://api.example.com/users/99')
+    expect(req.body).toBeUndefined()
+  })
+
+  it('API: appends query params to the URL', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/users',
+      kind: 'api',
+      params: { query: { role: 'admin', active: 'true' } },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toContain('role=admin')
+    expect(req.url).toContain('active=true')
+  })
+
+  it('API: sets body from body channel', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/users',
+      method: 'POST',
+      kind: 'api',
+      params: { body: { name: 'Alice', age: 30 } },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.body).toEqual({ name: 'Alice', age: 30 })
+  })
+
+  it('API: merges headers channel into request headers', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/users',
+      kind: 'api',
+      params: { headers: { 'x-tenant-id': 'tenant-123' } },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.headers?.['x-tenant-id']).toBe('tenant-123')
+  })
+
+  it('API GET with query only — no body', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/search',
+      method: 'GET',
+      kind: 'api',
+      params: { query: { q: 'typescript' } },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toContain('q=typescript')
+    expect(req.body).toBeUndefined()
+  })
+
+  it('API: combines pathParams, query, body, and headers together', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/orgs/:orgId/users/:userId',
+      method: 'PUT',
+      kind: 'api',
+      params: {
+        pathParams: { orgId: 'acme', userId: '7' },
+        query: { version: '2' },
+        body: { name: 'Bob' },
+        headers: { 'x-request-id': 'req-xyz' },
+      },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    expect(req.url).toContain('/orgs/acme/users/7')
+    expect(req.url).toContain('version=2')
+    expect(req.body).toEqual({ name: 'Bob' })
+    expect(req.headers?.['x-request-id']).toBe('req-xyz')
+  })
+
+  it('RPC with keys named "body" and "query" is treated as flat — NOT structured', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/rpc/DoThing',
+      kind: 'rpc',
+      params: { body: 'literal-body-value', query: 'literal-query-value' },
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com')
+    // The entire params object goes to body — no query string appended
+    expect(req.body).toEqual({ body: 'literal-body-value', query: 'literal-query-value' })
+    expect(req.url).toBe('https://api.example.com/rpc/DoThing')
+    // Should NOT have a query string derived from params.query
+    expect(req.url).not.toContain('?')
+  })
+
+  it('prepends basePath to the URL', () => {
+    const descriptor: CallDescriptor = {
+      ...base,
+      path: '/users',
+      kind: 'rpc',
+      params: {},
+    }
+    const req = buildAdapterRequest(descriptor, 'https://api.example.com/v1')
+    expect(req.url).toBe('https://api.example.com/v1/users')
+  })
+})