backd-js 0.1.15 → 0.3.0

package/src/data.js

@@ -0,0 +1,293 @@
+import { Job } from './functions.js'
+
+/**
+ * @typedef {import('./client.js').Client} Client
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./functions.js').JobData} JobData
+ */
+
+/**
+ * Server-owned fields of a document.
+ * @typedef {object} Meta
+ * @property {string} created_at   RFC3339 timestamp.
+ * @property {string} updated_at   RFC3339 timestamp.
+ * @property {number} [version]    Increases on every write; missing only on very old documents.
+ * @property {string | null} [owner]  Id of the user who created it (realms with auth enabled).
+ * @property {string} [created_by] `user:<id>`, `key:<name>` or `anonymous`.
+ * @property {string} [updated_by] `user:<id>`, `key:<name>` or `anonymous`.
+ */
+
+/**
+ * A stored document: the collection's fields plus `id` and `_meta`.
+ * @template {object} [T=Record<string, any>]
+ * @typedef {T & { id: string, _meta: Meta }} Doc
+ */
+
+/**
+ * @typedef {object} ListParams
+ * @property {object | string} [where]      Filter in backd's query language, e.g. `{ price: { $lt: 20 } }`
+ *   or `{ $or: [{ title: { $icontains: 'go' } }, { body: { $icontains: 'go' } }] }`.
+ * @property {string | string[]} [orderBy]  Fields, `-` prefix for descending, e.g. `'-_meta.created_at'`.
+ * @property {number} [limit]               1–100; default 20.
+ * @property {number} [skip]
+ * @property {string} [after]               The `next_cursor` of the previous page: continues the list after it
+ *   (same `where` and `orderBy`). Can't be combined with `skip`.
+ * @property {boolean} [count]              Also return `total`.
+ */
+
+/**
+ * A page of documents, as the API returns it.
+ * @template {object} [T=Record<string, any>]
+ * @typedef {object} Page
+ * @property {Doc<T>[]} items
+ * @property {number} limit
+ * @property {number} skip
+ * @property {boolean} has_more
+ * @property {string} [next_cursor]   With `has_more`: pass it as `after` to get the next page. Absent when the
+ *   `orderBy` can't be followed by a cursor (arrays, objects, mixed types): use `skip` then.
+ * @property {number} [total]   With `count: true`; counts the whole list, not what is after `after`.
+ */
+
+/**
+ * Options for writes. `ifMatch` makes the write fail with a
+ * VersionMismatchError unless the document is still at that version.
+ * @typedef {RequestOptions & { ifMatch?: number | string }} WriteOptions
+ */
+
+/**
+ * One write for `db.batch(...)`, applied atomically with the others.
+ * `create` and `replace` need `document`; `patch` needs `patch` (a JSON
+ * Merge Patch). `replace`, `patch` and `delete` need `id`, and accept
+ * `ifMatch` (like `WriteOptions`).
+ * @typedef {object} BatchOperation
+ * @property {'create' | 'replace' | 'patch' | 'delete'} op
+ * @property {string} collection
+ * @property {string} [id]
+ * @property {Record<string, any>} [document]
+ * @property {Record<string, any>} [patch]
+ * @property {number | string} [ifMatch]
+ */
+
+/** A database of the realm: `client.db(name)`. */
+export class Database {
+  /**
+   * @param {Client} client
+   * @param {string} name
+   */
+  constructor(client, name) {
+    /** @internal */
+    this.client = client
+    /** @readonly */
+    this.name = name
+  }
+
+  /**
+   * A collection of this database.
+   * @template {object} [T=Record<string, any>]
+   * @param {string} name
+   * @returns {Collection<T>}
+   */
+  collection(name) {
+    return new Collection(this.client, this.name, name)
+  }
+
+  /**
+   * Creates, replaces, patches and deletes documents across this
+   * database's collections in one MongoDB transaction: either every
+   * operation applies, or none does (up to 100 operations). Rejects with
+   * a `BackdError` naming the first operation that failed; a version
+   * mismatch (`ifMatch`) is a `VersionMismatchError`, same as a single
+   * write.
+   * @param {BatchOperation[]} operations
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<(Doc | { id: string })[]>} one entry per operation, in order
+   */
+  async batch(operations, opts) {
+    const body = {
+      operations: operations.map(({ ifMatch, ...op }) => (ifMatch === undefined ? op : { ...op, if_match: ifMatchValue(ifMatch) })),
+    }
+    const { data } = await this.client.request({ method: 'POST', path: [this.name, '_batch'], body, ...opts })
+    return data.results
+  }
+
+  /**
+   * Calls a function. Returns its output directly for a `sync`
+   * function; for `async`, a `Job` handle to poll instead of the
+   * output (`job.status()`, or `job.wait()` for the output). A
+   * function's own error (`ctx.error(status, code, message)`) arrives
+   * as a `BackdError` with that status and code — for `async`, only
+   * once `job.wait()` resolves, not from this call itself.
+   *
+   * `webhook` functions can't be called through this method: their
+   * caller is whatever service sends the webhook, never this client.
+   * @param {string} name
+   * @param {unknown} [input] Any JSON value; omitted is sent as `null`.
+   * @param {RequestOptions & { idempotencyKey?: string }} [opts]
+   * @returns {Promise<unknown | Job>}
+   */
+  async fn(name, input, opts = {}) {
+    const { idempotencyKey, headers, ...rest } = opts
+    const reqHeaders = idempotencyKey === undefined ? headers : { ...headers, 'Idempotency-Key': idempotencyKey }
+    const { status, data } = await this.client.request({
+      method: 'POST',
+      path: [this.name, '_func', name],
+      body: input === undefined ? null : input,
+      headers: reqHeaders,
+      ...rest,
+    })
+    if (status === 202) return new Job(this.client, this.name, /** @type {JobData} */ (data))
+    return data
+  }
+}
+
+/**
+ * A collection: `client.db(db).collection(name)`. `T` describes the
+ * documents' own fields.
+ * @template {object} [T=Record<string, any>]
+ */
+export class Collection {
+  /**
+   * @param {Client} client
+   * @param {string} database
+   * @param {string} name
+   */
+  constructor(client, database, name) {
+    /** @internal */
+    this.client = client
+    /** @internal */
+    this.path = [database, name]
+  }
+
+  /**
+   * One page of documents the caller may read.
+   * @param {ListParams} [params]
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<Page<T>>}
+   */
+  async list(params = {}, opts) {
+    const { data } = await this.client.request({ method: 'GET', path: this.path, query: listQuery(params), ...opts })
+    return data
+  }
+
+  /**
+   * Every matching document, fetching pages as needed:
+   * `for await (const doc of posts.iterate({ where }))`. Pages follow a
+   * cursor (`next_cursor`), so documents created, changed or deleted
+   * meanwhile never shift a page, and it is as fast at the end as at the
+   * start. An `orderBy` on arrays, objects or mixed types has no cursor:
+   * those lists are fetched by offset instead, where documents created or
+   * deleted meanwhile can be skipped or repeated.
+   * @param {Omit<ListParams, 'skip' | 'count'>} [params] `limit` is the page size (default 100).
+   * @param {RequestOptions} [opts]
+   * @returns {AsyncGenerator<Doc<T>, void, undefined>}
+   */
+  async *iterate(params = {}, opts) {
+    const limit = params.limit ?? 100
+    let after = params.after
+    for (let skip = 0; ; skip += limit) {
+      // With a cursor the next request carries it; without one, the offset.
+      const page = await this.list(after === undefined ? { ...params, limit, skip } : { ...params, limit, after }, opts)
+      yield* page.items
+      if (!page.has_more) return
+      if (page.next_cursor === undefined) {
+        if (after !== undefined) throw new Error('backd: the list has no next_cursor to continue after')
+      } else {
+        after = page.next_cursor
+      }
+    }
+  }
+
+  /**
+   * One document; NotFoundError if it doesn't exist or the caller may not read it.
+   * @param {string} id
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<Doc<T>>}
+   */
+  async get(id, opts) {
+    return (await this.client.request({ method: 'GET', path: [...this.path, id], ...opts })).data
+  }
+
+  /**
+   * Creates a document. `id` and `_meta` are set by the server.
+   * @param {T} doc
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<Doc<T>>}
+   */
+  async create(doc, opts) {
+    return (await this.client.request({ method: 'POST', path: this.path, body: doc, ...opts })).data
+  }
+
+  /**
+   * Replaces the whole document: fields not in `doc` are removed.
+   * @param {string} id
+   * @param {T} doc
+   * @param {WriteOptions} [opts]
+   * @returns {Promise<Doc<T>>}
+   */
+  async replace(id, doc, opts = {}) {
+    return (await this.client.request({ method: 'PUT', path: [...this.path, id], body: doc, ...write(opts) })).data
+  }
+
+  /**
+   * Updates some fields (JSON Merge Patch): fields in `patch` are set,
+   * nested objects are merged, and `null` removes a field.
+   * @param {string} id
+   * @param {Partial<T> | Record<string, unknown>} patch
+   * @param {WriteOptions} [opts]
+   * @returns {Promise<Doc<T>>}
+   */
+  async patch(id, patch, opts = {}) {
+    return (
+      await this.client.request({
+        method: 'PATCH',
+        path: [...this.path, id],
+        body: patch,
+        contentType: 'application/merge-patch+json',
+        ...write(opts),
+      })
+    ).data
+  }
+
+  /**
+   * Deletes a document.
+   * @param {string} id
+   * @param {WriteOptions} [opts]
+   * @returns {Promise<void>}
+   */
+  async delete(id, opts = {}) {
+    await this.client.request({ method: 'DELETE', path: [...this.path, id], ...write(opts) })
+  }
+}
+
+/**
+ * @param {ListParams} p
+ * @returns {Record<string, string | number | boolean | undefined>}
+ */
+function listQuery(p) {
+  return {
+    where: p.where === undefined ? undefined : typeof p.where === 'string' ? p.where : JSON.stringify(p.where),
+    order_by: Array.isArray(p.orderBy) ? p.orderBy.join(',') : p.orderBy,
+    limit: p.limit,
+    skip: p.skip,
+    after: p.after,
+    count: p.count || undefined,
+  }
+}
+
+/**
+ * Turns `ifMatch` into an If-Match header.
+ * @param {WriteOptions} opts
+ * @returns {RequestOptions}
+ */
+function write({ ifMatch, ...opts }) {
+  if (ifMatch === undefined) return opts
+  return { ...opts, headers: { ...opts.headers, 'If-Match': ifMatchValue(ifMatch) } }
+}
+
+/**
+ * `3` → `"3"`; strings (`*`, `"3"`, `"2", "3"`) are sent as given.
+ * @param {number | string} v
+ */
+export function ifMatchValue(v) {
+  return typeof v === 'number' ? `"${v}"` : v
+}

package/src/errors.js

@@ -0,0 +1,135 @@
+/**
+ * @typedef {object} ErrorDetail
+ * @property {string} path   Field or parameter the problem is about.
+ * @property {string} reason What's wrong with it.
+ */
+
+/**
+ * An error answered by backd, or a network failure (status 0).
+ * `code` is stable and meant for programs; `message` is for humans.
+ */
+export class BackdError extends Error {
+  /**
+   * @param {object} init
+   * @param {number} init.status      HTTP status; 0 for network failures.
+   * @param {string} init.code        backd error code, e.g. "validation_error".
+   * @param {string} init.message
+   * @param {ErrorDetail[]} [init.details]
+   * @param {string} [init.requestId] The request ID, to match server logs.
+   * @param {unknown} [init.cause]
+   */
+  constructor({ status, code, message, details = [], requestId, cause }) {
+    super(message, cause === undefined ? undefined : { cause })
+    this.name = new.target.name
+    /** @type {number} */
+    this.status = status
+    /** @type {string} */
+    this.code = code
+    /** @type {ErrorDetail[]} */
+    this.details = details
+    /** @type {string | undefined} */
+    this.requestId = requestId
+  }
+}
+
+/** 400: invalid body, query or header (`validation_error`, `invalid_json`, `invalid_query`, `invalid_header`). */
+export class ValidationError extends BackdError {}
+
+/** 401: missing, invalid or expired credentials, or a wrong email or password. */
+export class AuthenticationError extends BackdError {}
+
+/** 403: the caller isn't allowed to do this. */
+export class ForbiddenError extends BackdError {}
+
+/**
+ * Not an HTTP error: a sign-up in a realm that requires verified addresses
+ * answers `202`, because the account exists but there is no session. Thrown
+ * by `auth.signup()` so the code after it, which expects a session, doesn't run.
+ */
+export class VerificationRequiredError extends BackdError {}
+
+/** 404: unknown realm, collection, document, user or session. */
+export class NotFoundError extends BackdError {}
+
+/** 409: a unique value already exists (`conflict`, `email_taken`) or concurrent writes (`write_conflict`). */
+export class ConflictError extends BackdError {}
+
+/** 412: `If-Match` didn't match the current version. */
+export class VersionMismatchError extends BackdError {}
+
+/** 429 and 503: try again later; `retryAfter` is in milliseconds when the server said. */
+export class RetryableError extends BackdError {
+  /**
+   * @param {ConstructorParameters<typeof BackdError>[0] & { retryAfter?: number }} init
+   */
+  constructor(init) {
+    super(init)
+    /** @type {number | undefined} */
+    this.retryAfter = init.retryAfter
+  }
+}
+
+/** 0: the request didn't get an answer (network error, abort, timeout). */
+export class NetworkError extends BackdError {}
+
+/** @type {Record<number, typeof BackdError>} */
+const byStatus = {
+  400: ValidationError,
+  401: AuthenticationError,
+  403: ForbiddenError,
+  404: NotFoundError,
+  409: ConflictError,
+  412: VersionMismatchError,
+  429: RetryableError,
+  503: RetryableError,
+}
+
+/**
+ * The `BackdError` subclass for a status, or the base class if there's
+ * no specific one for it. Used for real responses (`errorFromResponse`)
+ * and to reconstruct the same shape from an async job's stored result,
+ * which never went through an HTTP response of its own (roadmap F14).
+ * @param {number} status
+ * @returns {typeof BackdError}
+ */
+export function errorClassFor(status) {
+  return byStatus[status] ?? BackdError
+}
+
+/**
+ * Builds the error for a non-2xx response.
+ * @param {Response} res
+ * @returns {Promise<BackdError>}
+ */
+export async function errorFromResponse(res) {
+  /** @type {{ error?: { code?: string, message?: string, details?: ErrorDetail[], request_id?: string } }} */
+  let body = {}
+  try {
+    body = await res.json()
+  } catch {
+    // Not JSON (for example from a proxy): keep the defaults below.
+  }
+  const e = body.error ?? {}
+  const Class = errorClassFor(res.status)
+  const retryAfter = parseRetryAfter(res.headers.get('Retry-After'))
+  return new Class({
+    status: res.status,
+    code: e.code ?? 'http_' + res.status,
+    message: e.message ?? res.statusText ?? 'request failed',
+    details: e.details ?? [],
+    requestId: e.request_id ?? res.headers.get('X-Request-ID') ?? undefined,
+    ...(Class === RetryableError ? { retryAfter } : {}),
+  })
+}
+
+/**
+ * Parses a Retry-After header (seconds or an HTTP date) into milliseconds.
+ * @param {string | null} value
+ * @returns {number | undefined}
+ */
+export function parseRetryAfter(value) {
+  if (!value) return undefined
+  if (/^\d+$/.test(value)) return Number(value) * 1000
+  const at = Date.parse(value)
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now())
+}

package/src/functions.js

@@ -0,0 +1,143 @@
+import { errorClassFor } from './errors.js'
+
+/**
+ * @typedef {import('./client.js').Client} Client
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./errors.js').ErrorDetail} ErrorDetail
+ */
+
+/**
+ * How an `async` job ended, once `status` is `'done'` — the same shape
+ * a `sync` call's own answer would carry for the same outcome.
+ * @typedef {object} JobResult
+ * @property {string} status `ok`, `function_error`, `timeout`, `memory`, `cpu`, `crash`, `output_too_large` or `bundle`.
+ * @property {unknown} [output]     The function's output, when `status` is `ok`.
+ * @property {number} [http_status] The status a `sync` call would have answered with; absent only when `status` is `ok`.
+ * @property {string} [code]        The function's own code (`function_error`) or one of backd's own; absent only when `status` is `ok`.
+ * @property {string} [message]     Absent only when `status` is `ok`.
+ * @property {ErrorDetail[]} [details]
+ * @property {number} duration_ms
+ */
+
+/**
+ * A job as the API returns it: `POST .../_func/{name}`'s `202` body, or `GET .../_jobs/{id}`.
+ * @typedef {object} JobData
+ * @property {string} id
+ * @property {string} function `<database>/<name>`.
+ * @property {'queued' | 'running' | 'done'} status
+ * @property {string} created_at
+ * @property {number} [attempts] How many times a worker has started it.
+ * @property {string | null} [next_attempt_at] When a failed attempt will be retried (the function's `retry` policy); null otherwise.
+ * @property {JobResult | null} result
+ */
+
+/**
+ * `job.wait()` gave up before the job finished (roadmap F14) — the job
+ * itself is unaffected and still running; call `wait()` again, or poll
+ * with `status()`, whenever you like.
+ */
+export class JobTimeoutError extends Error {
+  /** @param {string} jobId */
+  constructor(jobId) {
+    super(`job ${jobId} did not finish within the given timeout`)
+    this.name = 'JobTimeoutError'
+    /** @readonly */
+    this.jobId = jobId
+  }
+}
+
+/**
+ * A handle to an `async` function's job (roadmap F11, this client since
+ * F14): `db.fn(name, input)` returns one instead of the output directly
+ * when the function is `async`. Poll with `status()`, or use `wait()`
+ * to get the output the same way a `sync` call's return value works.
+ */
+export class Job {
+  /**
+   * @param {Client} client
+   * @param {string} database
+   * @param {JobData} data
+   */
+  constructor(client, database, data) {
+    /** @internal */
+    this.client = client
+    /** @internal */
+    this.database = database
+    /** @readonly */
+    this.id = data.id
+    /** @readonly The function this job runs, as `<database>/<name>`. */
+    this.function = data.function
+    /** @internal */
+    this.data = data
+  }
+
+  /** The job's data as of the last `status()` or `wait()` call, or when it was created. */
+  get raw() {
+    return this.data
+  }
+
+  /**
+   * Polls the job's current status.
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<'queued' | 'running' | 'done'>}
+   */
+  async status(opts) {
+    this.data = await this._fetch(opts)
+    return this.data.status
+  }
+
+  /**
+   * Polls until the job is done, then returns its output — the same
+   * value a `sync` call would have returned — or throws a `BackdError`
+   * matching what a `sync` call would have thrown for the same outcome
+   * (the function's own `code`, when it threw `ctx.error(...)`).
+   * @param {RequestOptions & { pollIntervalMs?: number, timeoutMs?: number }} [opts]
+   *   `pollIntervalMs` default 500. Without `timeoutMs`, waits indefinitely.
+   * @returns {Promise<unknown>}
+   */
+  async wait(opts = {}) {
+    const { pollIntervalMs = 500, timeoutMs, ...rest } = opts
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs
+    for (;;) {
+      this.data = await this._fetch(rest)
+      if (this.data.status === 'done') return outputOrThrow(this.data.result, this.id)
+      if (deadline !== undefined && Date.now() >= deadline) throw new JobTimeoutError(this.id)
+      await sleep(pollIntervalMs)
+    }
+  }
+
+  /**
+   * @internal
+   * @param {RequestOptions} [opts]
+   * @returns {Promise<JobData>}
+   */
+  async _fetch(opts) {
+    const { data } = await this.client.request({ method: 'GET', path: [this.database, '_jobs', this.id], ...opts })
+    return data
+  }
+}
+
+/**
+ * @param {JobResult | null} result
+ * @param {string} jobId
+ * @returns {unknown}
+ */
+function outputOrThrow(result, jobId) {
+  if (!result) throw new Error(`job ${jobId} is done but has no result`)
+  if (result.status === 'ok') return result.output
+  const Class = errorClassFor(result.http_status ?? 500)
+  throw new Class({
+    status: result.http_status ?? 500,
+    code: result.code ?? 'function_failed',
+    message: result.message ?? 'the function failed',
+    details: result.details ?? [],
+  })
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/index.js

@@ -0,0 +1,51 @@
+export { createClient, Client } from './client.js'
+export { Auth } from './auth.js'
+export { Database, Collection, ifMatchValue } from './data.js'
+export { Admin } from './admin.js'
+export { Job, JobTimeoutError } from './functions.js'
+export {
+  BackdError,
+  ValidationError,
+  AuthenticationError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  VersionMismatchError,
+  RetryableError,
+  NetworkError,
+  VerificationRequiredError,
+} from './errors.js'
+export { memoryStorage, localStorageStorage } from './storage.js'
+
+/**
+ * @typedef {import('./client.js').ClientOptions} ClientOptions
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./client.js').RetryOptions} RetryOptions
+ * @typedef {import('./storage.js').TokenStorage} TokenStorage
+ * @typedef {import('./auth.js').User} User
+ * @typedef {import('./auth.js').Session} Session
+ * @typedef {import('./auth.js').SessionInfo} SessionInfo
+ * @typedef {import('./auth.js').AuthEvent} AuthEvent
+ * @typedef {import('./errors.js').ErrorDetail} ErrorDetail
+ * @typedef {import('./data.js').Meta} Meta
+ * @typedef {import('./data.js').ListParams} ListParams
+ * @typedef {import('./data.js').WriteOptions} WriteOptions
+ * @typedef {import('./admin.js').AdminUser} AdminUser
+ * @typedef {import('./admin.js').UserPage} UserPage
+ * @typedef {import('./admin.js').Invitation} Invitation
+ * @typedef {import('./admin.js').NewInvitation} NewInvitation
+ * @typedef {import('./admin.js').SentInvitation} SentInvitation
+ * @typedef {import('./admin.js').OwnedReport} OwnedReport
+ * @typedef {import('./functions.js').JobData} JobData
+ * @typedef {import('./functions.js').JobResult} JobResult
+ */
+
+/**
+ * @template {object} [T=Record<string, any>]
+ * @typedef {import('./data.js').Doc<T>} Doc
+ */
+
+/**
+ * @template {object} [T=Record<string, any>]
+ * @typedef {import('./data.js').Page<T>} Page
+ */

package/src/storage.js

@@ -0,0 +1,43 @@
+/**
+ * Where the client keeps the session token. Methods may be async.
+ * @typedef {object} TokenStorage
+ * @property {() => string | null | undefined | Promise<string | null | undefined>} get
+ * @property {(token: string) => void | Promise<void>} set
+ * @property {() => void | Promise<void>} remove
+ */
+
+/**
+ * Keeps the token in memory: it is lost on reload, and scripts on the page
+ * can't read it from storage. The default.
+ * @returns {TokenStorage}
+ */
+export function memoryStorage() {
+  /** @type {string | null} */
+  let token = null
+  return {
+    get: () => token,
+    set: (t) => {
+      token = t
+    },
+    remove: () => {
+      token = null
+    },
+  }
+}
+
+/**
+ * Keeps the token in `localStorage`, so sessions survive reloads. Any
+ * script running on the page (including injected ones) can read it:
+ * protect the app against cross-site scripting.
+ * @param {string} [key] Storage key; defaults to "backd.session".
+ * @returns {TokenStorage}
+ */
+export function localStorageStorage(key = 'backd.session') {
+  const ls = globalThis.localStorage
+  if (!ls) throw new Error('localStorage is not available in this runtime')
+  return {
+    get: () => ls.getItem(key),
+    set: (t) => ls.setItem(key, t),
+    remove: () => ls.removeItem(key),
+  }
+}