backd-js 0.1.15 → 0.2.0

package/types/errors.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @typedef {object} ErrorDetail
+ * @property {string} path   Field or parameter the problem is about.
+ * @property {string} reason What's wrong with it.
+ */
+export type ErrorDetail = {
+    /**
+     * Field or parameter the problem is about.
+     */
+    path: string;
+    /**
+     * What's wrong with it.
+     */
+    reason: string;
+};
+/**
+ * An error answered by backd, or a network failure (status 0).
+ * `code` is stable and meant for programs; `message` is for humans.
+ */
+export declare class BackdError extends Error {
+    /** @type {number} */
+    status: number;
+    /** @type {string} */
+    code: string;
+    /** @type {ErrorDetail[]} */
+    details: ErrorDetail[];
+    /** @type {string | undefined} */
+    requestId: string | undefined;
+    /**
+     * @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 }: {
+        status: number;
+        code: string;
+        message: string;
+        details?: ErrorDetail[];
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** 400: invalid body, query or header (`validation_error`, `invalid_json`, `invalid_query`, `invalid_header`). */
+export declare class ValidationError extends BackdError {
+}
+/** 401: missing, invalid or expired credentials, or a wrong email or password. */
+export declare class AuthenticationError extends BackdError {
+}
+/** 403: the caller isn't allowed to do this. */
+export declare 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 declare class VerificationRequiredError extends BackdError {
+}
+/** 404: unknown realm, collection, document, user or session. */
+export declare class NotFoundError extends BackdError {
+}
+/** 409: a unique value already exists (`conflict`, `email_taken`) or concurrent writes (`write_conflict`). */
+export declare class ConflictError extends BackdError {
+}
+/** 412: `If-Match` didn't match the current version. */
+export declare class VersionMismatchError extends BackdError {
+}
+/** 429 and 503: try again later; `retryAfter` is in milliseconds when the server said. */
+export declare class RetryableError extends BackdError {
+    /** @type {number | undefined} */
+    retryAfter: number | undefined;
+    /**
+     * @param {ConstructorParameters<typeof BackdError>[0] & { retryAfter?: number }} init
+     */
+    constructor(init: ConstructorParameters<typeof BackdError>[0] & {
+        retryAfter?: number;
+    });
+}
+/** 0: the request didn't get an answer (network error, abort, timeout). */
+export declare class NetworkError extends BackdError {
+}
+/**
+ * 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 declare function errorClassFor(status: number): typeof BackdError;
+/**
+ * Builds the error for a non-2xx response.
+ * @param {Response} res
+ * @returns {Promise<BackdError>}
+ */
+export declare function errorFromResponse(res: Response): Promise<BackdError>;
+/**
+ * Parses a Retry-After header (seconds or an HTTP date) into milliseconds.
+ * @param {string | null} value
+ * @returns {number | undefined}
+ */
+export declare function parseRetryAfter(value: string | null): number | undefined;

package/types/functions.d.ts

@@ -0,0 +1,135 @@
+export type Client = import('./client.js').Client;
+export type RequestOptions = import('./client.js').RequestOptions;
+export type ErrorDetail = import('./errors.js').ErrorDetail;
+export type JobResult = {
+    /**
+     * `ok`, `function_error`, `timeout`, `memory`, `cpu`, `crash`, `output_too_large` or `bundle`.
+     */
+    status: string;
+    /**
+     * The function's output, when `status` is `ok`.
+     */
+    output?: unknown;
+    /**
+     * The status a `sync` call would have answered with; absent only when `status` is `ok`.
+     */
+    http_status?: number;
+    /**
+     * The function's own code (`function_error`) or one of backd's own; absent only when `status` is `ok`.
+     */
+    code?: string;
+    /**
+     * Absent only when `status` is `ok`.
+     */
+    message?: string;
+    details?: ErrorDetail[];
+    duration_ms: number;
+};
+export type JobData = {
+    id: string;
+    /**
+     * `<database>/<name>`.
+     */
+    function: string;
+    status: 'queued' | 'running' | 'done';
+    created_at: string;
+    /**
+     * How many times a worker has started it.
+     */
+    attempts?: number;
+    /**
+     * When a failed attempt will be retried (the function's `retry` policy); null otherwise.
+     */
+    next_attempt_at?: string | null;
+    result: JobResult | null;
+};
+/**
+ * @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 declare class JobTimeoutError extends Error {
+    /** @readonly */
+    jobId: string;
+    /** @param {string} jobId */
+    constructor(jobId: string);
+}
+/**
+ * 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 declare class Job {
+    /** @internal */
+    client: import("./client.js").Client;
+    /** @internal */
+    database: string;
+    /** @readonly */
+    id: string;
+    /** @readonly The function this job runs, as `<database>/<name>`. */
+    function: string;
+    /** @internal */
+    data: JobData;
+    /**
+     * @param {Client} client
+     * @param {string} database
+     * @param {JobData} data
+     */
+    constructor(client: Client, database: string, data: JobData);
+    /** The job's data as of the last `status()` or `wait()` call, or when it was created. */
+    get raw(): JobData;
+    /**
+     * Polls the job's current status.
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<'queued' | 'running' | 'done'>}
+     */
+    status(opts?: RequestOptions): Promise<'queued' | 'running' | 'done'>;
+    /**
+     * 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>}
+     */
+    wait(opts?: RequestOptions & {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    /**
+     * @internal
+     * @param {RequestOptions} [opts]
+     * @returns {Promise<JobData>}
+     */
+    _fetch(opts?: RequestOptions): Promise<JobData>;
+}

package/types/index.d.ts

@@ -0,0 +1,59 @@
+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';
+export type ClientOptions = import('./client.js').ClientOptions;
+export type RequestOptions = import('./client.js').RequestOptions;
+export type RetryOptions = import('./client.js').RetryOptions;
+export type TokenStorage = import('./storage.js').TokenStorage;
+export type User = import('./auth.js').User;
+export type Session = import('./auth.js').Session;
+export type SessionInfo = import('./auth.js').SessionInfo;
+export type AuthEvent = import('./auth.js').AuthEvent;
+export type ErrorDetail = import('./errors.js').ErrorDetail;
+export type Meta = import('./data.js').Meta;
+export type ListParams = import('./data.js').ListParams;
+export type WriteOptions = import('./data.js').WriteOptions;
+export type AdminUser = import('./admin.js').AdminUser;
+export type UserPage = import('./admin.js').UserPage;
+export type Invitation = import('./admin.js').Invitation;
+export type NewInvitation = import('./admin.js').NewInvitation;
+export type SentInvitation = import('./admin.js').SentInvitation;
+export type OwnedReport = import('./admin.js').OwnedReport;
+export type JobData = import('./functions.js').JobData;
+export type JobResult = import('./functions.js').JobResult;
+export type Doc<T extends object = Record<string, any>> = import('./data.js').Doc<T>;
+export type Page<T extends object = Record<string, any>> = import('./data.js').Page<T>;
+/**
+ * @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/types/storage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+export type TokenStorage = {
+    get: () => string | null | undefined | Promise<string | null | undefined>;
+    set: (token: string) => void | Promise<void>;
+    remove: () => void | Promise<void>;
+};
+/**
+ * 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 declare function memoryStorage(): TokenStorage;
+/**
+ * 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 declare function localStorageStorage(key?: string): TokenStorage;

package/.babelrc

@@ -1,4 +0,0 @@
-{
-  "presets": ["env"],
-  "plugins": ["babel-plugin-add-module-exports"]
-}

package/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = LF
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false

package/.eslintrc.js

@@ -1,28 +0,0 @@
-// https://eslint.org/docs/user-guide/configuring
-
-module.exports = {
-  root: true,
-  parser: 'babel-eslint',
-  parserOptions: {
-    sourceType: 'module'
-  },
-  env: {
-    browser: true,
-    es6: true,
-    node: true
-  },
-  // https://github.com/standard/standard/blob/master/docs/RULES-en.md
-  extends: 'standard',
-  // required to lint *.vue files
-  plugins: [
-  ],
-  // add your custom rules here
-  rules: {
-    // allow async-await
-    'generator-star-spacing': 'off',
-    // allow debugger during development
-    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
-    'padded-blocks': 'off',
-    'no-unused-expressions': 'off'
-  }
-}

package/.npmignore

@@ -1,9 +0,0 @@
-.DS_Store
-node_modules
-.docker
-.git
-docker-compose.yml
-src
-test
-publish.sh
-webpack.config.js

package/.nvmrc

@@ -1 +0,0 @@
-v6.10

package/.travis.yml

@@ -1,33 +0,0 @@
-language: node_js
-node_js:
-  - "node"
-  - "7"
-  - "6"
-
-sudo: required
-services:
-  - docker
-
-env:
-  COMPOSE_VERSION: 1.16.0
-
-before_install:
-  - curl -L https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-`uname -s`-`uname -m` > docker-compose
-  - chmod +x docker-compose
-  - sudo mv docker-compose /usr/local/bin
-  - docker-compose up -d mongodb
-  - docker-compose run -e ADMIN_NAME -e ADMIN_EMAIL -e ADMIN_PASSWORD bootstrap
-  - docker-compose up -d api
-
-script:
-  - npm run test
-
-after_install:
-  - docker-compose down
-
-notifications:
-  email:
-    on_success: always
-    on_failure: always
-    recipients:
-      - antoniofernandezvara+backd@gmail.com