@elmohq/sdk 0.0.0-claim → 0.1.0

package/src/internal/feature/timeout.ts

@@ -0,0 +1,146 @@
+import { TIMER_LIMIT } from '../core/backoff';
+import { replyWith } from '../core/body';
+import { calledOffWith, safeAddress, TimeoutError } from '../core/errors';
+import type {
+  CallableDescriptor,
+  CallTimeout,
+  Feature,
+  PreparedRequest,
+  Result,
+  Send,
+} from '../core/types';
+
+/**
+ * Chooses the limit of one call, given the operation as `METHOD /path` and the
+ * limit it would otherwise get. `undefined` keeps that limit.
+ */
+export type TimeoutPolicy = (operation: string, timeout: CallTimeout) => CallTimeout | undefined;
+
+/** A limit in milliseconds, `false` for none, or a policy choosing one per call. */
+export type TimeoutValue = CallTimeout | TimeoutPolicy;
+
+export interface TimeoutOptions {
+  ms?: number;
+}
+
+function describeTarget(request: PreparedRequest): string | undefined {
+  const { method } = request.callable;
+  if (typeof request.address !== 'string') return undefined;
+  const address = safeAddress(request.address);
+  return method ? `${method.toUpperCase()} "${address}"` : `"${address}"`;
+}
+
+export const DEFAULT_TIMEOUT = 60_000;
+
+function operationKey({ address, method }: CallableDescriptor): string {
+  return method ? `${method.toUpperCase()} ${address}` : address;
+}
+
+export function resolveTimeout(base: TimeoutOptions, request: PreparedRequest): number | undefined {
+  const own = request.callable.timeout ?? base.ms ?? DEFAULT_TIMEOUT;
+  const option = request.options['timeout'] as TimeoutValue | undefined;
+  const ms =
+    typeof option === 'function'
+      ? (option(operationKey(request.callable), own) ?? own)
+      : (option ?? own);
+  if (ms === false) return undefined;
+  return ms > 0 && Number.isFinite(ms) ? ms : undefined;
+}
+
+function watchedReply(
+  response: Response,
+  wait: <T>(pending: Promise<T>) => Promise<T>,
+  done: () => void,
+): Response {
+  const reader = response.body!.getReader();
+  const body = new ReadableStream<Uint8Array>({
+    cancel(reason) {
+      done();
+      return reader.cancel(reason);
+    },
+    async pull(controller) {
+      const step = await wait(reader.read()).catch((error: unknown) => {
+        done();
+        reader.cancel(error).catch(done);
+        throw error;
+      });
+      if (step.done) {
+        done();
+        controller.close();
+      } else {
+        controller.enqueue(step.value);
+      }
+    },
+  });
+  return replyWith(body, response);
+}
+
+export function timeoutFeature(options: TimeoutOptions = {}): Feature {
+  async function bounded(request: PreparedRequest, next: Send, stream: boolean): Promise<Result> {
+    const ms = resolveTimeout(options, request);
+    if (ms === undefined) return next(request);
+    const delay = Math.min(ms, TIMER_LIMIT);
+    let left = delay;
+
+    const caller = request.signal;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    function abortWithCaller(): void {
+      controller.abort(caller?.reason);
+    }
+
+    if (caller?.aborted) abortWithCaller();
+    caller?.addEventListener('abort', abortWithCaller, { once: true });
+
+    const abandoned = new Promise<never>((_, reject) => {
+      function giveUp(): void {
+        reject(calledOffWith(signal.reason));
+      }
+      if (signal.aborted) giveUp();
+      else signal.addEventListener('abort', giveUp, { once: true });
+    });
+    abandoned.catch(() => {});
+
+    function expire(): void {
+      controller.abort(new TimeoutError(ms, undefined, describeTarget(request)));
+    }
+
+    async function wait<T>(pending: Promise<T>): Promise<T> {
+      const started = Date.now();
+      const timer = setTimeout(expire, left);
+      try {
+        return await Promise.race([pending, abandoned]);
+      } finally {
+        clearTimeout(timer);
+        left = stream ? delay : left - (Date.now() - started);
+      }
+    }
+
+    function done(): void {
+      caller?.removeEventListener('abort', abortWithCaller);
+    }
+
+    request.signal = signal;
+    const result = await wait(next(request))
+      .catch((error: unknown) => {
+        done();
+        throw error;
+      })
+      .finally(() => {
+        request.signal = caller;
+      });
+    const { response } = result;
+    if (response?.body && (stream || request.options.unread)) {
+      return { ...result, response: watchedReply(response, wait, done) };
+    }
+    done();
+    return result;
+  }
+
+  return {
+    name: 'timeout',
+    onOpen: (request, next) => bounded(request, next, true),
+    onSend: (request, next) => bounded(request, next, false),
+  };
+}

package/src/internal/feature/validate.ts

@@ -0,0 +1,74 @@
+import { unreadableValue } from '../core/errors';
+import { readReply } from '../core/read-reply';
+import type { CallableDescriptor, Feature, ResolvedOptions } from '../core/types';
+
+export type Validate<TIn = unknown, TOut = TIn> = (value: TIn) => Promise<TOut> | TOut;
+
+export async function runValidator<T>(
+  validate: Validate<T, T> | undefined,
+  value: T,
+  options: ResolvedOptions,
+  response?: Response,
+): Promise<T> {
+  if (!validate || options['validate'] === false) return value;
+  return await readReply(validate, value, response);
+}
+
+export interface CallableValidators {
+  error?: Validate;
+  request?: Validate<ResolvedOptions, Partial<ResolvedOptions>>;
+  response?: Validate;
+}
+
+export function validatorsOf(callable: CallableDescriptor): CallableValidators | undefined {
+  return callable.validators as CallableValidators | undefined;
+}
+
+export function validateFeature(): Feature {
+  return {
+    name: 'validate',
+    async onOptions(options, callable) {
+      const validate = validatorsOf(callable)?.request;
+      if (!validate || options['validate'] === false) return;
+      Object.assign(options, await validate(options));
+    },
+    async onResult(result, request) {
+      const validators = validatorsOf(request.callable);
+      if (!validators) return result;
+      if (result.error !== undefined && result.error !== null) {
+        result.error = await runValidator(
+          validators.error,
+          result.error,
+          request.options,
+          result.response,
+        );
+      } else if (result.data !== undefined) {
+        result.data = await runValidator(
+          validators.response,
+          result.data,
+          request.options,
+          result.response,
+        );
+      }
+      return result;
+    },
+  };
+}
+
+export function decoded<TIn, TOut>(at: string, value: TIn, read: (value: TIn) => TOut): TOut {
+  let result: TOut;
+  try {
+    result = read(value);
+  } catch (cause) {
+    throw unreadableValue(at, value, cause);
+  }
+  if (result instanceof Date && Number.isNaN(result.getTime())) throw unreadableValue(at, value);
+  return result;
+}
+
+export function reviving<T>(revive: (value: T) => void): Validate {
+  return (data) => {
+    if (data != null) revive(data as T);
+    return data;
+  };
+}

package/src/internal/page/page.ts

@@ -0,0 +1,402 @@
+import { awaitedResult } from '../core/call-promise';
+import type { Client } from '../core/client';
+import { APIError, ElmoError } from '../core/errors';
+import { LazyPromise, unattended } from '../core/lazy-promise';
+import type {
+  CallableDescriptor,
+  ErrorMode,
+  PageEnvelope,
+  PageResult,
+  PaginationDescriptor,
+  PaginationStyle,
+  ResolvedOptions,
+  Result,
+} from '../core/types';
+
+/**
+ * One page of a paginated call. Iterating a page walks from it to the end of
+ * the collection.
+ */
+export interface Page<TItem = unknown, TBody = unknown> extends AsyncIterable<TItem> {
+  /** The whole reply body, counts and all. */
+  readonly body: TBody;
+  /** The items on this page. */
+  readonly data: ReadonlyArray<TItem>;
+  /** The next page. Throws if `hasNextPage()` is `false`. */
+  getNextPage(): Promise<Page<TItem, TBody>>;
+  /** Whether a page follows this one. It sends no request. */
+  hasNextPage(): boolean;
+  /**
+   * Where the page after this one begins, or `undefined` when none follows.
+   * Pass it back as `pageParam` to resume from here.
+   */
+  readonly nextPageParam: unknown;
+  /** The HTTP status of the reply that carried this page. */
+  readonly status: number;
+}
+
+interface Walk {
+  readonly cursor: unknown;
+  readonly descriptor: CallableDescriptor;
+  readonly options: ResolvedOptions;
+  readonly position: number;
+}
+
+function readPath(value: unknown, path: string | undefined): unknown {
+  if (!path) return value;
+  let current = value;
+  for (const key of path.split('.')) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+function readItems(data: unknown, pagination: PaginationDescriptor): ReadonlyArray<unknown> {
+  const items = readPath(data, pagination.items);
+  return Array.isArray(items) ? items : [];
+}
+
+function withPosition(
+  options: ResolvedOptions,
+  pagination: PaginationDescriptor,
+  value: unknown,
+): ResolvedOptions {
+  const name = pagination.param;
+  if (!name) return options;
+  if ((pagination.in ?? 'query') === 'body') {
+    return { ...options, body: { ...(options.body as object | undefined), [name]: value } };
+  }
+  return { ...options, query: { ...options.query, [name]: value } };
+}
+
+function resumeAt(walk: Walk, pagination: PaginationDescriptor, param: unknown): Walk {
+  if (pagination.style === 'link') {
+    const options = { ...walk.options };
+    delete options.query;
+    return { ...walk, descriptor: { ...walk.descriptor, address: param as string }, options };
+  }
+  const options = withPosition(walk.options, pagination, param);
+  if (pagination.style === 'cursor') return { ...walk, cursor: param, options };
+  return { ...walk, options, position: param as number };
+}
+
+function readCount(data: unknown, path: string | undefined): number | undefined {
+  if (!path) return undefined;
+  const value = readPath(data, path);
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined;
+  return value;
+}
+
+function startOf(pagination: PaginationDescriptor): number {
+  return pagination.start ?? (pagination.style === 'page' ? 1 : 0);
+}
+
+function stepCounted(
+  walk: Walk,
+  pagination: PaginationDescriptor,
+  result: Result,
+  count: number,
+  limit: number | undefined,
+): unknown {
+  if (!count) return undefined;
+
+  const size = readCount(result.data, pagination.size) ?? limit;
+  const position = walk.position + (pagination.style === 'page' ? 1 : size || count);
+  const start = startOf(pagination);
+
+  const pages = pagination.style === 'page' ? readCount(result.data, pagination.pages) : undefined;
+  const total = readCount(result.data, pagination.total);
+  if (pages === undefined && total === undefined && size !== undefined && count < size) {
+    return undefined;
+  }
+  if (pages !== undefined && position - start >= pages) return undefined;
+  if (total !== undefined) {
+    const read = pagination.style === 'page' ? (position - start) * (size ?? count) : position;
+    if (read >= total) return undefined;
+  }
+
+  return position;
+}
+
+type Stepper = (
+  walk: Walk,
+  pagination: PaginationDescriptor,
+  result: Result,
+  count: number,
+  limit: number | undefined,
+) => unknown;
+
+const STEPPERS: Partial<Readonly<Record<PaginationStyle, Stepper>>> = { page: stepCounted };
+
+const SCHEME_RE = /^[a-z][a-z\d+.-]*:/i;
+
+function pageURL(address: unknown): URL | undefined {
+  if (typeof address !== 'string') return undefined;
+  try {
+    const url = new URL(address, (globalThis as { location?: { href?: string } }).location?.href);
+    return url.origin === 'null' ? undefined : url;
+  } catch {
+    return undefined;
+  }
+}
+
+function followLink(client: Client, walk: Walk, link: string): string {
+  const own = pageURL(client.resolveAddress(walk.descriptor, walk.options));
+  if (!own) {
+    if (!SCHEME_RE.test(link) && !link.startsWith('//')) return link;
+    throw new ElmoError(
+      'Pagination stopped: the next page names a host, and no base URL says which host this client sends its credentials to.',
+    );
+  }
+  const target = new URL(link, own);
+  if (target.origin !== own.origin) {
+    throw new ElmoError(
+      `Pagination stopped: the next page is on ${target.origin}, and this client sends its credentials only to ${own.origin}.`,
+    );
+  }
+  return SCHEME_RE.test(link) ? link : target.href;
+}
+
+function saysMore(data: unknown, pagination: PaginationDescriptor): boolean {
+  return !pagination.more || readPath(data, pagination.more) !== false;
+}
+
+function stepWalk(
+  client: Client,
+  walk: Walk,
+  pagination: PaginationDescriptor,
+  result: Result,
+  count: number,
+  limit: number | undefined,
+): unknown {
+  const step = STEPPERS[pagination.style];
+  if (!step) {
+    throw new ElmoError(
+      `Cannot walk "${walk.descriptor.address}": this client does not page by "${pagination.style}".`,
+    );
+  }
+  if (!saysMore(result.data, pagination)) return undefined;
+  const next = step(walk, pagination, result, count, limit);
+  return pagination.style === 'link' && next !== undefined
+    ? followLink(client, walk, next as string)
+    : next;
+}
+
+async function* walkFrom<TItem>(page: Page<TItem>, maxPages: number): AsyncGenerator<TItem> {
+  let current = page;
+  for (let index = 1; ; index++) {
+    for (const item of current.data) yield item;
+    if (index >= maxPages || !current.hasNextPage()) return;
+    current = await current.getNextPage();
+  }
+}
+
+async function loadPage<TItem, TBody>(
+  client: Client,
+  walk: Walk,
+  pagination: PaginationDescriptor,
+  limit: number | undefined,
+  maxPages: number,
+): Promise<Page<TItem, TBody>> {
+  const result = (await client.call(walk.descriptor, walk.options)) as Result;
+  if (result.error !== undefined) throw result.error;
+
+  const data = readItems(result.data, pagination) as ReadonlyArray<TItem>;
+  const param = stepWalk(client, walk, pagination, result, data.length, limit);
+
+  const page: Page<TItem, TBody> = {
+    [Symbol.asyncIterator]: () => walkFrom(page, maxPages),
+    body: result.data as TBody,
+    data,
+    getNextPage: () => {
+      if (param === undefined) {
+        return Promise.reject(
+          new ElmoError(
+            `"${walk.descriptor.address}" has no page after this one. Check \`hasNextPage()\` first.`,
+          ),
+        );
+      }
+      return loadPage<TItem, TBody>(
+        client,
+        resumeAt(walk, pagination, param),
+        pagination,
+        limit,
+        maxPages,
+      );
+    },
+    hasNextPage: () => param !== undefined,
+    nextPageParam: param,
+    status: result.status as number,
+  };
+
+  return page;
+}
+
+export const DEFAULT_MAX_PAGES = 1000;
+
+function maxPagesFor(client: Client, options: ResolvedOptions): number {
+  return (options['maxPages'] ?? client.setup.defaults['maxPages'] ?? DEFAULT_MAX_PAGES) as number;
+}
+
+function openedAt(options: ResolvedOptions, pagination: PaginationDescriptor): unknown {
+  if (!pagination.param) return undefined;
+  const layer = options[pagination.in ?? 'query'] as Record<string, unknown> | undefined;
+  return layer?.[pagination.param];
+}
+
+function paginationOf(callable: CallableDescriptor): PaginationDescriptor {
+  if (callable.pagination) return callable.pagination;
+  throw new ElmoError(`"${callable.address}" is not a paged call, so it has no pages to walk.`);
+}
+
+function openWalk(callable: CallableDescriptor, options: ResolvedOptions): Walk {
+  const pagination = paginationOf(callable);
+  const opened = openedAt(options, pagination);
+  return {
+    cursor: pagination.style === 'cursor' ? opened : undefined,
+    descriptor: callable,
+    options: { ...options, raw: true },
+    position: typeof opened === 'number' && Number.isFinite(opened) ? opened : startOf(pagination),
+  };
+}
+
+function pageStream<TItem, TBody>(
+  load: () => Promise<Page<TItem, TBody>>,
+  maxPages: number,
+): AsyncIterable<Page<TItem, TBody>> {
+  return {
+    async *[Symbol.asyncIterator](): AsyncGenerator<Page<TItem, TBody>> {
+      let current = await load();
+      for (let index = 1; ; index++) {
+        yield current;
+        if (index >= maxPages || !current.hasNextPage()) return;
+        current = await current.getNextPage();
+      }
+    },
+  };
+}
+
+function requestedLimit(
+  options: ResolvedOptions,
+  pagination: PaginationDescriptor,
+): number | undefined {
+  if (!pagination.limitParam) return undefined;
+  const layer = options[pagination.in ?? 'query'] as Record<string, unknown> | undefined;
+  const limit = Number(layer?.[pagination.limitParam]);
+  return Number.isFinite(limit) && limit > 0 ? limit : undefined;
+}
+
+/**
+ * A paginated call. Awaiting it gives the first page, or its result envelope
+ * under the `'return'` error mode. Iterating it gives every item on every page,
+ * and throws on a failed page under either mode.
+ */
+export class PagePromise<
+  TItem = unknown,
+  TBody = unknown,
+  TErrors = unknown,
+  TAwaited = Page<TItem, TBody>,
+  TMode extends ErrorMode = 'throw',
+>
+  extends LazyPromise<PageResult<TAwaited, TErrors, TMode>>
+  implements AsyncIterable<TItem>
+{
+  private envelope: Promise<PageEnvelope<TAwaited, TErrors>> | undefined;
+
+  private readonly callable: CallableDescriptor;
+  private readonly client: Client;
+  private readonly limit: number | undefined;
+  private readonly maxPages: number;
+  private readonly options: ResolvedOptions;
+  private readonly pagination: PaginationDescriptor;
+  private readonly project: (page: Page<TItem, TBody>) => TAwaited;
+
+  private readonly first: Promise<Page<TItem, TBody>>;
+
+  constructor(
+    client: Client,
+    callable: CallableDescriptor,
+    options: ResolvedOptions,
+    project: (page: Page<TItem, TBody>) => TAwaited,
+  ) {
+    super();
+    this.callable = callable;
+    this.client = client;
+    this.options = options;
+    this.pagination = paginationOf(callable);
+    this.limit = requestedLimit(options, this.pagination);
+    this.maxPages = maxPagesFor(client, options);
+    this.project = project;
+    const opened = openWalk(this.callable, this.options);
+    const param = options['pageParam'];
+    this.first = unattended(
+      loadPage<TItem, TBody>(
+        this.client,
+        param === undefined ? opened : resumeAt(opened, this.pagination, param),
+        this.pagination,
+        this.limit,
+        this.maxPages,
+      ),
+    );
+  }
+
+  /** Every item, page after page, up to `maxPages`. */
+  async *[Symbol.asyncIterator](): AsyncGenerator<TItem> {
+    yield* walkFrom(await this.first, this.maxPages);
+  }
+
+  /** Every page, up to `maxPages`. */
+  iterPages(): AsyncIterable<Page<TItem, TBody>> {
+    return pageStream(() => this.first, this.maxPages);
+  }
+
+  /**
+   * The whole result envelope. A failure of the call is returned on it, not
+   * thrown. What one of your own functions throws, such as a hook, is thrown
+   * as it is.
+   */
+  result(): Promise<PageEnvelope<TAwaited, TErrors>> {
+    return (this.envelope ??= this.read());
+  }
+
+  /** The page alone, with a failure thrown rather than handed back. */
+  async unwrap(): Promise<TAwaited> {
+    const result = await this.result();
+    if (result.ok === false) throw result.error;
+    return result.data;
+  }
+
+  private async read(): Promise<PageEnvelope<TAwaited, TErrors>> {
+    try {
+      const page = await this.first;
+      return { data: this.project(page), ok: true, status: page.status };
+    } catch (error) {
+      if (!(error instanceof ElmoError)) throw error;
+      const status = error instanceof APIError ? error.status : undefined;
+      return { error, ok: false, status } as PageEnvelope<TAwaited, TErrors>;
+    }
+  }
+
+  protected override settle(): Promise<PageResult<TAwaited, TErrors, TMode>> {
+    return this.result().then((result) => awaitedResult(this.client, this.options, result));
+  }
+}
+
+export function pages<
+  TItem = unknown,
+  TBody = unknown,
+  TErrors = unknown,
+  TMode extends ErrorMode = 'throw',
+>(
+  client: Client,
+  callable: CallableDescriptor,
+  options: ResolvedOptions = {},
+): PagePromise<TItem, TBody, TErrors, Page<TItem, TBody>, TMode> {
+  return new PagePromise<TItem, TBody, TErrors, Page<TItem, TBody>, TMode>(
+    client,
+    callable,
+    options,
+    (page) => page,
+  );
+}

package/src/internal/transport/fetch.ts

@@ -0,0 +1,82 @@
+import { isStreamed } from '../core/body';
+import { safeAddress, unsendableAddress } from '../core/errors';
+import { metadataHeaders } from '../core/metadata';
+import type { PreparedRequest, Transport } from '../core/types';
+
+/** A `fetch` function, called with the full address and a built `RequestInit`. */
+export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** What `fetch` takes, less what the client sets itself. */
+export interface FetchOptions extends RequestInit {
+  /** Set by the client. */
+  body?: never;
+  /** Set by the client. Pass `headers` to the call. */
+  headers?: never;
+  /** Set by the client. */
+  method?: never;
+  /** Set by the client. Pass `signal` to the call. */
+  signal?: never;
+}
+
+function checkAddress(address: string): void {
+  let url: URL;
+  try {
+    url = new URL(address, (globalThis as { location?: { href: string } }).location?.href);
+  } catch {
+    throw unsendableAddress(
+      safeAddress(address),
+      'is not a full address',
+      'Start the base URL with `https://`.',
+    );
+  }
+  const shown = `${url.protocol}//${url.host}${url.pathname}`;
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw unsendableAddress(
+      shown,
+      `uses \`${url.protocol}\`, which fetch does not send`,
+      'Start the base URL with `https://`.',
+    );
+  }
+  if (url.username || url.password) {
+    throw unsendableAddress(
+      shown,
+      'holds a user name or password, which fetch refuses',
+      'Pass the credential as an option instead.',
+    );
+  }
+}
+
+const OWNED = ['body', 'headers', 'method', 'signal'] as const;
+
+function extraInit(request: PreparedRequest<string>): RequestInit | undefined {
+  const extra = request.options['fetchOptions'] as RequestInit | undefined;
+  if (!extra) return undefined;
+  const rest: RequestInit = { ...extra };
+  for (const key of OWNED) delete rest[key];
+  return rest;
+}
+
+function toRequestInit(request: PreparedRequest<string>): RequestInit {
+  return {
+    ...extraInit(request),
+    ...(request.body !== undefined && { body: request.body }),
+    ...(isStreamed(request.body) && { duplex: 'half' }),
+    headers: metadataHeaders(request.meta),
+    method: (request.callable.method ?? 'get').toUpperCase(),
+    ...(request.signal !== undefined && { signal: request.signal }),
+  };
+}
+
+export function createFetchTransport(fetchFn?: Fetch): Transport<string, 'unary'> {
+  function send(request: PreparedRequest<string>): Promise<Response> {
+    const configured = request.options['fetch'] as Fetch | undefined;
+    const call = configured ?? fetchFn ?? globalThis.fetch;
+    if (call === globalThis.fetch) checkAddress(request.address);
+    return call(request.address, toRequestInit(request));
+  }
+
+  return {
+    name: 'fetch',
+    unary: send,
+  };
+}