@elmohq/sdk 0.0.0-stage → 0.1.1

package/src/internal/core/browser.ts

@@ -0,0 +1,11 @@
+import { ElmoError } from './errors';
+import type { ResolvedOptions } from './types';
+
+export function refuseBrowser(options: ResolvedOptions): void {
+  if (options['dangerouslyAllowBrowser'] === true) return;
+  const scope = globalThis as { document?: unknown; window?: unknown };
+  if (scope.window === undefined || scope.document === undefined) return;
+  throw new ElmoError(
+    'This client was built in a browser, where every visitor to the page can read the credential it sends. Build it on a server instead. If the credential is meant to be public, or a proxy adds it, pass `dangerouslyAllowBrowser: true`.',
+  );
+}

package/src/internal/core/call-promise.ts

@@ -0,0 +1,145 @@
+import type { Client } from './client';
+import type { Exchange } from './dispatch';
+import { ElmoError } from './errors';
+import { LazyPromise, unattended } from './lazy-promise';
+import type {
+  CallableDescriptor,
+  CallResult,
+  ErrorMode,
+  ResolvedOptions,
+  ResultEnvelope,
+} from './types';
+
+export function awaitedResult<T>(
+  client: Client,
+  options: ResolvedOptions,
+  result: { data?: unknown; error?: unknown; ok?: boolean },
+): T {
+  if ((options.errors ?? client.setup.defaults.errors) === 'return') return result as T;
+  if (result.ok === false) throw result.error;
+  return result.data as T;
+}
+
+/** A call already sent, whose reply is not yet read. */
+export class CallPromise<
+  TResponses = unknown,
+  TErrors = unknown,
+  TMode extends ErrorMode = 'throw',
+> extends LazyPromise<CallResult<TResponses, TErrors, TMode>> {
+  protected readonly client: Client;
+  protected readonly exchange: Promise<Exchange>;
+  protected readonly options: ResolvedOptions;
+
+  private envelope: Promise<ResultEnvelope<TResponses, TErrors>> | undefined;
+
+  constructor(client: Client, callable: CallableDescriptor, options: ResolvedOptions = {}) {
+    super();
+    this.client = client;
+    this.options = options;
+    this.exchange = unattended(client.exchange(callable, { ...options, envelope: true }));
+  }
+
+  /**
+   * 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<ResultEnvelope<TResponses, TErrors>> {
+    return (this.envelope ??= this.read());
+  }
+
+  /** The payload alone, with a failure thrown rather than handed back. */
+  async unwrap(): Promise<CallResult<TResponses, TErrors, 'throw'>> {
+    const result = await this.result();
+    if (result.ok === false) throw result.error;
+    return result.data as CallResult<TResponses, TErrors, 'throw'>;
+  }
+
+  private async read(): Promise<ResultEnvelope<TResponses, TErrors>> {
+    try {
+      return await this.decode();
+    } catch (error) {
+      if (!(error instanceof ElmoError)) throw error;
+      return { error, ok: false } as ResultEnvelope<TResponses, TErrors>;
+    }
+  }
+
+  protected override settle(): Promise<CallResult<TResponses, TErrors, TMode>> {
+    return this.result().then((result) => awaitedResult(this.client, this.options, result));
+  }
+
+  protected async decode(): Promise<ResultEnvelope<TResponses, TErrors>> {
+    return (await this.exchange).read() as Promise<ResultEnvelope<TResponses, TErrors>>;
+  }
+}
+
+/** What a call resolves with where its `Response` is asked for as well. */
+export interface WithResponse<TData> {
+  /** What the call resolves with on its own. */
+  data: TData;
+  /** The request id to quote when reporting a problem with the call. */
+  requestId: string | undefined;
+  /** The `Response` that carried `data`. Its body is already read. */
+  response: Response;
+}
+
+/** A call already sent, whose `Response` can be read as well as its payload. */
+export class RestCallPromise<
+  TResponses = unknown,
+  TErrors = unknown,
+  TMode extends ErrorMode = 'throw',
+> extends CallPromise<TResponses, TErrors, TMode> {
+  private claimed = false;
+
+  private unread: Promise<Response> | undefined;
+
+  /**
+   * The `Response` itself, with its body unread and yours to read once. An
+   * error status does not throw here. A call that got no response does.
+   */
+  asResponse(): Promise<Response> {
+    return (this.unread ??= this.claim());
+  }
+
+  /** The decoded body, the `Response` that carried it, and the request id. */
+  async withResponse(): Promise<WithResponse<CallResult<TResponses, TErrors, TMode>>> {
+    const data = await (this as CallPromise<TResponses, TErrors, TMode>);
+    const exchange = await this.exchange;
+    return { data, requestId: exchange.requestId(), response: exchange.response as Response };
+  }
+
+  protected override async decode(): Promise<ResultEnvelope<TResponses, TErrors>> {
+    const exchange = await this.exchange;
+    const { response } = exchange;
+    if (!this.claimed || !response) return super.decode();
+    if (!response.bodyUsed) {
+      return exchange.read(response.clone()) as Promise<ResultEnvelope<TResponses, TErrors>>;
+    }
+    throw new ElmoError(
+      'The body of this call was already read through asResponse(). Use withResponse() instead, which gives the body and the reply from one call.',
+    );
+  }
+
+  private async claim(): Promise<Response> {
+    const { response } = await this.exchange;
+    if (!response) {
+      throw new ElmoError(
+        'This call was answered without a `Response`, so there is none to hand back.',
+      );
+    }
+    if (!response.bodyUsed) this.claimed = true;
+    return response;
+  }
+}
+
+export function callPromise<
+  TResponses = unknown,
+  TErrors = unknown,
+  TMode extends ErrorMode = 'throw',
+>(
+  client: Client,
+  callable: CallableDescriptor,
+  options: ResolvedOptions = {},
+): RestCallPromise<TResponses, TErrors, TMode> {
+  return new RestCallPromise<TResponses, TErrors, TMode>(client, callable, options);
+}

package/src/internal/core/callable.ts

@@ -0,0 +1,11 @@
+import type { CallableDescriptor, Interaction } from './types';
+
+export type CallableInput = Omit<CallableDescriptor, 'interaction'> & {
+  readonly interaction?: Interaction;
+};
+
+export function callable<T extends CallableInput>(
+  descriptor: T,
+): T & { readonly interaction: Interaction } {
+  return { interaction: 'unary', ...descriptor };
+}

package/src/internal/core/client.ts

@@ -0,0 +1,89 @@
+import { mergeConfigs, mergeDefaults } from './config';
+import { applyAliases, applyCredentials } from './credentials';
+import type { DispatchSetup, Exchange } from './dispatch';
+import { dispatch, exchange, prepare } from './dispatch';
+import { envDefaults } from './env';
+import { ElmoError } from './errors';
+import { onlyProtocol } from './protocol';
+import type {
+  CallableDescriptor,
+  CallResult,
+  ErrorMode,
+  PreparedRequest,
+  ResolvedOptions,
+} from './types';
+
+/** What every call is sent through. It holds the options all calls share. */
+export interface Client {
+  /** @internal */
+  call<TData = unknown, TError = unknown, TMode extends ErrorMode = 'throw'>(
+    callable: CallableDescriptor,
+    options?: ResolvedOptions,
+  ): Promise<CallResult<TData, TError, TMode>>;
+  /** @internal */
+  exchange(callable: CallableDescriptor, options?: ResolvedOptions): Promise<Exchange>;
+  /** @internal */
+  prepare<TAddress = unknown>(
+    callable: CallableDescriptor,
+    options?: ResolvedOptions,
+  ): Promise<PreparedRequest<TAddress>>;
+  /** @internal */
+  resolveAddress<TAddress = unknown>(
+    callable: CallableDescriptor,
+    options?: ResolvedOptions,
+  ): TAddress;
+  /** @internal */
+  readonly setup: DispatchSetup;
+}
+
+function clientOf(setup: DispatchSetup): Client {
+  const client = {
+    call<TData = unknown, TError = unknown, TMode extends ErrorMode = 'throw'>(
+      callable: CallableDescriptor,
+      options?: ResolvedOptions,
+    ): Promise<CallResult<TData, TError, TMode>> {
+      return dispatch(setup, callable, options) as Promise<CallResult<TData, TError, TMode>>;
+    },
+    exchange(callable: CallableDescriptor, options?: ResolvedOptions): Promise<Exchange> {
+      return exchange(setup, callable, options);
+    },
+    prepare<TAddress = unknown>(callable: CallableDescriptor, options: ResolvedOptions = {}) {
+      return prepare(setup, callable, options) as Promise<PreparedRequest<TAddress>>;
+    },
+    resolveAddress<TAddress = unknown>(
+      callable: CallableDescriptor,
+      options: ResolvedOptions = {},
+    ) {
+      const { binding } = onlyProtocol(setup.protocols, callable.interaction);
+      return binding.resolveAddress(callable, mergeConfigs(setup.defaults, options)) as TAddress;
+    },
+  };
+  return Object.defineProperty(client, 'setup', { value: setup }) as Client;
+}
+
+export function createClient(setup: DispatchSetup): Client {
+  return clientOf({
+    ...setup,
+    defaults: envDefaults(setup.defaults, setup.env, setup.credentials),
+  });
+}
+
+export function clientFor(
+  args: (Partial<ResolvedOptions> & { client?: Client; key?: string }) | undefined,
+  fallback?: Client,
+): Client {
+  const { client, key: _key, ...args_ } = args ?? {};
+  const base = client ?? fallback;
+  if (!base) throw new ElmoError('This SDK has no client of its own. Pass one as `client`.');
+  const config = applyCredentials(applyAliases(args_, base.setup.aliases), base.setup.credentials);
+  if (client && !Object.keys(config).length) return client;
+  const defaults = mergeDefaults(base.setup.defaults, config);
+  base.setup.guard?.(defaults);
+  return clientOf({ ...base.setup, defaults });
+}
+
+export function withClient<T extends object>(source: T, client: Client, key = 'client'): T {
+  const derived = Object.create(Object.getPrototypeOf(source)) as Record<string, Client>;
+  derived[key] = client;
+  return derived as T;
+}

package/src/internal/core/config.ts

@@ -0,0 +1,84 @@
+import { mergeMetadata } from './metadata';
+import type { ResolvedOptions } from './types';
+
+type Layers = ReadonlyArray<Partial<ResolvedOptions> | undefined>;
+
+export function foldRetry(sources: Layers, merged: ResolvedOptions): ResolvedOptions {
+  if (!sources.some((source) => source?.['retry'] !== undefined)) return merged;
+  let retry: unknown;
+  for (const source of sources) {
+    const own = source?.['retry'];
+    const count = source?.['maxRetries'];
+    const counted = typeof count === 'number' && Number.isFinite(count);
+    if (own === false) {
+      retry = false;
+    } else if (own !== undefined || counted) {
+      const rules: Record<string, unknown> = {
+        ...(typeof retry === 'object' && retry),
+        ...(typeof own === 'object' && own),
+      };
+      if (counted && (typeof own !== 'object' || !own || !('maxRetries' in own))) {
+        rules['maxRetries'] = count;
+      }
+      retry = rules;
+    }
+  }
+  merged['retry'] = retry;
+  delete merged['maxRetries'];
+  return merged;
+}
+
+const MERGED_LAYERS = ['path', 'query'] as const;
+
+export function mergeLayers(sources: Layers, merged: ResolvedOptions): ResolvedOptions {
+  for (const key of MERGED_LAYERS) {
+    const layers = sources.filter((source) => source?.[key]);
+    if (!layers.length) continue;
+    const layer: Record<string, unknown> = {};
+    for (const source of layers) {
+      for (const [name, value] of Object.entries(source![key] as Record<string, unknown>)) {
+        if (value !== undefined) layer[name] = value;
+      }
+    }
+    merged[key] = layer;
+  }
+  return merged;
+}
+
+function merge(
+  sources: ReadonlyArray<Partial<ResolvedOptions> | undefined>,
+  keepAccessors: boolean,
+): ResolvedOptions {
+  const merged: ResolvedOptions = {};
+  for (const source of sources) {
+    if (!source) continue;
+    if (keepAccessors) {
+      for (const [key, held] of Object.entries(Object.getOwnPropertyDescriptors(source))) {
+        if (held.get || held.value !== undefined) Object.defineProperty(merged, key, held);
+      }
+    } else {
+      for (const key of Object.keys(source)) {
+        const value = source[key];
+        if (value !== undefined) merged[key] = value;
+      }
+    }
+  }
+  merged.headers = mergeMetadata(...sources.map((source) => source?.headers));
+  return foldRetry(sources, mergeLayers(sources, merged));
+}
+
+export function mergeConfigs(...sources: ReadonlyArray<Partial<ResolvedOptions> | undefined>) {
+  return merge(sources, false);
+}
+
+export function createConfig(overrides: Partial<ResolvedOptions> = {}): ResolvedOptions {
+  return mergeConfigs({ errors: 'throw', headers: {} }, overrides);
+}
+
+export function baseURLOf(options: ResolvedOptions, fallback?: string): string | undefined {
+  return options.baseURL ?? fallback;
+}
+
+export function mergeDefaults(...sources: ReadonlyArray<Partial<ResolvedOptions> | undefined>) {
+  return merge(sources, true);
+}

package/src/internal/core/credentials.ts

@@ -0,0 +1,40 @@
+import type { CredentialSpec, ResolvedOptions } from './types';
+
+const LAYER_ALIASES: Readonly<Record<string, string>> = {
+  defaultHeaders: 'headers',
+  defaultPath: 'path',
+  defaultQuery: 'query',
+};
+
+export function applyAliases(
+  config: Partial<ResolvedOptions>,
+  aliases: Readonly<Record<string, string>> | undefined,
+): Partial<ResolvedOptions> {
+  let applied: Record<string, unknown> | undefined;
+  for (const [alias, canonical] of Object.entries(
+    aliases ? { ...LAYER_ALIASES, ...aliases } : LAYER_ALIASES,
+  )) {
+    if (!(alias in config)) continue;
+    applied ??= { ...config };
+    if (applied[canonical] === undefined) applied[canonical] = applied[alias];
+    delete applied[alias];
+  }
+
+  return (applied as Partial<ResolvedOptions> | undefined) ?? config;
+}
+
+export function applyCredentials(
+  config: Partial<ResolvedOptions>,
+  credentials: Readonly<Record<string, CredentialSpec>> | undefined,
+): Partial<ResolvedOptions> {
+  if (!credentials) return config;
+
+  let applied: Record<string, unknown> | undefined;
+  for (const [name, spec] of Object.entries(credentials)) {
+    if (spec.option === false || config[name] !== undefined || !(name in config)) continue;
+    applied ??= { ...config };
+    delete applied[name];
+  }
+
+  return (applied as Partial<ResolvedOptions> | undefined) ?? config;
+}

package/src/internal/core/dispatch.ts

@@ -0,0 +1,225 @@
+import { bufferReply } from './body';
+import { mergeConfigs } from './config';
+import { applyAliases, applyCredentials } from './credentials';
+import {
+  ElmoError,
+  sniffRequestId,
+  unansweredError,
+  unsendableHeader,
+  UnsupportedInteractionError,
+} from './errors';
+import { FeatureRunner } from './features';
+import { mergeMetadata, unsendableName } from './metadata';
+import type { Protocols } from './protocol';
+import { onlyProtocol } from './protocol';
+import type {
+  AnyTransport,
+  Binding,
+  CallableDescriptor,
+  Codec,
+  CredentialSpec,
+  Feature,
+  FeatureContext,
+  PreparedRequest,
+  ResolvedOptions,
+  Result,
+  Send,
+} from './types';
+import { encodeNamedBody } from '../codec/registry';
+
+export interface DispatchSetup {
+  accept?: string;
+  aliases?: Readonly<Record<string, string>>;
+  codecs: ReadonlyArray<Codec>;
+  credentials?: Readonly<Record<string, CredentialSpec>>;
+  defaults: ResolvedOptions;
+  env?: Readonly<Record<string, string>>;
+  features?: ReadonlyArray<Feature>;
+  guard?: (options: ResolvedOptions) => void;
+  protocols: Protocols;
+  transports?: (name: string) => AnyTransport;
+}
+
+export interface Exchange {
+  read(from?: Response): Promise<unknown>;
+  requestId(): string | undefined;
+  readonly response: Response | undefined;
+}
+
+interface Sent {
+  binding: Binding;
+  ctx: FeatureContext;
+  result: Result;
+  runner: FeatureRunner;
+}
+
+async function readReply(
+  setup: DispatchSetup,
+  sent: Sent,
+  request: PreparedRequest,
+  from?: Response,
+): Promise<unknown> {
+  const { binding, ctx, runner } = sent;
+
+  try {
+    const raw = from ?? sent.result.response;
+    let result =
+      request.options.unread || !raw
+        ? sent.result
+        : await binding.readResult!(raw, request, setup.codecs);
+
+    result = await runner.result(result, request, ctx);
+
+    const failure = binding.readError?.(result, request) ?? result.error;
+
+    if (request.options.raw) {
+      return failure === undefined ? result : { ...result, error: failure };
+    }
+
+    if (failure !== undefined) {
+      if (request.options.errors !== 'return' && !request.options.envelope) throw failure;
+      return {
+        data: undefined,
+        error: await runner.error(failure, request, ctx),
+        ok: false,
+        status: result.status,
+      };
+    }
+
+    return request.options.errors === 'return' || request.options.envelope
+      ? { data: result.data, error: undefined, ok: true, status: result.status }
+      : result.data;
+  } catch (error) {
+    throw await runner.error(error, request, ctx);
+  }
+}
+
+export function rejectUnsendable(transport: AnyTransport, request: PreparedRequest): never {
+  throw new UnsupportedInteractionError(transport.name, request.interaction);
+}
+
+function shellOf(request: PreparedRequest): PreparedRequest {
+  if (request.options.unread) return request;
+  return { ...request, options: { ...request.options, unread: true } };
+}
+
+function transportFor(setup: DispatchSetup, named: unknown, fallback: AnyTransport): AnyTransport {
+  if (named === undefined) return fallback;
+  if (typeof named !== 'string') return named as AnyTransport;
+  const found = setup.transports?.(named);
+  if (!found) throw new ElmoError(`This client carries no transport named "${named}".`);
+  return found;
+}
+
+async function sendRequest(setup: DispatchSetup, request: PreparedRequest): Promise<Sent> {
+  const protocol = onlyProtocol(setup.protocols, request.interaction);
+  const { binding } = protocol;
+  const transport = transportFor(setup, request.options['transport'], protocol.transport);
+  const runner = new FeatureRunner(setup.features);
+  const ctx = { binding, transport };
+
+  const { unary } = transport;
+  if (request.interaction !== 'unary' || !unary) rejectUnsendable(transport, request);
+
+  try {
+    if (!binding.readResult) {
+      throw new ElmoError(
+        `The "${binding.name}" binding reads no reply, so it cannot answer this call.`,
+      );
+    }
+
+    const send: Send = async (attempt) => {
+      await runner.request(attempt, ctx);
+      const unsendable = unsendableName(attempt.meta);
+      if (unsendable !== undefined) throw unsendableHeader(unsendable);
+      attempt.log?.sending();
+      let raw: Response;
+      try {
+        raw = await unary.call(transport, attempt);
+        if (!request.options.unread) raw = await bufferReply(raw, attempt.signal);
+      } catch (error) {
+        throw unansweredError(error);
+      }
+      return binding.readResult!(raw, shellOf(attempt), setup.codecs);
+    };
+
+    return { binding, ctx, result: await runner.send(send, ctx)(request), runner };
+  } catch (error) {
+    throw await runner.error(error, request, ctx);
+  }
+}
+
+export async function execute(setup: DispatchSetup, request: PreparedRequest): Promise<unknown> {
+  return readReply(setup, await sendRequest(setup, request), request);
+}
+
+export function buildRequestWithoutCookies(
+  setup: DispatchSetup,
+  callable: CallableDescriptor,
+  resolved: ResolvedOptions,
+): PreparedRequest {
+  const interaction = callable.interaction ?? 'unary';
+  const { binding } = onlyProtocol(setup.protocols, interaction);
+  const encoded = encodeNamedBody(setup.codecs, callable.mediaType, resolved);
+  const meta = mergeMetadata(resolved.headers);
+  if (encoded?.contentType && meta['content-type'] === undefined) {
+    meta['content-type'] = encoded.contentType;
+  }
+
+  const accept = callable.accept ?? setup.accept ?? binding.accept;
+  if (accept && meta['accept'] === undefined) meta['accept'] = accept;
+
+  return {
+    address: binding.resolveAddress(callable, resolved),
+    body: encoded?.payload,
+    callable,
+    interaction,
+    meta,
+    options: resolved,
+    signal: resolved.signal,
+  };
+}
+
+export async function prepare<TAddress = unknown>(
+  setup: DispatchSetup,
+  callable: CallableDescriptor,
+  options: ResolvedOptions = {},
+): Promise<PreparedRequest<TAddress>> {
+  const { binding, transport } = onlyProtocol(setup.protocols, callable.interaction);
+  const resolved = mergeConfigs(
+    setup.defaults,
+    applyCredentials(applyAliases(options, setup.aliases), setup.credentials),
+  );
+  const runner = new FeatureRunner(setup.features);
+  const ctx = { binding, transport };
+
+  await runner.options(resolved, callable, ctx);
+
+  const request = buildRequestWithoutCookies(setup, callable, resolved);
+
+  await runner.prepare(request, ctx);
+  return request as PreparedRequest<TAddress>;
+}
+
+export async function dispatch(
+  setup: DispatchSetup,
+  callable: CallableDescriptor,
+  options: ResolvedOptions = {},
+): Promise<unknown> {
+  return execute(setup, await prepare(setup, callable, options));
+}
+
+export async function exchange(
+  setup: DispatchSetup,
+  callable: CallableDescriptor,
+  options: ResolvedOptions = {},
+): Promise<Exchange> {
+  const request = await prepare(setup, callable, options);
+  const sent = await sendRequest(setup, request);
+  let read: Promise<unknown> | undefined;
+  return {
+    read: (from) => (read ??= readReply(setup, sent, request, from)),
+    requestId: () => sent.result.response && sniffRequestId(sent.result.response),
+    response: sent.result.response,
+  };
+}

package/src/internal/core/env.ts

@@ -0,0 +1,68 @@
+import type { CredentialSpec, ResolvedOptions } from './types';
+
+export function impliedEnvironment(..._tokens: ReadonlyArray<unknown>): undefined {
+  return undefined;
+}
+
+export function readEnv(name: string): string | undefined {
+  const global = globalThis as {
+    Deno?: { env?: { get?: (name: string) => string | undefined } };
+    process?: { env?: Record<string, string | undefined> };
+  };
+  const value = global.process?.env?.[name] ?? global.Deno?.env?.get?.(name);
+  return value?.trim() || undefined;
+}
+
+function readable(credentials: Readonly<Record<string, CredentialSpec>>): ReadonlyArray<string> {
+  return Object.keys(credentials).filter(
+    (name) => credentials[name]!.variable && credentials[name]!.option !== false,
+  );
+}
+
+export function envDefaults(
+  base: ResolvedOptions,
+  env: Readonly<Record<string, string>> = {},
+  credentials: Readonly<Record<string, CredentialSpec>> = {},
+): ResolvedOptions {
+  const reads = new WeakMap<object, ResolvedOptions>();
+  const held = readable(credentials);
+
+  function resolve(): ResolvedOptions {
+    const read: ResolvedOptions = {};
+    for (const [option, variable] of Object.entries(env)) {
+      const value = readEnv(variable) ?? base[option];
+      if (value !== undefined) read[option] = value;
+    }
+    if (held.length) {
+      const tokens: Record<string, string | undefined> = {};
+      for (const name of held) tokens[name] = readEnv(credentials[name]!.variable!);
+      Object.assign(read, tokens);
+      const environment = impliedEnvironment(tokens, credentials) ?? base.environment;
+      if (environment !== undefined) read.environment = environment;
+    }
+    return read;
+  }
+
+  function resolvedFor(holder: object): ResolvedOptions {
+    let read = reads.get(holder);
+    if (!read) {
+      read = resolve();
+      reads.set(holder, read);
+    }
+    return read;
+  }
+
+  const decided = [...Object.keys(env), ...held, ...(held.length ? ['environment'] : [])];
+
+  const defaults = { ...base };
+  for (const key of decided) {
+    Object.defineProperty(defaults, key, {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return resolvedFor(this as object)[key];
+      },
+    });
+  }
+  return defaults;
+}