feat: add type declerations

.lintstagedrc.js

@@ -1,7 +1,8 @@
 module.exports = {
-  "*.md,!test/**/*.md": [
-    filenames => filenames.map(filename => `remark ${filename} -qfo`)
+  '*.md,!test/**/*.md': [
+    (filenames) => filenames.map((filename) => `remark ${filename} -qfo`)
   ],
   'package.json': 'fixpack',
-  '*.js': 'xo --fix'
+  '*.js': 'xo --fix',
+  '*.ts': 'xo --fix'
 };

package.json

@@ -41,10 +41,13 @@
     "@commitlint/config-conventional": "latest",
     "@goto-bus-stop/envify": "^5.0.0",
     "@sinonjs/fake-timers": "^8.1.0",
+    "@types/node": "^14.0.0",
+    "@types/safe-timers": "^1.1.0",
     "ava": "latest",
     "codecov": "latest",
     "cross-env": "latest",
     "delay": "^5.0.0",
+    "dtslint": "^4.2.0",
     "eslint": "^8.2.0",
     "eslint-config-xo-lass": "latest",
     "eslint-plugin-compat": "^3.13.0",
@@ -64,7 +67,8 @@
     "node": ">= 12.11.0"
   },
   "files": [
-    "src"
+    "src",
+    "types/index.d.ts"
   ],
   "homepage": "https://github.com/breejs/bree",
   "husky": {
@@ -156,6 +160,7 @@
   ],
   "license": "MIT",
   "main": "src/index.js",
+  "types": "types",
   "publishConfig": {
     "access": "public"
   },
@@ -171,8 +176,9 @@
     "lint:md": "remark . -qfo",
     "nyc": "cross-env NODE_ENV=test nyc ava",
     "pretest": "yarn run lint",
-    "test": "cross-env NODE_ENV=test ava",
-    "test-coverage": "cross-env NODE_ENV=test nyc yarn run test"
+    "test": "yarn run ava && yarn run dtslint",
+    "test-coverage": "cross-env NODE_ENV=test nyc yarn run test",
+    "dtslint": "cross-env NODE_ENV=test dtslint types"
   },
   "xo": {
     "prettier": true,
@@ -204,7 +210,29 @@
         "rules": {
           "unicorn/no-process-exit": "off"
         }
+      },
+      {
+        "files": [
+          "*.ts"
+        ],
+        "parserOptions": {
+          "project": [
+            "types/tsconfig.json"
+          ]
+        }
+      },
+      {
+        "files": [
+          "types/tests.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/no-unused-vars": "off",
+          "@typescript-eslint/no-empty-function": "off",
+          "@typescript-eslint/no-unsafe-assignment": "off",
+          "@typescript-eslint/no-unsafe-call": "off"
+        }
       }
-    ]
+    ],
+    "parser": "@typescript-eslint/parser"
   }
 }

types/index.d.ts

@@ -0,0 +1,113 @@
+// Definitions by: Taylor Schley <https://github.com/shadowgate15>
+
+import { EventEmitter } from 'node:events';
+import { WorkerOptions, Worker } from 'node:worker_threads';
+import { Timeout, Interval } from 'safe-timers';
+
+export = Bree;
+
+declare class Bree extends EventEmitter {
+  config: Bree.BreeConfigs;
+
+  closeWorkerAfterMs: Record<string, unknown>;
+  workers: Record<string, Worker>;
+  timeouts: Record<string, Timeout>;
+  intervals: Record<string, Interval>;
+
+  isSchedule: (value: any) => boolean;
+  getWorkerMetadata: (
+    name: string,
+    meta?: Record<string, unknown>
+  ) => Record<string, unknown>;
+
+  run: (name?: string) => void;
+
+  start: (name?: string) => void;
+  stop: (name?: string) => Promise<void>;
+  add: (
+    jobs:
+      | string
+      | (() => void)
+      | Bree.JobOptions
+      | Array<string | (() => void) | Bree.JobOptions>
+  ) => void;
+
+  remove: (name: string) => Promise<void>;
+
+  removeSafeTimer: (type: string, name: string) => void;
+
+  validateJob: (
+    job: string | (() => void) | Bree.JobOptions,
+    i: number,
+    names: string[],
+    config: Bree.BreeOptions
+  ) => void;
+
+  getName: (job: string | Record<string, unknown> | (() => void)) => string;
+
+  getHumanToMs: (_value: string) => number;
+  parseValue: (
+    value: boolean | string | number | Record<string, unknown>
+  ) => number | boolean | Record<string, unknown>;
+
+  createWorker: (filename: string, options: Partial<WorkerOptions>) => Worker;
+
+  constructor(config?: Bree.BreeOptions);
+}
+
+declare namespace Bree {
+  interface JobOptions {
+    name?: string;
+    path?: string | (() => void);
+    timeout?: number | string | boolean;
+    interval?: number | string;
+    date?: Date;
+    cron?: string;
+    hasSeconds?: boolean;
+    cronValidate?: Record<string, unknown>;
+    closeWorkerAfterMs?: number;
+    worker?: Partial<WorkerOptions>;
+    outputWorkerMetadate?: boolean;
+    timezone?: string;
+  }
+
+  interface BreeConfigs {
+    logger: Record<string, unknown>;
+    root: string | boolean;
+    timeout: number | boolean;
+    interval: number;
+    timezone: string;
+    jobs: Array<string | (() => void) | JobOptions>;
+    hasSeconds: boolean;
+    cronValidate: Record<string, unknown>;
+    closeWorkerAfterMs: number;
+    defaultExtension: string;
+    acceptedExtensions: string[];
+    worker: WorkerOptions;
+    errorHandler?: (error: any, workerMetadata: any) => void;
+    workerMessageHandler?: (message: any, workerMetadata: any) => void;
+    outputWorkerMetadate: boolean;
+  }
+
+  interface BreeOptions {
+    logger?: Record<string, unknown>;
+    root?: string | boolean;
+    timeout?: number | boolean;
+    interval?: number;
+    timezone?: string;
+    jobs?: Array<string | (() => void) | JobOptions>;
+    hasSeconds?: boolean;
+    cronValidate?: Record<string, unknown>;
+    closeWorkerAfterMs?: number;
+    defaultExtension?: string;
+    acceptedExtensions?: string[];
+    worker?: WorkerOptions;
+    errorHandler?: (error: any, workerMetadata: any) => void;
+    workerMessageHandler?: (message: any, workerMetadata: any) => void;
+    outputWorkerMetadate?: boolean;
+  }
+
+  type PluginFunc<T = unknown> = (options: T, c: typeof Bree) => void;
+
+  function extend<T = unknown>(plugin: PluginFunc<T>, options?: T): Bree;
+}

types/tests.ts

@@ -0,0 +1,171 @@
+import * as path from 'node:path';
+
+import * as Bree from 'bree';
+
+Bree.extend((o, b) => {}, {});
+
+const fn = () => {};
+
+(async () => {
+  const bree = new Bree({
+    logger: console,
+
+    jobs: [
+      // runs `./jobs/foo.js` on start
+      'foo',
+
+      // run fn function on start
+      fn,
+
+      // runs `./jobs/foo-bar.js` on start
+      {
+        name: 'foo-bar'
+      },
+
+      // runs `./jobs/some-other-path.js` on start
+      {
+        name: 'beep',
+        path: path.join(__dirname, 'jobs', 'some-other-path')
+      },
+
+      // runs `./jobs/worker-1.js` on the last day of the month
+      {
+        name: 'worker-1',
+        interval: 'on the last day of the month'
+      },
+
+      // runs `./jobs/worker-2.js` every other day
+      {
+        name: 'worker-2',
+        interval: 'every 2 days'
+      },
+
+      // runs `./jobs/worker-3.js` at 10:15am and 5:15pm every day except on Tuesday
+      {
+        name: 'worker-3',
+        interval: 'at 10:15 am also at 5:15pm except on Tuesday'
+      },
+
+      // runs `./jobs/worker-4.js` at 10:15am every weekday
+      {
+        name: 'worker-4',
+        cron: '15 10 ? * *'
+      },
+
+      // runs `./jobs/worker-5.js` on after 10 minutes have elapsed
+      {
+        name: 'worker-5',
+        timeout: '10m'
+      },
+
+      // runs `./jobs/worker-6.js` after 1 minute and every 5 minutes thereafter
+      {
+        name: 'worker-6',
+        timeout: '1m',
+        interval: '5m'
+        // this is unnecessary but shows you can pass a Number (ms)
+        // interval: ms('5m')
+      },
+
+      // runs `./jobs/worker-7.js` after 3 days and 4 hours
+      {
+        name: 'worker-7',
+        // this example uses `human-interval` parsing
+        timeout: '3 days and 4 hours'
+      },
+
+      // runs `./jobs/worker-8.js` at midnight (once)
+      {
+        name: 'worker-8',
+        timeout: 'at 12:00 am'
+      },
+
+      // runs `./jobs/worker-9.js` every day at midnight
+      {
+        name: 'worker-9',
+        interval: 'at 12:00 am'
+      },
+
+      // runs `./jobs/worker-10.js` at midnight on the 1st of every month
+      {
+        name: 'worker-10',
+        cron: '0 0 1 * *'
+      },
+
+      // runs `./jobs/worker-11.js` at midnight on the last day of month
+      {
+        name: 'worker-11',
+        cron: '0 0 L * *'
+      },
+
+      // runs `./jobs/worker-12.js` at a specific Date (e.g. in 3 days)
+      {
+        name: 'worker-12',
+        date: new Date()
+      },
+
+      // runs `./jobs/worker-13.js` on start and every 2 minutes
+      {
+        name: 'worker-13',
+        interval: '2m'
+      },
+
+      // runs `./jobs/worker-14.js` on start with custom `new Worker` options (see below)
+      {
+        name: 'worker-14',
+        // <https://nodejs.org/api/worker_threads.html#worker_threads_new_worker_filename_options>
+        worker: {
+          workerData: {
+            foo: 'bar',
+            beep: 'boop'
+          }
+        }
+      },
+
+      // runs `./jobs/worker-15.js` **NOT** on start, but every 2 minutes
+      {
+        name: 'worker-15',
+        timeout: false, // <-- specify `false` here to prevent default timeout (e.g. on start)
+        interval: '2m'
+      },
+
+      // runs `./jobs/worker-16.js` on January 1st, 2022
+      // and at midnight on the 1st of every month thereafter
+      {
+        name: 'worker-16',
+        date: new Date(),
+        cron: '0 0 1 * *'
+      }
+    ]
+  });
+  // start only a specific job:
+  bree.start('foo');
+
+  // stop all jobs
+  await bree.stop();
+
+  // stop only a specific job:
+  await bree.stop('beep');
+
+  // run all jobs (this does not abide by timeout/interval/cron and spawns workers immediately)
+  bree.run();
+
+  // run a specific job (...)
+  bree.run('beep');
+
+  // add a job array after initialization:
+  bree.add(['boop']);
+  // this must then be started using one of the above methods
+
+  // add a job after initialization:
+  bree.add('boop');
+  // this must then be started using one of the above methods
+
+  bree.add(fn);
+
+  // remove a job after initialization:
+  await bree.remove('boop');
+
+  // createWorker check
+  bree.createWorker('testFile', {});
+})();

types/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "types": [],
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "baseUrl": "../",
+    "paths": {
+      "bree": ["."]
+    },
+    "moduleResolution": "node"
+  },
+  "include": ["src"]
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rule": {
+    "semicolon": true,
+    "indent": [true, "spaces", 2]
+  }
+}