type-fest
Version:
A collection of essential TypeScript types
50 lines (35 loc) • 2.31 kB
TypeScript
import type {ReadonlyDeep} from './readonly-deep.d.ts'; // For `@link`
import type {WritableDeep} from './writable-deep.d.ts'; // For `@link`
/**
Matches a `Date` that cannot be changed.
Use-cases:
- Type a parameter of a function that only reads a date, so the function cannot change it. The [`prefer-readonly-parameter-types`](https://typescript-eslint.io/rules/prefer-readonly-parameter-types/) lint rule flags a `Date` parameter, but accepts a `ReadonlyDate`.
- Type the return value of a function that hands out a date the caller must not change.
@example
```
import type {ReadonlyDate} from 'type-fest';
function formatDate(date: ReadonlyDate): string {
return date.toISOString().slice(0, 10);
}
declare const date: Date;
formatDate(date);
//=> string
declare const readonlyDate: ReadonlyDate;
formatDate(readonlyDate);
// @ts-expect-error -- Property 'setTime' does not exist on type 'ReadonlyDate'.
readonlyDate.setTime(0);
// Get a mutable copy when you need one.
// eslint-disable-next-line unicorn/consistent-date-clone -- A `ReadonlyDate` cannot be passed to `new Date()`.
const mutableDate = new Date(readonlyDate.getTime());
//=> Date
```
Note: A `Date` is assignable to a `ReadonlyDate`, but a `ReadonlyDate` is not assignable to a `Date`, like `ReadonlyArray` and `Array`. Code that hands a `ReadonlyDate` to a function that takes a `Date`, like most date libraries, needs `new Date(readonlyDate.getTime())`.
Note: This is only a compile-time check. The value is still a `Date` at runtime, so plain JavaScript can still change it, and `Object.freeze()` does not stop the setters. An `instanceof Date` check narrows the type back to `Date`, which brings the setters back. Use [`Temporal`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) for values that cannot be changed at runtime.
Note: It removes every `set*` method, including a setter that a project adds to `Date`.
{@link ReadonlyDeep `ReadonlyDeep`} turns a `Date` into a `ReadonlyDate`, and {@link WritableDeep `WritableDeep`} turns a `ReadonlyDate` back into a `Date`. The other `*Deep` types do not walk into a `ReadonlyDate`.
@category Object
*/
export type ReadonlyDate = {
readonly [Key in keyof Date as Key extends `set${string}` ? never : Key]: Date[Key];
};
export {};