From fce81baa1e54614bcd98fea2d710905af3c5c9ab Mon Sep 17 00:00:00 2001 From: Piotr Pietrzak Date: Wed, 31 Jan 2018 20:54:33 +0100 Subject: [PATCH 1/4] @types/matter-js - Add Matter.use and Matter.Plugin. --- types/matter-js/index.d.ts | 144 ++++++++++++++++++++++++++++- types/matter-js/matter-js-tests.ts | 10 +- 2 files changed, 150 insertions(+), 4 deletions(-) diff --git a/types/matter-js/index.d.ts b/types/matter-js/index.d.ts index 51a367df6c..a76ee1cc51 100644 --- a/types/matter-js/index.d.ts +++ b/types/matter-js/index.d.ts @@ -1,13 +1,24 @@ // Type definitions for Matter.js - 0.9.1 // Project: https://github.com/liabru/matter-js // Definitions by: Ivane Gegia , -// David Asmuth +// David Asmuth , +// Piotr Pietrzak git // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped export = Matter; export as namespace Matter; declare namespace Matter { + /** + * Installs the given plugins on the `Matter` namespace. + * This is a short-hand for `Plugin.use`, see it for more information. + * Call this function once at the start of your code, with all of the plugins you wish to install as arguments. + * Avoid calling this function multiple times unless you intend to manually control installation order. + * @method use + * @param ...plugin {Function} The plugin(s) to install on `base` (multi-argument). + */ + export function use(...plugins: (Object | string)[]): void; + /** * The `Matter.Axes` module contains methods for creating and manipulating sets of axes. * @@ -3315,4 +3326,135 @@ declare namespace Matter { static trigger(object: any, eventNames: string, event?: (e: any) => void): void; } + + type Dependency = {name: string, range: string} + | {name: string, version: string} + | string; + + export class Plugin { + + /** + * Registers a plugin object so it can be resolved later by name. + * @method register + * @param plugin {} The plugin to register. + * @return {object} The plugin. + */ + static register(plugin: T): T; + + /** + * Resolves a dependency to a plugin object from the registry if it exists. + * The `dependency` may contain a version, but only the name matters when resolving. + * @method resolve + * @param dependency {string} The dependency. + * @return {object} The plugin if resolved, otherwise `undefined`. + */ + static resolve(dependency: string): object | undefined; + + /** + * Returns `true` if the object meets the minimum standard to be considered a plugin. + * This means it must define the following properties: + * - `name` + * - `version` + * - `install` + * @method isPlugin + * @param obj {} The obj to test. + * @return {boolean} `true` if the object can be considered a plugin otherwise `false`. + */ + static isPlugin(obj: object): boolean; + + /** + * Returns a pretty printed plugin name and version. + * @method toString + * @param plugin {} The plugin. + * @return {string} Pretty printed plugin name and version. + */ + static toString(plugin: string | object): string; + + /** + * Returns `true` if `plugin.for` is applicable to `module` by comparing against `module.name` and `module.version`. + * If `plugin.for` is not specified then it is assumed to be applicable. + * The value of `plugin.for` is a string of the format `'module-name'` or `'module-name@version'`. + * @method isFor + * @param plugin {} The plugin. + * @param module {} The module. + * @return {boolean} `true` if `plugin.for` is applicable to `module`, otherwise `false`. + */ + static isFor(plugin: object, module: object): boolean; + + /** + * Installs the plugins by calling `plugin.install` on each plugin specified in `plugins` if passed, otherwise `module.uses`. + * For installing plugins on `Matter` see the convenience function `Matter.use`. + * Plugins may be specified either by their name or a reference to the plugin object. + * Plugins themselves may specify further dependencies, but each plugin is installed only once. + * Order is important, a topological sort is performed to find the best resulting order of installation. + * This sorting attempts to satisfy every dependency's requested ordering, but may not be exact in all cases. + * This function logs the resulting status of each dependency in the console, along with any warnings. + * - A green tick ✅ indicates a dependency was resolved and installed. + * - An orange diamond 🔶 indicates a dependency was resolved but a warning was thrown for it or one if its dependencies. + * - A red cross ❌ indicates a dependency could not be resolved. + * Avoid calling this function multiple times on the same module unless you intend to manually control installation order. + * @method use + * @param module {} The module install plugins on. + * @param [plugins=module.uses] {} The plugins to install on module (optional, defaults to `module.uses`). + */ + static use(module: object, plugins: string[]): void; + + /** + * Recursively finds all of a module's dependencies and returns a flat dependency graph. + * @method dependencies + * @param module {} The module. + * @return {object} A dependency graph. + */ + static dependencies( + module: Dependency, + tracked: object + ): object | string | undefined + + /** + * Parses a dependency string into its components. + * The `dependency` is a string of the format `'module-name'` or `'module-name@version'`. + * See documentation for `Plugin.versionParse` for a description of the format. + * This function can also handle dependencies that are already resolved (e.g. a module object). + * @method dependencyParse + * @param dependency {string} The dependency of the format `'module-name'` or `'module-name@version'`. + * @return {object} The dependency parsed into its components. + */ + static dependencyParse(dependency: Dependency) : {name: string, range: string}; + + /** + * Parses a version string into its components. + * Versions are strictly of the format `x.y.z` (as in [semver](http://semver.org/)). + * Versions may optionally have a prerelease tag in the format `x.y.z-alpha`. + * Ranges are a strict subset of [npm ranges](https://docs.npmjs.com/misc/semver#advanced-range-syntax). + * Only the following range types are supported: + * - Tilde ranges e.g. `~1.2.3` + * - Caret ranges e.g. `^1.2.3` + * - Exact version e.g. `1.2.3` + * - Any version `*` + * @method versionParse + * @param range {string} The version string. + * @return {object} The version range parsed into its components. + */ + static versionParse(range: string) : { + isRange: boolean, + version: string, + range: string, + operator: string + parts: number[], + prerelease: string, + number: number + }; + + /** + * Returns `true` if `version` satisfies the given `range`. + * See documentation for `Plugin.versionParse` for a description of the format. + * If a version or range is not specified, then any version (`*`) is assumed to satisfy. + * @method versionSatisfies + * @param version {string} The version string. + * @param range {string} The range string. + * @return {boolean} `true` if `version` satisfies `range`, otherwise `false`. + */ + static versionSatisfies(version: string, range: string): boolean; + + } } diff --git a/types/matter-js/matter-js-tests.ts b/types/matter-js/matter-js-tests.ts index d94a1b6bed..bfec5afb66 100644 --- a/types/matter-js/matter-js-tests.ts +++ b/types/matter-js/matter-js-tests.ts @@ -6,9 +6,13 @@ var Engine = Matter.Engine, Composites = Matter.Composites, Constraint = Matter.Constraint, Events = Matter.Events, - Query = Matter.Query; - - + Query = Matter.Query, + Plugin = Matter.Plugin; + + +Matter.use('matter-gravity'); +Plugin.use(Matter, ["matter-world-wrap"]); + var engine = Engine.create(); //Bodies From 51698b21a1d0623d5a5e4cde2b930c8af5e05e61 Mon Sep 17 00:00:00 2001 From: Piotr Pietrzak Date: Wed, 31 Jan 2018 20:59:00 +0100 Subject: [PATCH 2/4] Change `Object` to `object` in Matter.use type. --- types/matter-js/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/matter-js/index.d.ts b/types/matter-js/index.d.ts index a76ee1cc51..b863d6d848 100644 --- a/types/matter-js/index.d.ts +++ b/types/matter-js/index.d.ts @@ -17,7 +17,7 @@ declare namespace Matter { * @method use * @param ...plugin {Function} The plugin(s) to install on `base` (multi-argument). */ - export function use(...plugins: (Object | string)[]): void; + export function use(...plugins: (object | string)[]): void; /** * The `Matter.Axes` module contains methods for creating and manipulating sets of axes. From a91bad190e15c01f12903467bb1f0f30feed66c4 Mon Sep 17 00:00:00 2001 From: Piotr Pietrzak Date: Wed, 31 Jan 2018 21:04:48 +0100 Subject: [PATCH 3/4] Increment @types/matter-js version. --- types/matter-js/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/matter-js/index.d.ts b/types/matter-js/index.d.ts index b863d6d848..63fd2b01d2 100644 --- a/types/matter-js/index.d.ts +++ b/types/matter-js/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Matter.js - 0.9.1 +// Type definitions for Matter.js - 0.10.0 // Project: https://github.com/liabru/matter-js // Definitions by: Ivane Gegia , // David Asmuth , From 61a6251d03669c40166d38e4937fc3d991827610 Mon Sep 17 00:00:00 2001 From: Piotr Pietrzak Date: Wed, 31 Jan 2018 21:51:19 +0100 Subject: [PATCH 4/4] Remove occurences of ": object". Fix header. --- types/matter-js/index.d.ts | 27 +++++++++++++++++---------- types/matter-js/matter-js-tests.ts | 4 ++-- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/types/matter-js/index.d.ts b/types/matter-js/index.d.ts index 63fd2b01d2..ffca8627d0 100644 --- a/types/matter-js/index.d.ts +++ b/types/matter-js/index.d.ts @@ -2,7 +2,7 @@ // Project: https://github.com/liabru/matter-js // Definitions by: Ivane Gegia , // David Asmuth , -// Piotr Pietrzak git +// Piotr Pietrzak // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped export = Matter; @@ -17,7 +17,7 @@ declare namespace Matter { * @method use * @param ...plugin {Function} The plugin(s) to install on `base` (multi-argument). */ - export function use(...plugins: (object | string)[]): void; + export function use(...plugins: (Plugin | string)[]): void; /** * The `Matter.Axes` module contains methods for creating and manipulating sets of axes. @@ -3332,6 +3332,10 @@ declare namespace Matter { | string; export class Plugin { + name: string; + version: string; + install: () => void; + for?: string; /** * Registers a plugin object so it can be resolved later by name. @@ -3339,7 +3343,7 @@ declare namespace Matter { * @param plugin {} The plugin to register. * @return {object} The plugin. */ - static register(plugin: T): T; + static register(plugin: Plugin): Plugin; /** * Resolves a dependency to a plugin object from the registry if it exists. @@ -3348,7 +3352,7 @@ declare namespace Matter { * @param dependency {string} The dependency. * @return {object} The plugin if resolved, otherwise `undefined`. */ - static resolve(dependency: string): object | undefined; + static resolve(dependency: string): Plugin | undefined; /** * Returns `true` if the object meets the minimum standard to be considered a plugin. @@ -3360,7 +3364,7 @@ declare namespace Matter { * @param obj {} The obj to test. * @return {boolean} `true` if the object can be considered a plugin otherwise `false`. */ - static isPlugin(obj: object): boolean; + static isPlugin(obj: {}): boolean; /** * Returns a pretty printed plugin name and version. @@ -3368,7 +3372,7 @@ declare namespace Matter { * @param plugin {} The plugin. * @return {string} Pretty printed plugin name and version. */ - static toString(plugin: string | object): string; + static toString(plugin: string | Plugin): string; /** * Returns `true` if `plugin.for` is applicable to `module` by comparing against `module.name` and `module.version`. @@ -3379,7 +3383,7 @@ declare namespace Matter { * @param module {} The module. * @return {boolean} `true` if `plugin.for` is applicable to `module`, otherwise `false`. */ - static isFor(plugin: object, module: object): boolean; + static isFor(plugin: Plugin, module: {name?: string, [_: string]: any}): boolean; /** * Installs the plugins by calling `plugin.install` on each plugin specified in `plugins` if passed, otherwise `module.uses`. @@ -3397,7 +3401,10 @@ declare namespace Matter { * @param module {} The module install plugins on. * @param [plugins=module.uses] {} The plugins to install on module (optional, defaults to `module.uses`). */ - static use(module: object, plugins: string[]): void; + static use( + module: {uses?: (Plugin | string)[]; [_: string]: any}, + plugins: (Plugin | string)[] + ): void; /** * Recursively finds all of a module's dependencies and returns a flat dependency graph. @@ -3407,8 +3414,8 @@ declare namespace Matter { */ static dependencies( module: Dependency, - tracked: object - ): object | string | undefined + tracked?: {[_: string]: string[]} + ): {[_: string]: string[]} | string | undefined /** * Parses a dependency string into its components. diff --git a/types/matter-js/matter-js-tests.ts b/types/matter-js/matter-js-tests.ts index bfec5afb66..3c34f91ecc 100644 --- a/types/matter-js/matter-js-tests.ts +++ b/types/matter-js/matter-js-tests.ts @@ -10,8 +10,8 @@ var Engine = Matter.Engine, Plugin = Matter.Plugin; -Matter.use('matter-gravity'); -Plugin.use(Matter, ["matter-world-wrap"]); +Matter.use('matter-attractors'); +Plugin.use(Matter, ["matter-wrap"]); var engine = Engine.create();