Basic node build to support repl

README.md

@@ -1,14 +1,21 @@
-# Setting up this Repo
+# Development
+
+## Goals
+
+1. Vend a Fauna client user's of Fauna can use on the server or the browser.
+2. Vend Typescript for those who want it; plain javascript for those who don't.
+
+## Setting up this Repo
 
 1. Clone the repository; e.g. `gh repo clone fauna/fauna-js` if you use the GitHub CLI
 2. Install dependencies via `yarn install`
 
-# Running tests
+## Running tests
 
 1. Start local Fauna containers using `yarn fauna-local; yarn fauna-local-alt-port`
 2. Wait a bit for for those containers to start (TODO automate this wait).
 3. Run the tests: `yarn test`
 
-# Linting your code
+## Linting your code
 
 Run `yarn lint`. Linting will auslo run automatically on each commit.

lib/client-configuration.d.ts

@@ -0,0 +1,73 @@
+/// <reference types="node" />
+/**
+ * Configuration for a client.
+ */
+export interface ClientConfiguration {
+  /**
+   * The {@link URL} of Fauna to call. See {@link endpoints} for some default options.
+   */
+  endpoint: URL;
+  /**
+   * The maximum number of connections to a make to Fauna.
+   */
+  max_conns: number;
+  /**
+   * A secret for your Fauna DB, used to authorize your queries.
+   * @see https://docs.fauna.com/fauna/current/security/keys
+   */
+  secret: string;
+  /**
+   * The timeout of each query, in milliseconds. This controls the maximum amount of
+   * time Fauna will execute your query before marking it failed.
+   */
+  timeout_ms: number;
+  /**
+   * If true, unconditionally run the query as strictly serialized.
+   * This affects read-only transactions. Transactions which write
+   * will always be strictly serialized.
+   */
+  linearized?: boolean;
+  /**
+   * The max number of times to retry the query if contention is encountered.
+   */
+  max_contention_retries?: number;
+  /**
+   * Tags provided back via logging and telemetry.
+   */
+  tags?: {
+    [key: string]: string;
+  };
+  /**
+   * A traceparent provided back via logging and telemetry.
+   * Must match format: https://www.w3.org/TR/trace-context/#traceparent-header
+   */
+  traceparent?: string;
+}
+/**
+ * An extensible interface for a set of Fauna endpoints.
+ * @remarks Leverage the `[key: string]: URL;` field to extend to other endpoints.
+ */
+export interface Endpoints {
+  /** Fauna's cloud endpoint. */
+  cloud: URL;
+  /**
+   * An endpoint for interacting with local instance of Fauna (e.g. one running in a local docker container).
+   */
+  local: URL;
+  /**
+   * Any other endpoint you want your client to support. For example, if you run all requests through a proxy
+   * configure it here. Most clients will not need to leverage this ability.
+   */
+  [key: string]: URL;
+}
+/**
+ * A extensible set of endpoints for calling Fauna.
+ * @remarks Most clients will will not need to extend this set.
+ * @example
+ * ## To Extend
+ * ```typescript
+ *   // add to the endpoints constant
+ *   endpoints.myProxyEndpoint = new URL("https://my.proxy.url");
+ * ```
+ */
+export declare const endpoints: Endpoints;

lib/client.d.ts

@@ -0,0 +1,61 @@
+import { AxiosInstance } from "axios";
+import type { ClientConfiguration } from "./client-configuration";
+import type { QueryBuilder } from "./query-builder";
+import {
+  type QueryRequest,
+  type QueryRequestHeaders,
+  type QueryResponse,
+} from "./wire-protocol";
+/**
+ * Client for calling Fauna.
+ */
+export declare class Client {
+  #private;
+  /** The {@link ClientConfiguration} */
+  readonly clientConfiguration: ClientConfiguration;
+  /** The underlying {@link AxiosInstance} client. */
+  readonly client: AxiosInstance;
+  /**
+   * Constructs a new {@link Client}.
+   * @param clientConfiguration - the {@link ClientConfiguration} to apply.
+   * @example
+   * ```typescript
+   *  const myClient = new Client(
+   *   {
+   *     endpoint: endpoints.classic,
+   *     secret: "foo",
+   *     queryTimeoutMs: 60_000,
+   *   }
+   * );
+   * ```
+   */
+  constructor(clientConfiguration: ClientConfiguration);
+  /**
+   * Queries Fauna.
+   * @param request - a {@link QueryRequest} or {@link QueryBuilder} to build a request with.
+   *  Note, you can embed header fields in this object; if you do that there's no need to
+   *  pass the headers parameter.
+   * @param headers - optional {@link QueryRequestHeaders} to apply on top of the request input.
+   *   Values in this headers parameter take precedence over the same values in the request
+   *   parameter. This field is primarily intended to be used when you pass a QueryBuilder as
+   *   the parameter.
+   * @returns Promise<{@link QueryResponse}>.
+   * @throws {@link ServiceError} Fauna emitted an error. The ServiceError will be
+   *   one of ServiceError's child classes if the error can be further categorized,
+   *   or a concrete ServiceError if it cannot. ServiceError child types are
+   *   {@link AuthenticaionError}, {@link AuthorizationError}, {@link QueryCheckError}
+   *   {@link QueryRuntimeError}, {@link QueryTimeoutError}, {@link ServiceInternalError}
+   *   {@link ServiceTimeoutError}, {@link ThrottlingError}.
+   *   You can use either the type, or the underlying httpStatus + code to determine
+   *   the root cause.
+   * @throws {@link ProtocolError} the client a HTTP error not sent by Fauna.
+   * @throws {@link NetworkError} the client encountered a network issue
+   * connecting to Fauna.
+   * @throws A {@link ClientError} the client fails to submit the request
+   * due to an internal error.
+   */
+  query<T = any>(
+    request: QueryRequest | QueryBuilder,
+    headers?: QueryRequestHeaders
+  ): Promise<QueryResponse<T>>;
+}

lib/index.d.ts

@@ -0,0 +1,28 @@
+export { Client } from "./client";
+export {
+  type ClientConfiguration,
+  type Endpoints,
+  endpoints,
+} from "./client-configuration";
+export { type QueryBuilder, fql } from "./query-builder";
+export {
+  AuthenticationError,
+  AuthorizationError,
+  ClientError,
+  NetworkError,
+  ProtocolError,
+  QueryCheckError,
+  QueryRuntimeError,
+  QueryTimeoutError,
+  ServiceError,
+  ServiceInternalError,
+  ServiceTimeoutError,
+  ThrottlingError,
+  type JSONObject,
+  type JSONValue,
+  type QueryCheckFailure,
+  type QueryRequest,
+  type QueryRequestHeaders,
+  type QueryResponse,
+  type Span,
+} from "./wire-protocol";