From d4fb58c007d477d0898f2954122ca841cedc5dce Mon Sep 17 00:00:00 2001 From: Chad Engler Date: Sun, 1 Dec 2019 08:50:58 -0800 Subject: [PATCH] Fix up documentation --- package.json | 2 +- src/Loader.ts | 53 ++++++++++++--------- src/Resource.ts | 27 +++++++---- src/async/AsyncQueue.ts | 10 ++-- src/bundle.ts | 1 + src/index.ts | 5 -- src/load_strategies/AbstractLoadStrategy.ts | 25 +++++++--- tsconfig.json | 19 ++++++++ 8 files changed, 91 insertions(+), 51 deletions(-) diff --git a/package.json b/package.json index 92441b3..ac12a42 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,7 @@ "test": "npm run test-dev -- --single-run", "pretest-dev": "npm run build", "test-dev": "karma start test/karma.conf.js", - "docs": "typedoc --out docs --mode modules", + "docs": "typedoc", "prepublishOnly": "npm run build", "predeploy": "rimraf ./docs && npm run docs", "deploy": "gh-pages -d docs", diff --git a/src/Loader.ts b/src/Loader.ts index 7bd37a7..4e3d869 100644 --- a/src/Loader.ts +++ b/src/Loader.ts @@ -1,7 +1,7 @@ import parseUri from 'parse-uri'; import { Signal } from 'type-signals'; import { AsyncQueue } from './async/AsyncQueue'; -import { Resource, OnCompleteSignal as OnResourceCompleteSignal } from './Resource'; +import { Resource } from './Resource'; import { ILoadConfig } from './load_strategies/AbstractLoadStrategy'; import { eachSeries } from './async/eachSeries'; @@ -9,20 +9,26 @@ import { eachSeries } from './async/eachSeries'; const MAX_PROGRESS = 100; const rgxExtractUrlHash = /(#[\w-]+)?$/; -export type ResourceMap = Partial>; +/** + * @category Type Aliases + */ +export namespace Loader +{ + export type ResourceMap = Partial>; -export type OnProgressSignal = (loader: Loader, resource: Resource) => void; -export type OnErrorSignal = (errMessage: string, loader: Loader, resource: Resource) => void; -export type OnLoadSignal = (loader: Loader, resource: Resource) => void; -export type OnStartSignal = (loader: Loader) => void; -export type OnCompleteSignal = (loader: Loader, resources: ResourceMap) => void; + export type OnProgressSignal = (loader: Loader, resource: Resource) => void; + export type OnErrorSignal = (errMessage: string, loader: Loader, resource: Resource) => void; + export type OnLoadSignal = (loader: Loader, resource: Resource) => void; + export type OnStartSignal = (loader: Loader) => void; + export type OnCompleteSignal = (loader: Loader, resources: ResourceMap) => void; -export type MiddlewareFn = (resource: Resource, next: () => void) => void; -export type UrlResolverFn = (url: string, parsed: ReturnType) => string; + export type MiddlewareFn = (resource: Resource, next: () => void) => void; + export type UrlResolverFn = (url: string, parsed: ReturnType) => string; +} -export interface Middleware +interface Middleware { - fn: MiddlewareFn; + fn: Loader.MiddlewareFn; priority: number; } @@ -44,7 +50,7 @@ export interface IAddOptions extends ILoadConfig name?: string; // Callback to add an an onComplete signal istener. - onComplete?: OnResourceCompleteSignal; + onComplete?: Resource.OnCompleteSignal; // Parent resource this newly added resource is a child of. parentResource?: Resource; @@ -52,6 +58,7 @@ export interface IAddOptions extends ILoadConfig /** * Manages the state and loading of multiple resources to load. + * @preferred */ export class Loader { @@ -65,7 +72,7 @@ export class Loader * can be used to modify the url just prior to `baseUrl` and `defaultQueryString` * being applied. */ - urlResolver: UrlResolverFn | null = null; + urlResolver: Loader.UrlResolverFn | null = null; /** * The progress percent of the loader going through the queue. @@ -100,34 +107,34 @@ export class Loader defaultQueryString = ''; /** - * All the resources for this loader keyed by name. + * All the resources for this loader keyed by name, or URL if no name was given. */ - resources: ResourceMap = {}; + resources: Loader.ResourceMap = {}; /** * Dispatched once per errored resource. */ - onError = new Signal(); + readonly onError: Signal = new Signal(); /** * Dispatched once per loaded resource. */ - onLoad = new Signal(); + readonly onLoad: Signal = new Signal(); /** * Dispatched when the loader begins to process the queue. */ - onStart = new Signal(); + readonly onStart: Signal = new Signal(); /** * Dispatched when the queued resources all load. */ - onComplete = new Signal(); + readonly onComplete: Signal = new Signal(); /** * Dispatched once per loaded or errored resource. */ - onProgress = new Signal(); + readonly onProgress: Signal = new Signal(); /** * The base url for all resources loaded by this loader. @@ -324,7 +331,7 @@ export class Loader * A lower priority value will make the function run earlier. * That is, priority 30 is run before priority 50. */ - use(fn: MiddlewareFn, priority: number = Loader.DefaultMiddlewarePriority): this + use(fn: Loader.MiddlewareFn, priority: number = Loader.DefaultMiddlewarePriority): this { this._middleware.push({ fn, priority }); this._middleware.sort((a, b) => a.priority - b.priority); @@ -365,7 +372,7 @@ export class Loader /** * Starts loading the queued resources. */ - load(cb?: OnCompleteSignal): this + load(cb?: Loader.OnCompleteSignal): this { if (typeof cb === 'function') this.onComplete.once(cb); @@ -544,7 +551,7 @@ export class Loader * A lower priority value will make the function run earlier. * That is, priority 30 is run before priority 50. */ - static use(fn: MiddlewareFn, priority = Loader.DefaultMiddlewarePriority): typeof Loader + static use(fn: Loader.MiddlewareFn, priority = Loader.DefaultMiddlewarePriority): typeof Loader { Loader._defaultMiddleware.push({ fn, priority }); Loader._defaultMiddleware.sort((a, b) => a.priority - b.priority); diff --git a/src/Resource.ts b/src/Resource.ts index e4bc639..d071e34 100644 --- a/src/Resource.ts +++ b/src/Resource.ts @@ -8,18 +8,25 @@ import { XhrLoadStrategy } from './load_strategies/XhrLoadStrategy'; import { ResourceType, ResourceState } from './resource_type'; import { getExtension } from './utilities'; -export type OnStartSignal = (resource: Resource) => void; -export type OnErrorSignal = (resource: Resource) => void; -export type OnCompleteSignal = (resource: Resource) => void; -export type OnProgressSignal = (resource: Resource, percent: number) => void; - export interface IResourceOptions extends ILoadConfig { strategy?: AbstractLoadStrategy | AbstractLoadStrategyCtor; } +/** + * @category Type Aliases + */ +export namespace Resource +{ + export type OnStartSignal = (resource: Resource) => void; + export type OnErrorSignal = (resource: Resource) => void; + export type OnCompleteSignal = (resource: Resource) => void; + export type OnProgressSignal = (resource: Resource, percent: number) => void; +} + /** * Manages the state and loading of a resource and all child resources. + * @preferred */ export class Resource { @@ -89,7 +96,7 @@ export class Resource /** * Dispatched when the resource beings to load. */ - readonly onStart = new Signal(); + readonly onStart: Signal = new Signal(); /** * Dispatched each time progress of this resource load updates. @@ -98,18 +105,18 @@ export class Resource * is being loaded on a modern browser, using XHR, and the remote server * properly sets Content-Length headers, then this will be available. */ - readonly onProgress = new Signal(); + readonly onProgress: Signal = new Signal(); /** * Dispatched once this resource has loaded, if there was an error it will * be in the `error` property. */ - readonly onComplete = new Signal(); + readonly onComplete: Signal = new Signal(); /** * Dispatched after this resource has had all the *after* middleware run on it. */ - readonly onAfterMiddleware = new Signal(); + readonly onAfterMiddleware: Signal = new Signal(); /** * The data that was loaded by the resource. The type of this member is @@ -148,7 +155,7 @@ export class Resource * * @ignore */ - _onCompleteBinding: SignalBinding | null = null; + _onCompleteBinding: SignalBinding | null = null; private _strategy: AbstractLoadStrategy; private _state = ResourceState.NotStarted; diff --git a/src/async/AsyncQueue.ts b/src/async/AsyncQueue.ts index 030e461..b2e011a 100644 --- a/src/async/AsyncQueue.ts +++ b/src/async/AsyncQueue.ts @@ -57,11 +57,11 @@ export class AsyncQueue private _started = false; private _tasks: ITask[] = []; - readonly onSaturated = new Signal(); - readonly onUnsaturated = new Signal(); - readonly onEmpty = new Signal(); - readonly onDrain = new Signal(); - readonly onError = new Signal>(); + readonly onSaturated: Signal = new Signal(); + readonly onUnsaturated: Signal = new Signal(); + readonly onEmpty: Signal = new Signal(); + readonly onDrain: Signal = new Signal(); + readonly onError: Signal> = new Signal>(); constructor(readonly worker: IWorker, public concurrency = 1) { diff --git a/src/bundle.ts b/src/bundle.ts index f2dba65..d0c6d98 100644 --- a/src/bundle.ts +++ b/src/bundle.ts @@ -9,6 +9,7 @@ import { Loader } from './Loader'; import { Resource } from './Resource'; import { ResourceType, ResourceState } from './resource_type'; +// TODO: Hide this stuff and only expose for tests import { AsyncQueue } from './async/AsyncQueue'; import { eachSeries } from './async/eachSeries'; import { getExtension } from './utilities'; diff --git a/src/index.ts b/src/index.ts index 1f923da..ebe821d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -8,8 +8,3 @@ export { XhrLoadStrategy } from './load_strategies/XhrLoadStrategy'; export { Loader } from './Loader'; export { Resource } from './Resource'; export { ResourceType, ResourceState } from './resource_type'; - -import { AsyncQueue } from './async/AsyncQueue'; -import { eachSeries } from './async/eachSeries'; - -export const async = { AsyncQueue, eachSeries }; diff --git a/src/load_strategies/AbstractLoadStrategy.ts b/src/load_strategies/AbstractLoadStrategy.ts index 9b3e5ba..933467d 100644 --- a/src/load_strategies/AbstractLoadStrategy.ts +++ b/src/load_strategies/AbstractLoadStrategy.ts @@ -1,10 +1,6 @@ import { Signal } from 'type-signals'; import { ResourceType } from '../resource_type'; -export type OnErrorSignal = (errMessage: string) => void; -export type OnCompleteSignal = (type: ResourceType, data: any) => void; -export type OnProgressSignal = (percent: number) => void; - export interface ILoadConfig { // The url for this resource, relative to the baseUrl of this loader. @@ -21,18 +17,33 @@ export interface ILoadConfig timeout?: number; } +/** + * @category Type Aliases + */ +export namespace AbstractLoadStrategy +{ + export type OnErrorSignal = (errMessage: string) => void; + export type OnCompleteSignal = (type: ResourceType, data: any) => void; + export type OnProgressSignal = (percent: number) => void; +} + +/** + * Base load strategy interface that all custom load strategies + * are expected to inherit from and implement. + * @preferred + */ export abstract class AbstractLoadStrategy { /** * Dispatched when the resource fails to load. */ - readonly onError = new Signal(); + readonly onError: Signal = new Signal(); /** * Dispatched once this resource has loaded, if there was an error it will * be in the `error` property. */ - readonly onComplete = new Signal(); + readonly onComplete: Signal = new Signal(); /** * Dispatched each time progress of this resource load updates. @@ -41,7 +52,7 @@ export abstract class AbstractLoadStrategy * is being loaded on a modern browser, using XHR, and the remote server * properly sets Content-Length headers, then this will be available. */ - readonly onProgress = new Signal(); + readonly onProgress: Signal = new Signal(); constructor(readonly config: C) { } diff --git a/tsconfig.json b/tsconfig.json index a2c3f6b..d94baf2 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -9,6 +9,25 @@ "sourceMap": true, "strict": true }, + "typedocOptions": { + "mode": "file", + "out": "docs", + "excludeExternals": true, + "excludeNotExported": true, + "excludePrivate": true, + "toc": [ + "AbstractLoadStrategy", + "AudioLoadStrategy", + "ImageLoadStrategy", + "MediaElementLoadStrategy", + "VideoLoadStrategy", + "XhrLoadStrategy", + "Loader", + "Resource", + "ResourceType", + "ResourceState" + ] + }, "include": [ "src/**/*", "types/**/*"