Add typedocs (#42)

Update documentation blurbs and deploy to github pages

.eslintrc.yml

@@ -30,5 +30,6 @@ parserOptions:
 ignorePatterns:
   - jest.config.js
   - "dist/"
+  - "docs/"
   - "examples/"
   - "coverage/"

.github/workflows/cicd.yaml

@@ -18,7 +18,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Set up Node
         uses: actions/setup-node@v4
         with:

.github/workflows/docs.yaml

@@ -0,0 +1,62 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+      - name: Install dependencies
+        run: npm install
+      - name: Build docs
+        run: npm run docs
+      - name: Archive artifact # from: https://github.com/actions/upload-pages-artifact
+        shell: sh
+        run: |
+          echo ::group::Archive artifact
+          tar \
+            --dereference --hard-dereference \
+            --directory docs \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+          echo ::endgroup::
+      - name: Upload artifact
+        id: upload-artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          if-no-files-found: error
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - id: deployment
+        name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: github-pages

.gitignore

@@ -2,6 +2,7 @@
 node_modules/
 out/
 dist/
+docs/
 coverage/
 .next/
 mydb.sqlite

.prettierignore

@@ -1,5 +1,6 @@
 build
 dist
+docs
 coverage
 examples
 README.md

lib/core/opts.ts

@@ -1,53 +1,134 @@
 import { IEncoder } from "./encoder";
 import { IRetry } from "./retry";
+import { ILogger } from "./logger";
+import { IStore } from "./store";
+import { IBucket } from "./bucket";
 
-export type Opts = {
+/**
+ * Resonate configuration options.
+ */
+export interface ResonateOptions {
   /**
-   * Overrides the default identifer.
+   * A bucket instance, if not provided a default bucket will be
+   * used.
    */
-  id?: string;
+  bucket: IBucket;
 
   /**
-   * Overrides the default idempotency key.
+   * An encoder instance used for encoding and decoding values
+   * returned (or thrown) by registered functions. If not provided,
+   * a default JSON encoder will be used.
    */
-  idempotencyKey?: string;
+  encoder: IEncoder<unknown, string | undefined>;
 
   /**
-   * Overrides the default timeout.
+   * A process id that can be used to uniquely identify this Resonate
+   * instance. If not provided a default value will be generated.
    */
-  timeout: number;
+  pid: string;
 
   /**
-   * Overrides the default retry policy.
+   * A logger instance, if not provided a default logger will be
+   * used.
+   */
+  logger: ILogger;
+
+  /**
+   * Your resonate namespace, defaults to an empty string.
+   */
+  namespace: string;
+
+  /**
+   * The frequency in ms to poll the promise server for pending
+   * promises that may need to be recovered, defaults to 1000.
+   */
+  recoveryDelay: number;
+
+  /**
+   * A retry instance, defaults to exponential backoff.
    */
   retry: IRetry;
 
+  /**
+   * A seperator token used for constructing promise ids, defaults to
+   * "/".
+   */
+  separator: string;
+
+  /**
+   * A store instance, if provided this will take precedence over a
+   * remote store.
+   */
+  store: IStore;
+
+  /**
+   * The default promise timeout in ms, used for every function
+   * executed by calling run. Defaults to 1000.
+   */
+  timeout: number;
+
+  /**
+   * The remote promise store url. If not provided, an in-memory
+   * promise store will be used.
+   */
+  url: string;
+}
+
+export interface ContextOptions {
+  /**
+   * Overrides the default bucket.
+   */
+  bucket: IBucket;
+
+  /**
+   * Overrides the generated default execution id.
+   */
+  eid: string;
+
   /**
    * Overrides the default encoder.
    */
   encoder: IEncoder<unknown, string | undefined>;
 
   /**
-   * Overrides the default execution id.
+   * Overrides the default promise identifer.
    */
-  eid: string;
-};
+  id?: string;
+
+  /**
+   * Overrides the default promise idempotency key.
+   */
+  idempotencyKey?: string;
+
+  /**
+   * Overrides the default retry policy.
+   */
+  retry: IRetry;
+
+  /**
+   * Overrides the default timeout.
+   */
+  timeout: number;
+}
 
-export class ContextOpts {
-  constructor(private opts: Partial<Opts> = {}) {}
+// Use a class to wrap ContextOptions so we can use the prototype
+// (see the type guard below) to distinguish between options and a
+// function parameters on calls to run.
+export class Options {
+  constructor(private opts: Partial<ContextOptions> = {}) {}
 
-  all(): Partial<Opts> {
+  all(): Partial<ContextOptions> {
     return this.opts;
   }
 
-  merge(opts: Partial<Opts>): ContextOpts {
-    return new ContextOpts({
+  merge(opts: Partial<ContextOptions>): Options {
+    return new Options({
       ...this.opts,
       ...opts,
     });
   }
 }
 
-export function isContextOpts(o: unknown): o is ContextOpts {
-  return o instanceof ContextOpts;
+export function isContextOpts(o: unknown): o is Options {
+  return o instanceof Options;
 }

lib/core/types.ts

@@ -0,0 +1,59 @@
+import { Context } from "../resonate";
+
+// Types
+
+// Resonate supports any function that takes a context as the first
+// argument. The generic parameter is used to restrict the return
+// type when a generator used.
+
+/**
+ * Represents a Resonate function. Must define {@link Context} as the
+ * first argument, may by additional arguments.
+ *
+ * @template T Represents the return type of the function.
+ * @param ctx - The Resonate {@link Context}.
+ * @param args - Additional function arguments.
+ */
+export type Func<T = any> = (ctx: Context, ...args: any[]) => T;
+
+// Similar to the built in Parameters type, but ignores the required
+// context parameter.
+
+/**
+ * Infers the parameters of a Resonate function.
+ *
+ * @template F The Resonate function type.
+ */
+export type Params<F extends Func> = F extends (ctx: Context, ...args: infer P) => any ? P : never;
+
+// Similar to the built in ReturnType type, but optionally returns
+// the awaited inferred return value of F if F is a generator,
+// otherwise returns the awaited inferred return value.
+
+/**
+ * Infers the return type of a Resonate function.
+ *
+ * If a generator is used, the return type will be the return type of
+ * the generator, otherwise the return type will be the return type
+ * of the function.
+ *
+ * @template F The Resonate function type.
+ */
+export type Return<F extends Func> = F extends (ctx: Context, ...args: any) => infer R
+  ? R extends Generator<unknown, infer G>
+    ? Awaited<G>
+    : Awaited<R>
+  : never;
+
+// Type Guards
+
+export function isFunction(f: unknown): f is Func {
+  return (
+    typeof f === "function" &&
+    (f.constructor.name === "Function" || f.constructor.name === "AsyncFunction" || f.constructor.name === "")
+  );
+}
+
+export function isGenerator(f: unknown): f is Func<Generator> {
+  return typeof f === "function" && f.constructor.name === "GeneratorFunction";
+}

lib/index.ts

@@ -1,3 +1,5 @@
 import { Resonate, Context } from "./resonate";
+import { ResonateOptions, ContextOptions } from "./core/opts";
+import { Func, Params, Return } from "./core/types";
 
-export { Resonate, Context };
+export { Resonate, Context, ResonateOptions, ContextOptions, Func, Params, Return };