diff --git a/types/screeps-profiler/index.d.ts b/types/screeps-profiler/index.d.ts new file mode 100644 index 0000000000..6ce153c7de --- /dev/null +++ b/types/screeps-profiler/index.d.ts @@ -0,0 +1,132 @@ +// Type definitions for screeps-profiler 1.2 +// Project: https://github.com/gdborton/screeps-profiler +// Definitions by: Casey Link +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +/** + * The Screeps Profiler is a library that helps to understand where your CPU is being spent in + * the game of Screeps. + * It works by monkey patching functions on the Global game object prototypes, with a function that + * record how long each function takes. The primary benefit of using this profiler is that you can + * get a clear picture of where your CPU is being used over time, and optimize some of the heavier functions. + * While it works best for players that heavily employ prototypes in their code, it should work + * to some degree for all players. + * + * Any modules that you use that modify the game's prototypes should be imported + * before you require the profiler. + * + * @see More information at https://github.com/gdborton/screeps-profiler + */ +interface ScreepsGameProfiler { + /** + * Will run for the given number of ticks then will output the gathered information to the console. + * + * @param {number} ticks - controls how long the profiler should run before stopping + * @param {string} [functionFilter] - parameter will limit the scope of the profiler to a specific function name + */ + profile(ticks: number, functionFilter?: string): void; + + /** + * Will run for the given number of ticks, and will output the gathered information each tick to + * the console. The can sometimes be useful for seeing spikes in performance. + * + * @param {number} ticks - controls how long the profiler should run before stopping + * @param {string} [functionFilter] - parameter will limit the scope of the profiler to a specific function name + */ + stream(ticks: number, functionFilter?: string): void; + + /** + * This will run for the given number of ticks, and will email the output to your registered + * Screeps email address. Very useful for long running profiles. + * + * @param {number} ticks - controls how long the profiler should run before stopping + * @param {string} [functionFilter] - parameter will limit the scope of the profiler to a specific function name + */ + email(ticks: number, functionFilter?: string): void; + + /** + * This will run indefinitely, and will only output data when the output console command is run. + * Very useful for long running profiles with lots of function calls. + * + * @param {string} [functionFilter] - parameter will limit the scope of the profiler to a specific function name + */ + background(functionFilter?: string): void; + + /** + * Print a report based on the current tick. The profiler will continue to operate normally. + * This is currently the only way to get data from the background profile. + * + * @param {number} [lineCount=20] the number of lines to output + */ + output(lineCount?: number): void; + + /** + * Stops the profiler and resets its memory. This is currently the only way to stop a background profile. + */ + reset(): void; + + /** + * Restarts the profiler using the same options previously used to start it. + */ + restart(): void; +} + +interface ScreepsProfilerStatic { + /** + * This line monkey patches the global prototypes. Should be called before and outside your main loop. + */ + enable(): void; + + /** + * Wrap your main loop with this function. + * + * @param {function} callback - your main loop function + */ + // tslint:disable-next-line ban-types + wrap(callback: Function): Function; + + /** + * Register a class to be profiled. Each of the functions on this class will be replaced with + * a profiler wrapper + * @param {Object} clazz constructor + * @param {string} className - The name of the class, a label used in output + */ + // tslint:disable-next-line ban-types + registerClass(constructor: Function, className: string): void; + + /** + * Each of the functions on this object will be replaced with a profiler wrapper. + * @param {Object} object + * @param {string} objectName - Name of the object, a label used in output + */ + registerObject(object: any, objectName: string): void; + + /** + * Wraps a function for profiling, returns the wrapped function. + * + * Be sure to reassign the function, we can't alter functions that are passed. + * + * The second param is optional if you pass a named function function x() {}, but required if + * you pass an anonymous function var x = function(){}. + * + * @param {string} [fnName] - Name of the function, used as a label in output + * @return {function} the original function wrapped for profiling + */ + // tslint:disable-next-line ban-types + registerFN(fn: Function, fnName?: string): Function; +} + +declare global { + /** + * screeps-profiler extends the Game interface with itself + * @see http://docs.screeps.com/api/#Game + */ + interface Game { + profiler: ScreepsGameProfiler; + } + var Game: Game; +} + +declare var profiler: ScreepsProfilerStatic; + +export = profiler; diff --git a/types/screeps-profiler/screeps-profiler-tests.ts b/types/screeps-profiler/screeps-profiler-tests.ts new file mode 100644 index 0000000000..bae26d3e91 --- /dev/null +++ b/types/screeps-profiler/screeps-profiler-tests.ts @@ -0,0 +1,42 @@ +import profiler = require("screeps-profiler"); + +function testFunction() { +} + +class TestClass { + private dummy: string; +} + +const testObj = { + foo() { + }, +}; + +profiler.enable(); +profiler.wrap(testFunction); +profiler.registerClass(TestClass, "TestClass"); +profiler.registerObject(testObj, "testObj"); +profiler.registerFN(testFunction); +profiler.registerFN(testFunction, "testFunction"); + +const ticks: number = 100; +const filterName: string = "test"; + +Game.profiler.profile(ticks); +Game.profiler.profile(ticks, filterName); + +Game.profiler.stream(ticks); +Game.profiler.stream(ticks, filterName); + +Game.profiler.email(ticks); +Game.profiler.email(ticks, filterName); + +Game.profiler.background(); +Game.profiler.background(filterName); + +Game.profiler.output(); +Game.profiler.output(100); + +Game.profiler.reset(); + +Game.profiler.restart(); diff --git a/types/screeps-profiler/tsconfig.json b/types/screeps-profiler/tsconfig.json new file mode 100644 index 0000000000..4334877022 --- /dev/null +++ b/types/screeps-profiler/tsconfig.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "screeps-profiler-tests.ts" + ] +} diff --git a/types/screeps-profiler/tslint.json b/types/screeps-profiler/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/screeps-profiler/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }