Merge pull request #309 from derbyjs/update-jsdoc

Update Racer jsdoc documentation

- Add typedoc dependencies to generate API documentation
- Fixed exisiting jsdoc links and references that were incorrect
- Add github workflow to generate github pages site

package.json

@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "build": "node_modules/.bin/tsc",
+    "docs": "node_modules/.bin/typedoc",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "pretest": "npm run build",
@@ -41,6 +42,9 @@
     "eslint-config-google": "^0.14.0",
     "mocha": "^9.1.3",
     "nyc": "^15.1.0",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-mdn-links": "^3.1.28",
+    "typedoc-plugin-missing-exports": "^2.2.0",
     "typescript": "^5.1.3"
   },
   "bugs": {

src/Backend.ts

@@ -1,13 +1,23 @@
 import * as path from 'path';
 import * as util from './util';
-import { ModelOptions, RootModel } from './Model/Model';
+import { type ModelOptions, RootModel } from './Model/Model';
 import Backend = require('sharedb');
 
+export type BackendOptions = { modelOptions?: ModelOptions } & Backend.ShareDBOptions;
+
+/**
+ * RacerBackend extends ShareDb Backend
+ */
 export class RacerBackend extends Backend {
   racer: any;
-  modelOptions: any;
+  modelOptions: ModelOptions;
 
-  constructor(racer: any, options?: { modelOptions?: ModelOptions } & Backend.ShareDBOptions) {
+  /**
+   * 
+   * @param racer - Racer instance
+   * @param options - Model and SharedB options 
+   */
+  constructor(racer: any, options?: BackendOptions) {
     super(options);
     this.racer = racer;
     this.modelOptions = options && options.modelOptions;
@@ -17,18 +27,31 @@ export class RacerBackend extends Backend {
     });
   }
 
-  createModel(options?: ModelOptions, req?: any) {
+  /**
+   * Create new `RootModel`
+   *
+   * @param options - Optional model options
+   * @param request - Optional request context See {@link Backend.listen} for details.
+   * @returns a new root model
+   */
+  createModel(options?: ModelOptions, request?: any) {
     if (this.modelOptions) {
       options = (options) ?
         util.mergeInto(options, this.modelOptions) :
         this.modelOptions;
     }
     var model = new RootModel(options);
     this.emit('model', model);
-    model.createConnection(this, req);
+    model.createConnection(this, request);
     return model;
   };
 
+  /**
+   * Model middleware that creates and attaches a {@link Model} to the `request`
+   * and attaches listeners to response for closing model on response completion
+   *
+   * @returns an Express middleware function
+   */
   modelMiddleware() {
     var backend = this;
     function modelMiddleware(req, res, next) {

src/Model/Model.ts

@@ -11,14 +11,24 @@ export type DefualtType = unknown;
 
 declare module './Model' {
   interface DebugOptions {
+    /** Enables browser side logging of ShareDB operations */
     debugMutations?: boolean,
+    /** Disable submitting of local operations to remote backend */
     disableSubmit?: boolean,
     remoteMutations?: boolean,
   }
 
   interface ModelOptions {
+    /** see {@link DebugOptions} */
     debug?: DebugOptions;
+    /** Ensure read-only access of model data */
     fetchOnly?: boolean;
+    /**
+     * Delay in milliseconds before actually unloading data after `unload` called
+     * 
+     * Default to 0 on server, and 1000ms for browser. Runtime value can be inspected
+     * on {@link RootModel.unloadDelay} 
+     */
     unloadDelay?: number;
     bundleTimeout?: number;
   }
@@ -28,6 +38,11 @@ declare module './Model' {
 
 type ModelInitFunction = (instance: RootModel, options: ModelOptions) => void;
 
+/**
+ * Base class for Racer models
+ * 
+ * @typeParam T - Type of data the Model contains
+ */
 export class Model<T = DefualtType> {
   static INITS: ModelInitFunction[] = [];
 
@@ -45,7 +60,11 @@ export class Model<T = DefualtType> {
   _preventCompose: boolean;
   _silent: boolean;
 
-
+  /**
+   * Creates a new Racer UUID
+   * 
+   * @returns a new Racer UUID.
+   * */
   id(): UUID {
     return uuidv4();
   }
@@ -55,6 +74,9 @@ export class Model<T = DefualtType> {
   };
 }
 
+/**
+ * RootModel is the model that holds all data and maintains connection info
+ */
 export class RootModel extends Model<ModelData> {
   backend: RacerBackend;
   connection: Connection;
@@ -70,6 +92,11 @@ export class RootModel extends Model<ModelData> {
   }
 }
 
+/**
+ * Model for some subset of the data
+ * 
+ * @typeParam T - type of data the ChildModel contains.
+ */
 export class ChildModel<T = DefualtType> extends Model<T> {
   constructor(model: Model<T>) {
     super();

src/Model/collections.ts

@@ -33,7 +33,19 @@ declare module './Model' {
     destroy(subpath?: Path): void;
 
     /**
-     * Gets the value located at this model's path or a relative subpath.
+     * Gets the value located at this model's path.
+     *
+     * If no value exists at the path, this returns `undefined`.
+     *
+     * _Note:_ The value is returned by reference, and object values should not
+     * be directly modified - use the Model mutator methods instead. The
+     * TypeScript compiler will enforce no direct modifications, but there are
+     * no runtime guards, which means JavaScript source code could still
+     * improperly make direct modifications.
+     */
+    get(): ReadonlyDeep<T> | undefined;
+    /**
+     * Gets the value located at a relative subpath.
      *
      * If no value exists at the path, this returns `undefined`.
      *
@@ -45,7 +57,6 @@ declare module './Model' {
      *
      * @param subpath
      */
-    get(): ReadonlyDeep<T> | undefined;
     get<S>(subpath?: Path): ReadonlyDeep<S> | undefined;
 
     getCollection(collectionName: string): Collection<JSONObject>;

src/Model/contexts.ts

@@ -24,8 +24,22 @@ declare module './Model' {
      * @see https://derbyjs.github.io/derby/models/contexts
      */
     context(contextId: string): ChildModel<T>;
-    getOrCreateContext(id: string): Context;
-    setContext(id: string): void;
+    /**
+     * Get the named context or create a new named context if it doesnt exist.
+     * 
+     * @param contextId context id
+     * 
+     * @see https://derbyjs.github.io/derby/models/contexts
+     */
+    getOrCreateContext(contextId: string): Context;
+    /**
+     * Set the named context to use for this model.
+     * 
+     * @param contextId context id
+     * 
+     * @see https://derbyjs.github.io/derby/models/contexts
+     */
+    setContext(contextId: string): void;
 
     /**
      * Unloads data for this model's context, or for a specific named context.
@@ -52,24 +66,24 @@ Model.INITS.push(function(model) {
   model.root.setContext('root');
 });
 
-Model.prototype.context = function(id) {
+Model.prototype.context = function(contextId) {
   var model = this._child();
-  model.setContext(id);
+  model.setContext(contextId);
   return model;
 };
 
-Model.prototype.setContext = function(id) {
-  this._context = this.getOrCreateContext(id);
+Model.prototype.setContext = function(contextId) {
+  this._context = this.getOrCreateContext(contextId);
 };
 
-Model.prototype.getOrCreateContext = function(id) {
-  var context = this.root._contexts[id] ||
-    (this.root._contexts[id] = new Context(this, id));
+Model.prototype.getOrCreateContext = function(contextId) {
+  var context = this.root._contexts[contextId] ||
+    (this.root._contexts[contextId] = new Context(this, contextId));
   return context;
 };
 
-Model.prototype.unload = function(id) {
-  var context = (id) ? this.root._contexts[id] : this._context;
+Model.prototype.unload = function(contextId) {
+  var context = (contextId) ? this.root._contexts[contextId] : this._context;
   context && context.unload();
 };
 

src/Model/index.ts

@@ -2,7 +2,7 @@
 /// <reference path="./connection.server.ts" />
 
 import { serverRequire } from '../util';
-export { Model, ChildModel, RootModel, ModelOptions, type UUID, type DefualtType } from './Model';
+export { Model, ChildModel, RootModel, type ModelOptions, type UUID, type DefualtType } from './Model';
 export { ModelData } from './collections';
 export { type Subscribable } from './subscriptions';
 

src/Model/mutators.ts

@@ -44,24 +44,65 @@ declare module './Model' {
     createNullPromised(value: any): Promise<void>;
     createNullPromised(subpath: Path, value: any): Promise<void>;
     _createNull(segments: Segments, value: any, cb?: ErrorCallback): void;
-
+
+    /**
+     * Adds a document to the collection, under an id subpath corresponding
+     * to either the document's `id` property if present, or else a new randomly
+     * generated id.
+     *
+     * If a callback is provided, it's called when the write is committed or
+     * fails.
+     *
+     * @param value - Document to add
+     * @param cb - Optional callback
+     */
     add(value: any, cb?: ValueCallback<string>): string;
+    /**
+     * Adds a document to the collection, under an id subpath corresponding
+     * to either the document's `id` property if present, or else a new randomly
+     * generated id.
+     *
+     * If a callback is provided, it's called when the write is committed or
+     * fails.
+     *
+     * @param subpath - Optional Collection under which to add the document
+     * @param value - Document to add
+     * @param cb - Optional callback
+     */
     add(subpath: Path, value: any, cb?: ValueCallback<string>): string;
     addPromised(value: any): Promise<string>;
     addPromised(subpath: Path, value: any): Promise<string>;
     _add(segments: Segments, value: any, cb?: ValueCallback<string>): string;
 
     /**
-     * Deletes the value at this model's path or a relative subpath.
+     * Deletes the value at this relative subpath.
      *
      * If a callback is provided, it's called when the write is committed or
      * fails.
      *
+     * @typeParam S - Type of the data returned by delete operation
      * @param subpath
      * @returns the old value at the path
      */
     del<S>(subpath: Path, cb?: Callback): S | undefined;
+    /**
+     * Deletes the value at this model's path.
+     *
+     * If a callback is provided, it's called when the write is committed or
+     * fails.
+     *
+     * @typeParam T - Type of the data returned by delete operation
+     * @returns the old value at the path
+     */
     del<T>(cb?: Callback): T | undefined;
+    /**
+     * Deletes the value at this relative subpath. If not provided deletes at model path
+     *
+     * Promise resolves when commit succeeds, rejected on commit failure.
+     *
+     * @param subpath - Optional subpath to delete
+     * @returns promise
+     */
     delPromised(subpath?: Path): Promise<void>;
     _del<S>(segments: Segments, cb?: ErrorCallback): S;
 
@@ -76,11 +117,17 @@ declare module './Model' {
     /**
      * Push a value to a model array
      *
-     * @param subpath
      * @param value
      * @returns the length of the array
      */
     push(value: any): number;
+    /**
+     * Push a value to a model array at subpath
+     *
+     * @param subpath
+     * @param value
+     * @returns the length of the array
+     */
     push(subpath: Path, value: any, cb?: ErrorCallback): number;
     pushPromised(value: any): Promise<void>;
     pushPromised(subpath: Path, value: any): Promise<void>;
@@ -104,7 +151,7 @@ declare module './Model' {
      *
      * If a callback is provided, it's called when the write is committed or
      * fails.
-     *
+     * @typeParam V - type of data at subpath
      * @param subpath
      * @returns the removed item
      */
@@ -125,7 +172,8 @@ declare module './Model' {
      * If a callback is provided, it's called when the write is committed or
      * fails.
      *
-     * @param subpath
+     * @typeParam - Type of data targeted by remove operation
+     * @param subpath - Subpath to remove
      * @param index - 0-based index at which to start removing items
      * @param howMany - Number of items to remove. Defaults to `1`.
      * @returns array of the removed items