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 {};