diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 289142d..a1b0bad 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -17,3 +17,5 @@ jobs: run: bun install - name: Build run: bun run build + - name: Test types + run: bun run test:types diff --git a/CHANGELOG.md b/CHANGELOG.md index 82d58bc..3c341d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ ## Changelog +#### v2.1.0 +- added: TimeString/TimeUnit types - duration strings passed to ms/seconds/datePlus are now type-checked +- BREAKING (types only): TS code passing plain strings (e.g. user input) must cast via `as TimeString` - runtime behavior is unchanged #### v2.0.0 - BREAKING: to allow 0, false, and '0' as valid arguments for ms, tests had to be changed. - removed: sourcemaps in dist version (additional size savings) diff --git a/README.md b/README.md index 6656a81..46c77f4 100644 --- a/README.md +++ b/README.md @@ -54,8 +54,8 @@ Use Luke's if you want the absolute fastest parsing, or itty if you want some of ## seconds/ms

- seconds(duration: string) => number
- ms(duration: string) => number
+ seconds(duration: TimeString | number) => number
+ ms(duration: TimeString | number) => number

TTL math is a maintenance nightmare. It's a pain to write, a pain to read, and when you update the math later, you'll probably forget to update the comment, causing all sorts of mayhem. @@ -76,6 +76,14 @@ seconds('2 weeks') // 1209600 ms('2 weeks') // 1209600000 ``` +Duration strings are typed as `TimeString`, so typos like `ms('2 weekz')` fail at compile time rather than silently misbehaving. If you're parsing arbitrary user input (that you've validated yourself), cast it: + +```ts +import { ms, type TimeString } from 'itty-time' + +ms(userInput as TimeString) +``` + ## duration

duration(ms: number) => string @@ -114,7 +122,7 @@ duration(3750000, { join: false }) ## datePlus

- datePlus(duration: string, from = new Date) => Date + datePlus(duration: TimeString | number, from = new Date) => Date

Sometimes you need a TTL for some point in the future, but sometimes you need the actual date. You could convert it all yourself... or use this. diff --git a/package.json b/package.json index 032cd41..6bf5105 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,7 @@ "scripts": { "dev": "bun test --watch --coverage", "test": "bun test --coverage", + "test:types": "tsc -p tsconfig.spec.json", "lint": "itty lint", "build": "itty lint && itty build --hybrid", "release": "itty release --prepare --tag --push", diff --git a/src/datePlus.spec.ts b/src/datePlus.spec.ts index baa2bda..3bac54b 100644 --- a/src/datePlus.spec.ts +++ b/src/datePlus.spec.ts @@ -1,9 +1,9 @@ import { describe, expect, it } from 'bun:test' import { datePlus } from './datePlus' -import { ms } from './ms' +import { ms, type TimeString } from './ms' describe('datePlus(duration: string, from?: Date): Date', () => { - type DatePlusTest = [duration: string] + type DatePlusTest = [duration: TimeString] const tests: DatePlusTest[] = [ ['5 seconds'], diff --git a/src/datePlus.ts b/src/datePlus.ts index 5f25c87..4645ebf 100644 --- a/src/datePlus.ts +++ b/src/datePlus.ts @@ -1,5 +1,6 @@ import { ms } from './ms' +import { type TimeString } from './lib/units' // FUNCTION: get future date from a duration string (e.g. datePlus('3 hours')) -export const datePlus = (duration: string | number, from = new Date): Date => +export const datePlus = (duration: TimeString | number, from = new Date): Date => new Date(from.getTime() + ms(duration)) diff --git a/src/duration.spec.ts b/src/duration.spec.ts index 926c88a..1d6f787 100644 --- a/src/duration.spec.ts +++ b/src/duration.spec.ts @@ -1,13 +1,13 @@ import { describe, expect, it } from 'bun:test' import { duration } from './duration' -import { ms } from './ms' +import { ms, type TimeString } from './ms' const BASE = '1.1 weeks' const EXPECTED = '1 week, 16 hours, 48 minutes' describe('duration(ms: number, options?: durationOptions)', () => { describe('reverse-parses ms (number) into a readable string', () => { - const tests = [ + const tests: { original: TimeString, parts?: number, expected?: string }[] = [ { original: BASE, expected: '1 week, 16 hours, 48 minutes' }, { original: BASE, parts: 2, expected: '1 week, 16.8 hours' }, { original: BASE, parts: 1, expected: '1.1 weeks' }, diff --git a/src/index.spec.ts b/src/index.spec.ts index 91323c2..d9e5225 100644 --- a/src/index.spec.ts +++ b/src/index.spec.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'bun:test' import * as exports from './index' -const expected = [ +const expected: (keyof typeof exports)[] = [ 'seconds', 'ms', 'duration', diff --git a/src/lib/units.ts b/src/lib/units.ts index fd5d558..419b840 100644 --- a/src/lib/units.ts +++ b/src/lib/units.ts @@ -7,6 +7,19 @@ const month = day * 30, year = day * 365.25 +export type TimeUnit = + | 'ms' + | 'millisecond' | 'milliseconds' + | 'second' | 'seconds' + | 'minute' | 'minutes' + | 'hour' | 'hours' + | 'day' | 'days' + | 'week' | 'weeks' + | 'month' | 'months' + | 'year' | 'years' + +export type TimeString = `${number}` | `${number} ${TimeUnit}` + export const units: Record = { year, month, diff --git a/src/ms.spec.ts b/src/ms.spec.ts index 39ccd48..d792ed4 100644 --- a/src/ms.spec.ts +++ b/src/ms.spec.ts @@ -1,8 +1,8 @@ import { describe, expect, it } from 'bun:test' -import { ms } from './ms' +import { ms, type TimeString } from './ms' describe('ms(duration: string): number', () => { - type MsTest = [duration: string | number, expected: number] + type MsTest = [duration: TimeString | number, expected: number] const tests: MsTest[] = [ ['1 minutes', 60 * 1000], @@ -10,11 +10,12 @@ describe('ms(duration: string): number', () => { ['2 years', 2 * 365.25 * 24 * 60 * 60 * 1000], ['321 day', 60 * 60 * 24 * 321 * 1000], ['30.5 seconds', 30.5 * 1000], - ['30.5 seconds', 30.5 * 1000], + ['30.5 seconds' as TimeString, 30.5 * 1000], // extra whitespace still parses at runtime [4001, 4001], // a number is assumed to be a number ['100', 100], // string of a number is assumed to be ms ['100 ms', 100], // can handle ms - ['100apple', NaN], // can handle ms + ['100 milliseconds', 100], // can handle milliseconds + ['100apple' as TimeString, NaN], // unparsable strings return NaN at runtime ] describe('returns number of Ms', () => { @@ -35,7 +36,7 @@ describe('ms(duration: string): number', () => { { type: 'date', value: date, returns: +date }, { type: 'false', value: false, returns: 0 }, { type: '0 (string)', value: '0', returns: 0 }, - { type: '0', value: '0', returns: 0 }, + { type: '0', value: 0, returns: 0 }, { type: 'unparsable string', value: '456apple', returns: NaN }, { type: 'object', value: {}, throws: true }, { type: 'function', value: () => {}, throws: true }, diff --git a/src/ms.ts b/src/ms.ts index d9cc1fc..3b0a634 100644 --- a/src/ms.ts +++ b/src/ms.ts @@ -1,7 +1,9 @@ -import { units } from './lib/units' +import { units, type TimeString } from './lib/units' + +export type { TimeString, TimeUnit } from './lib/units' // FUNCTION: get number of seconds from a duration string -export const ms = (duration: string | number): number => { +export const ms = (duration: TimeString | number): number => { if (!isNaN(+duration)) return +duration // @ts-ignore diff --git a/src/seconds.spec.ts b/src/seconds.spec.ts index 1bc9320..73a5104 100644 --- a/src/seconds.spec.ts +++ b/src/seconds.spec.ts @@ -1,8 +1,9 @@ import { describe, expect, it } from 'bun:test' import { seconds } from './seconds' +import { type TimeString } from './lib/units' describe('seconds(duration: string): number', () => { - type SecondsTest = [duration: string | number, expected: number] + type SecondsTest = [duration: TimeString | number, expected: number] const tests: SecondsTest[] = [ ['5 seconds', 5], diff --git a/src/seconds.ts b/src/seconds.ts index 59f8357..1001ae4 100644 --- a/src/seconds.ts +++ b/src/seconds.ts @@ -1,4 +1,5 @@ import { ms } from './ms' +import { type TimeString } from './lib/units' -export const seconds = (duration: string | number): number => +export const seconds = (duration: TimeString | number): number => ms(duration) / 1000 diff --git a/src/types.spec.ts b/src/types.spec.ts new file mode 100644 index 0000000..791748f --- /dev/null +++ b/src/types.spec.ts @@ -0,0 +1,46 @@ +import { describe, expect, it } from 'bun:test' +import { datePlus } from './datePlus' +import { ms } from './ms' +import { seconds } from './seconds' +import { type TimeString } from './lib/units' + +// The @ts-expect-error assertions below are verified by `bun run test:types`, +// since bun test does not type-check. +describe('TimeString type checking', () => { + it('accepts every format the type allows', () => { + const durations: [duration: TimeString, expected: number][] = [ + ['100', 100], + ['100 ms', 100], + ['100 millisecond', 100], + ['100 milliseconds', 100], + ['30.5 seconds', 30.5 * 1000], + ['-30 minutes', -30 * 60 * 1000], + ['1.5 hours', 1.5 * 60 * 60 * 1000], + ['1 day', 24 * 60 * 60 * 1000], + ['2 weeks', 2 * 7 * 24 * 60 * 60 * 1000], + ['3 months', 3 * 30 * 24 * 60 * 60 * 1000], + ['4 years', 4 * 365.25 * 24 * 60 * 60 * 1000], + ] + + for (const [duration, expected] of durations) { + expect(ms(duration)).toBe(expected) + expect(seconds(duration)).toBe(expected / 1000) + expect(+datePlus(duration, new Date(0))).toBe(expected) + } + }) + + it('rejects invalid durations at compile time', () => { + // @ts-expect-error - arbitrary strings are not valid durations + expect(ms('lskdjfsdlkfjsdlfkjsd')).toBeNaN() + + // @ts-expect-error - duration values must be numeric + expect(seconds('one hour')).toBeNaN() + + // unit typos silently fall back to ms at runtime - the type catches them + // @ts-expect-error - unsupported units are rejected + expect(ms('2 weekz')).toBe(2) + + // @ts-expect-error - unsupported units are rejected + expect(+datePlus('2 apples', new Date(1000))).toBe(1002) + }) +}) diff --git a/tsconfig.spec.json b/tsconfig.spec.json new file mode 100644 index 0000000..007b974 --- /dev/null +++ b/tsconfig.spec.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": true, + "types": ["bun"] + }, + "exclude": ["node_modules", "dist", "examples"], + "include": ["src"] +}