TypeScript signatures in the documentation

[rauschma]

This seems to be the most common pattern for “like” objects:

zonedDateTime.with(zonedDateTimeLike: object | string, options?: object) : Temporal.ZonedDateTime
date.with(dateLike: object | string, options?: object) : Temporal.PlainDate
time.with(timeLike: object | string, options?: object) : Temporal.PlainTime
datetime.with(dateTimeLike: object | string, options?: object) : Temporal.PlainDateTime

Occasionally, parameter names and/or types diverge from this pattern:

yearMonth.with(yearMonthLike: object, options?: object) : Temporal.PlainYearMonth
zonedDateTime.add(duration: object, options?: object) : Temporal.ZonedDateTime
yearMonth.add(duration: Temporal.Duration | object | string, options?: object) : Temporal.PlainYearMonth
Temporal.Duration.from(thing: any) : Temporal.Duration
duration.with(durationLike: object) : Temporal.Duration

I’d prefer a more precise type because that makes the concept of “likeness” completely clear. But that may be too verbose for this documentation:

type ZonedDateTimeProps = {
  timeZone: string,
  year: number,
  month: number,
  day: number,
  hour: number,
  // Etc.
};
type ZonedDateTimeLike = Temporal.ZonedDateTime | ZonedDateTimeProps | string;

This is a nitpick, but the instance names are derived differently:

• Temporal.ZonedDateTime → zonedDateTime.year
• Temporal.PlainDateTime → datetime.year
• Temporal.PlainYearMonth → yearMonth.year

[nikeee]

The current index.d.ts of the polyfill does this and defines them like so:

proposal-temporal/polyfill/index.d.ts

Lines 1318 to 1332 in 51310e4

	export type ZonedDateTimeLike = {
	year?: number;
	month?: number;
	monthCode?: string;
	day?: number;
	hour?: number;
	minute?: number;
	second?: number;
	millisecond?: number;
	microsecond?: number;
	nanosecond?: number;
	offset?: string;
	timeZone?: TimeZoneProtocol | string;
	calendar?: CalendarProtocol | string;
	};

TS offers the ability to derive types, so a Partial<T> could be used to derive a new type from T that has all fields optional (if there exists a type that could be used, we could to this instead of defining a new interface).

[ptomato]

Thanks for the report! To be honest, I've always considered the types in the documentation to be "TypeScript-ish", rather than correct TypeScript, in the sense that the docs use a fairly well-known syntax to indicate the types, but the text clarifies things that would otherwise be verbose to express in the type syntax. So, you're correct that it is a bit sloppy. This we probably wouldn't fix, because the documentation is migrating to MDN (see #1449) and they don't use this TypeScript-ish notation anyway.

I believe the discrepancy with strings is a bug, see #1422.

The instance names are probably a holdover from when the types were named Temporal.DateTime etc. Pull requests to fix this are welcome.

[justingrant]

I believe the discrepancy with strings is a bug, see #1422.

@rauschma @nikeee - We'll eventually get around to fixing things like this, but in the meantime documentation PRs are always welcome! ;-)

[ptomato]

Going to close this; to me it seems like a matter of taste whether the names of the this-objects are more concise or more similar to the class name, and this will probably be edited anyway if the docs ever get onto MDN.

Anyone should still feel free to reopen this and submit a PR to the docs if they feel like doing the work; it's just that I'm not intending to do it.