Type refinements

Author: craigbeck

src/Model/Doc.ts

@@ -3,10 +3,10 @@ import { type Segments } from './types';
 import { Collection } from './collections';
 
 export class Doc {
-  collectionName: string;
-  id: string;
   collectionData: Model;
+  collectionName: string;
   data: any;
+  id: string;
   model: Model;
 
   constructor(model: Model, collectionName: string, id: string, data: any, _collection?: Collection) {

src/Model/Query.ts

@@ -3,7 +3,9 @@ import { type Segments } from './types';
 import { ChildModel, ErrorCallback, Model } from './Model';
 import { CollectionMap } from './CollectionMap';
 import { ModelData } from '.';
-import { Doc } from 'sharedb';
+import type { Doc } from './Doc';
+import type { Doc as ShareDBDoc } from 'sharedb';
+import type { RemoteDoc } from './RemoteDoc';
 
 var defaultType = require('sharedb/lib/client').types.defaultType;
 var util = require('../util');
@@ -267,7 +269,7 @@ export class Query<T = {}> {
 
   fetchPromised = promisify(Query.prototype.fetch);
 
-  subscribe(cb) {
+  subscribe(cb: ErrorCallback) {
     cb = this.model.wrapCallback(cb);
     this.context.subscribeQuery(this);
 
@@ -303,9 +305,9 @@ export class Query<T = {}> {
 
   subscribePromised = promisify(Query.prototype.subscribe);
 
-  _subscribeCb(cb) {
+  _subscribeCb(cb: ErrorCallback) {
     var query = this;
-    return function subscribeCb(err: Error, results: Doc[], extra?: any) {
+    return function subscribeCb(err: Error, results: ShareDBDoc[], extra?: any) {
       if (err) return query._flushSubscribeCallbacks(err, cb);
       query._setExtra(extra);
       query._setResults(results);
@@ -405,7 +407,7 @@ export class Query<T = {}> {
     if (extra === undefined) return;
     this.model._setDiffDeep(this.extraSegments, extra);
   };
-  _setResults(results) {
+  _setResults(results: ShareDBDoc[]) {
     var ids = resultsIds(results);
     this._setResultIds(ids);
   };
@@ -507,7 +509,7 @@ export class Query<T = {}> {
     var results = [];
     for (var i = 0; i < ids.length; i++) {
       var id = ids[i];
-      var doc = collection.docs[id];
+      var doc = collection.docs[id] as RemoteDoc;
       results.push(doc && doc.shareDoc);
     }
     return results;
@@ -526,7 +528,7 @@ export class Query<T = {}> {
     var collection = this.model.getCollection(this.collectionName);
     for (var i = 0, l = ids.length; i < l; i++) {
       var id = ids[i];
-      var doc = collection && collection.docs[id];
+      var doc = (collection && collection.docs[id]) as RemoteDoc;
       results.push(doc && doc.get());
     }
     return results;
@@ -564,7 +566,7 @@ export class Query<T = {}> {
       results = [];
       for (var i = 0; i < ids.length; i++) {
         var id = ids[i];
-        var doc = collection.docs[id];
+        var doc = collection.docs[id] as RemoteDoc;
         if (doc) {
           delete collection.docs[id];
           var data = doc.shareDoc.data;
@@ -610,7 +612,7 @@ function queryHash(contextId, collectionName, expression, options) {
   return JSON.stringify(args).replace(/\./g, '|');
 }
 
-function resultsIds(results) {
+function resultsIds(results: { id: string }[]): string[] {
   var ids = [];
   for (var i = 0; i < results.length; i++) {
     var shareDoc = results[i];

src/Model/collections.ts

@@ -1,28 +1,78 @@
 import { type Segments } from './types';
 import { Doc } from './Doc';
 import { Model, RootModel } from './Model';
+import { JSONObject } from 'sharedb/lib/sharedb';
+import { VerifyJsonWebKeyInput } from 'crypto';
+import { Path, ReadonlyDeep, ShallowCopiedValue } from '../types';
 var LocalDoc = require('./LocalDoc');
 var util = require('../util');
 
 export class ModelCollections {
   docs: Record<string, any>;
 }
-export class ModelData {}
-export class DocMap {}
-export class CollectionData {}
+
+/** Root model data */
+export class ModelData {
+  [collectionName: string]: CollectionData<JSONObject>;
+}
+
+class DocMap {
+  [id: string]: Doc;
+}
+
+/** Dictionary of document id to document data */
+export class CollectionData<T extends JSONObject> {
+  [id: string]: T;
+}
 
 declare module './Model' {
   interface RootModel {
     collections: ModelCollections;
     data: ModelData;
   }
-  interface Model {
+  interface Model<T> {
     destroy(subpath?: string): void;
-    get(subpath?: string): any;
-    get<T>(subpath?: string): T;
-    getCollection(collecitonName: string): ModelCollections;
-    getCopy(subpath: string): any;
-    getDeepCopy(subpath: string): any;
+
+    /**
+     * Gets the value located at this model's path or a relative subpath.
+     *
+     * 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.
+     *
+     * @param subpath
+     */
+    get<S>(subpath: Path): ReadonlyDeep<S> | undefined;
+    get(): ReadonlyDeep<T> | undefined;
+    
+    getCollection(collectionName: string): Collection<JSONObject>;
+    
+    /**
+     * Gets a shallow copy of the value located at this model's path or a relative
+     * subpath.
+     *
+     * If no value exists at the path, this returns `undefined`.
+     *
+     * @param subpath
+     */
+    getCopy<S>(subpath: Path): ShallowCopiedValue<S> | undefined;
+    getCopy(): ShallowCopiedValue<T> | undefined;
+
+    /**
+     * Gets a deep copy of the value located at this model's path or a relative
+     * subpath.
+     *
+     * If no value exists at the path, this returns `undefined`.
+     *
+     * @param subpath
+     */
+    getDeepCopy<S>(subpath: Path): S | undefined;
+    getDeepCopy(): T | undefined;
+
     getDoc(collecitonName: string, id: string): any | undefined;
     getOrCreateCollection(name: string): Collection;
     getOrCreateDoc(collectionName: string, id: string, data: any);
@@ -47,28 +97,28 @@ Model.prototype.getDoc = function(collectionName, id) {
   return collection && collection.docs[id];
 };
 
-Model.prototype.get = function(subpath) {
+Model.prototype.get = function<S>(subpath?: Path) {
   var segments = this._splitPath(subpath);
-  return this._get(segments);
+  return this._get(segments) as ReadonlyDeep<S>;
 };
 
 Model.prototype._get = function(segments) {
   return util.lookup(segments, this.root.data);
 };
 
-Model.prototype.getCopy = function(subpath) {
+Model.prototype.getCopy = function<S>(subpath?: Path) {
   var segments = this._splitPath(subpath);
-  return this._getCopy(segments);
+  return this._getCopy(segments) as ReadonlyDeep<S>;
 };
 
 Model.prototype._getCopy = function(segments) {
   var value = this._get(segments);
   return util.copy(value);
 };
 
-Model.prototype.getDeepCopy = function(subpath) {
+Model.prototype.getDeepCopy = function<S>(subpath?: Path) {
   var segments = this._splitPath(subpath);
-  return this._getDeepCopy(segments);
+  return this._getDeepCopy(segments) as S;
 };
 
 Model.prototype._getDeepCopy = function(segments) {
@@ -135,12 +185,12 @@ Model.prototype.destroy = function(subpath) {
   }
 };
 
-export class Collection {
+export class Collection<T extends JSONObject = {}> {
   model: RootModel;
   name: string;
   size: number;
   docs: DocMap;
-  data: CollectionData;
+  data: CollectionData<T>;
   Doc: typeof Doc;
 
   constructor(model: RootModel, name: string, docClass: typeof Doc) {
@@ -149,7 +199,7 @@ export class Collection {
     this.Doc = docClass;
     this.size = 0;
     this.docs = new DocMap();
-    this.data = model.data[name] = new CollectionData();
+    this.data = model.data[name] = new CollectionData<T>();
   }
 
   /**

src/util.ts

@@ -112,11 +112,11 @@ export function equalsNaN(x) {
   return x !== x;
 }
 
-export function isArrayIndex(segment) {
+export function isArrayIndex(segment: string): boolean {
   return (/^[0-9]+$/).test(segment);
 }
 
-export function lookup(segments, value) {
+export function lookup(segments: string[], value: unknown): unknown {
   if (!segments) return value;
 
   for (var i = 0, len = segments.length; i < len; i++) {
@@ -126,14 +126,14 @@ export function lookup(segments, value) {
   return value;
 }
 
-export function mayImpactAny(segmentsList, testSegments) {
+export function mayImpactAny(segmentsList: string[][], testSegments: string[]) {
   for (var i = 0, len = segmentsList.length; i < len; i++) {
     if (mayImpact(segmentsList[i], testSegments)) return true;
   }
   return false;
 }
 
-export function mayImpact(segments, testSegments) {
+export function mayImpact(segments: string[], testSegments: string[]): boolean {
   var len = Math.min(segments.length, testSegments.length);
   for (var i = 0; i < len; i++) {
     if (segments[i] !== testSegments[i]) return false;
@@ -186,13 +186,13 @@ export function serverRequire(module, id) {
   return module.require(id);
 }
 
-export function serverUse(module, id, options) {
+export function serverUse(module, id: string, options?: unknown) {
   if (!isServer) return this;
   var plugin = module.require(id);
   return this.use(plugin, options);
 }
 
-export function use(plugin, options) {
+export function use(plugin, options?: unknown) {
   // Don't include a plugin more than once
   var plugins = this._plugins || (this._plugins = []);
   if (plugins.indexOf(plugin) === -1) {