Initial work to make plugins type-safe (typescript)

package.json

@@ -8,7 +8,7 @@
   "scripts": {
     "test": "TZ=Pacific/Auckland npm run test-tz && TZ=Europe/London npm run test-tz && npm run test-tz && jest",
     "test-tz": "jest test/timezone.test --coverage=false",
-    "lint": "./node_modules/.bin/eslint src/* test/* build/*",
+    "lint": "./node_modules/.bin/eslint src/*.js test/*.js build/*.js",
     "prettier": "prettier --write \"docs/**/*.md\"",
     "babel": "cross-env BABEL_ENV=build babel src --out-dir esm --copy-files",
     "build": "cross-env BABEL_ENV=build node build && npm run size",

src/index.d.ts

@@ -0,0 +1,114 @@
+declare const dayjs: dayjs;
+export = dayjs;
+
+declare namespace dayjs {
+  type ConfigType = string | number | Date | Dayjs
+
+  type OptionType = { locale: string }
+
+  type UnitTypeShort = 'd' | 'M' | 'y' | 'h' | 'm' | 's' | 'ms'
+  type UnitTypeSingular = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'date' | UnitTypeShort;
+  type UnitTypePlural = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'quarters' | 'years' | 'dates'
+  type UnitType = UnitTypeSingular | UnitTypePlural
+
+  type OpUnitTypeShort = 'w'
+  type OpUnitType = UnitType | "week" | OpUnitTypeShort;
+
+  type PluginFunc<TPlugin> = (option: ConfigType, dayjsClass: InstanceType<Dayjs>, dayjsFactory: dayjs) => void;
+
+  /**
+   * Branding for static plugins, to enable better type inference.
+   * `extend` from this to make the plugin static
+   */
+  interface StaticPlugin {
+    __staticPlugin: never;
+  }
+}
+
+interface dayjs<TPlugin = {}> {
+  (config?: dayjs.ConfigType, option?: dayjs.OptionType): {} extends TPlugin
+    ? Dayjs
+    : Dayjs & TPlugin;
+
+  extend<UPlugin extends object>(
+    plugin: dayjs.PluginFunc<UPlugin>,
+    option?: dayjs.ConfigType
+  ): UPlugin extends dayjs.StaticPlugin ? (dayjs<TPlugin> & UPlugin) : dayjs<TPlugin & UPlugin>;
+  locale(arg1: any, arg2?: any): string;
+  isDayjs(d: any): d is Dayjs;
+  unix(t: number): Dayjs;
+}
+
+declare interface DayjsObject {
+  years: number;
+  months: number;
+  date: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  milliseconds: number;
+}
+
+declare class Dayjs {
+  constructor(config?: dayjs.ConfigType);
+
+  clone(): Dayjs;
+
+  isValid(): boolean;
+
+  year(): number;
+
+  month(): number;
+
+  date(): number;
+
+  day(): number;
+
+  hour(): number;
+
+  minute(): number;
+
+  second(): number;
+
+  millisecond(): number;
+
+  set(unit: dayjs.UnitType, value: number): Dayjs;
+
+  add(value: number, unit: dayjs.OpUnitType): Dayjs;
+
+  subtract(value: number, unit: dayjs.OpUnitType): Dayjs;
+
+  startOf(unit: dayjs.OpUnitType): Dayjs;
+
+  endOf(unit: dayjs.OpUnitType): Dayjs;
+
+  format(template?: string): string;
+
+  diff(dayjs: ConfigType, unit: OpUnitType, float?: boolean): number
+
+  valueOf(): number;
+
+  unix(): number;
+
+  daysInMonth(): number;
+
+  toDate(): Date;
+
+  toArray(): number[];
+
+  toJSON(): string;
+
+  toISOString(): string;
+
+  toObject(): DayjsObject;
+
+  toString(): string;
+
+  isBefore(dayjs: ConfigType, unit?: OpUnitType): boolean
+
+  isSame(dayjs: ConfigType, unit?: OpUnitType): boolean
+
+  isAfter(dayjs: ConfigType, unit?: OpUnitType): boolean
+
+  locale(arg1: any, arg2?: any): Dayjs;
+}

src/plugin/advancedFormat/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigType, PluginFunc } from '../../index'
+
+interface AdvancedFormatPlugin {
+  format(advancedFormat: string): string
+}
+
+declare const pluginFn: PluginFunc<AdvancedFormatPlugin>
+export default pluginFn

src/plugin/buddhistEra/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigType, PluginFunc } from '../../index'
+
+interface BuddhistEraPlugin {
+  format(buddhistEraFormat: string): string
+}
+
+declare const pluginFn: PluginFunc<BuddhistEraPlugin>
+export default pluginFn

src/plugin/customParseFormat/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigType, PluginFunc, StaticPlugin } from '../../index'
+
+interface CustomParseFormatPlugin extends StaticPlugin {
+  (input: string, format: string): this;
+}
+
+declare const pluginFn: PluginFunc<CustomParseFormatPlugin>;
+export default pluginFn

src/plugin/isBetween/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigType, PluginFunc, UnitType } from '../../index'
+
+interface IsBetweenPlugin {
+  isBetween(d1: ConfigType, d2: ConfigType, unit: UnitType): boolean;
+}
+
+declare const pluginFn: PluginFunc<IsBetweenPlugin>
+export default pluginFn

src/plugin/isLeapYear/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigType, PluginFunc } from '../../index'
+
+interface IsLeapYearPlugin {
+  isLeapYear(): boolean
+}
+
+declare const pluginFn: PluginFunc<IsLeapYearPlugin>
+export default pluginFn

src/plugin/relativeTime/index.d.ts

@@ -0,0 +1,11 @@
+import { ConfigType, PluginFunc } from '../../index'
+
+interface RelativeTimePlugin {
+  fromNow(withoutSuffix?: boolean): string
+  from(compared: ConfigType, withoutSuffix?: boolean): string
+  toNow(withoutSuffix?: boolean): string
+  to(compared: ConfigType, withoutSuffix?: boolean): string
+}
+
+declare const pluginFn: PluginFunc<RelativeTimePlugin>
+export default pluginFn

test/index.d.test.ts → test/index.test.d.ts

@@ -1,4 +1,10 @@
 import dayjs from '../src'
+import relativeTime from '../src/plugin/relativeTime'
+import advancedFormat from '../src/plugin/advancedFormat'
+import buddhistEra from '../src/plugin/buddhistEra'
+import isLeapYear from '../src/plugin/isLeapYear'
+import isBetween from '../src/plugin/isBetween'
+import customParseFormat from '../src/plugin/customParseFormat'
 
 dayjs()
 
@@ -76,4 +82,15 @@ dayjs().isSame(dayjs(), 'hours')
 
 dayjs().isAfter(dayjs(), 'year')
 
-dayjs('2000-01-01').isLeapYear()
+dayjs.extend(relativeTime)().toNow()
+dayjs.extend(advancedFormat)().format()
+dayjs.extend(buddhistEra)().format()
+dayjs.extend(isLeapYear)('2000-01-01').isLeapYear()
+dayjs.extend(isBetween)('2010-10-20').isBetween('2010-10-19', dayjs('2010-10-25'), 'year')
+
+const multiplePluginsDayjs = dayjs.extend(relativeTime).extend(isLeapYear)()
+multiplePluginsDayjs.toNow()
+multiplePluginsDayjs.isLeapYear()
+
+const dayjsWithCustomParseFormat = dayjs.extend(customParseFormat);
+dayjsWithCustomParseFormat('05/02/69 1:02:03 PM -05:00', 'MM/DD/YY H:mm:ss A Z');

test/plugins.test.js

@@ -0,0 +1,23 @@
+import MockDate from 'mockdate'
+import dayjs from '../src'
+import relativeTime from '../src/plugin/relativeTime'
+import isLeapYear from '../src/plugin/isLeapYear'
+
+beforeEach(() => {
+  MockDate.set(new Date())
+})
+
+afterEach(() => {
+  MockDate.reset()
+})
+
+it('should allow multiple plugin chaining', () => {
+  const now = dayjs()
+  expect(now.fromNow).not.toBeDefined()
+  expect(now.isLeapYear).not.toBeDefined()
+
+  const extendedDayjs = dayjs.extend(relativeTime).extend(isLeapYear)
+  const extendedNow = extendedDayjs()
+  expect(typeof extendedNow.fromNow).toBe('function')
+  expect(typeof extendedNow.isLeapYear).toBe('function')
+})