bjuppa / com-plain-date Goto Github PK

The functions that navigate from a plain-date to another are currently named with the add prefix, but they don't really "add" per se, they can also subtract if the argument is negative.

Would it make sense to change their prefix to jump, e.g. jumpDays?

Does "jump" sound to silly? I think navigate is too long and move is a bit boring.

• addBusinessDays
• addDays
• addMonths
• addQuarters
• addYears

...but not addTime, because it actually does move specifically forward and has a reverse function subtractTime.

(also, it seems ExPlainDate only has 4 of those navigators... addQuarters is missing)

This could go among the guiding principles in docs. It's because I think abbreviations in caps makes the function name harder to read when mixed between two other words. And our interfaces only have toJSON that has only one word!

Also explain that Date's toISOString is rarely used in userland code so would just bloat the ComPlainDate objects that already have the iso property.

The docs look weird for some function parameters with default values, for example:

This command can give an indication of how many functions are affected: deno doc mod.ts --json | grep -c 'UNSUPPORTED' giving a count of 40 at the time of writing.

Add utilities for getting the week-number of a calendar date:

weekNumber: 1-52
weekNumberISO: 1-53

See https://en.wikipedia.org/wiki/ISO_week_date#Algorithms

Also add methods to ExtendedPlainDate.

It could be useful to provide utils for directly truncating minutes relative full hours directly on JS Date objects, and it's easy to forget that it requires a timezone to do correctly... ;)

ComPlainDate could help developers by directly providing:

• startOfHour(timezone: string)(instant: Date): Date
• startOfDay(timezone: string)(instant: Date): Date

...and perhaps also:

• truncateToHalfHour
• truncateToThirdOfHour
• truncateToQuarterOfHour
• truncateToSixthOfHour
• truncateToTwelfthOfHour

Some quick ideas:

• differenceInHours(from: Date)(to: Date): number
• differenceInMinutes(from: Date)(to: Date): number
• differenceInSeconds(from: Date)(to: Date): number
• differenceAsDuration(timezone: string)(from: Date)(to: Date): Duration

isInPeriod(start: Date)(end: Date)(instant: Date): boolean

Sort start & end, apply closed start & open ending.

The PlainDateFactory interface requires a type-lift function (of) that is meant to be a reference back to the function itself.

I suspect that the self-reference prevents any such function (and it's dependencies) from being tree-shaken in a production build 🙀

Investigate if we can drop the type-lift from the interface and the implementations!

The generated docs have trouble picking up the parameter names when destructuring function parameters. This function declaration:

export function isLeapYear({ year }: SloppyDate): boolean { ... }

...looks like this in docs:

isLeapYear(unnamed 0: SloppyDate): boolean

Searching for }: in the codebase reveals the problematic functions, in 16 files at the time of writing.

In preparation for Duration objects, we should already start using plural property names, like hours, minutes, etc in objects not describing a time-of-day.

These are the relevant functions that need new signatures:

• tallyMilliseconds
• addTime & subtractTime
• timezoneOffsetParts

Also, add this as a guiding principle in the readme, and cut down on the existing object shape principle.

The npm package is currently missing a README file: https://www.npmjs.com/package/complaindate

https://docs.npmjs.com/about-package-readme-files

We should make sure that the build script https://github.com/bjuppa/com-plain-date/blob/main/scripts/build_npm.ts takes that into account!

Our localTimezone() function returns unexpected short form timezone names (e.g. "CET") on some systems. This breaks our tests for localTimezone as well as safeTimezone on those systems.

Seen with Deno 1.39.0 on macOS 14.2

The underlying call is Intl.DateTimeFormat()?.resolvedOptions()?.timeZone

There are no options affecting returned timeZone, so my suggestion is that we rewrite localTimezone to fallback to returning UTC whenever no / can be found in reported timeZone. The short form will not be useful for the UI anyway, for example the short forms will not be available in a dropdown.

We should set up a GitHub Action so that the npm package is built and published when tagging a release:

https://github.com/denoland/dnt#github-actions---npm-publish-on-tag

Plain-date and plain-time objects can be compared with <, >=, etc... but not for equality with == because of JS objects, duh.

It'd still be useful to compare them for equality though.

The simplest way would be an is(date: ComPlainDate): bool method that checks that all three properties are equal.

Next level would be isMatch(pattern: { year?: number | string, month?: number | string, day?: number | string }): bool that would return true when just the given properties match.

Having the latter makes the first one redundant. Would it make sense to implement the latter but calling it simply is, or would that be a confusing name?

If we start with a generator, we can use that to create some nifty range- and sequence-related functions:

• plainDateGenerator(next: (x: PlainDate) => PlainDate)(first: PlainDate): Iterable<PlainDate>
• plainDateRange(days: number)(first: PlainDate): PlainDate[] (days may be negative!)
• plainDatesBetween(first: PlainDate)(last: PlainDate): PlainDate[]
• firstPlainDate(predicate: (x: PainDate) => boolean))(sequence: Iterable<PlainDate>): PlainDate | undefined

See https://github.com/tc39/proposal-iterator-helpers

Create factory function Duration for duration objects (time-period, span, stretch), like 3 days, 4 hours, 25 minutes.

Some resolution units to consider, each can be negative, at least one needs to be given:

Time-level:

• milliseconds
• seconds
• minutes
• hours

Days-level:

• days
• weeks

Months-level:

• months
• quarters
• years
• decades
• centuries
• millennia

Upon object creation, normalize / balance to the largest given unit within each level.

Properties and methods:

• iso
• toString() => iso
• toJson() => iso
• valueOf() => number tally milliseconds
• is(other: Duration) => boolean equality check
• round() => Duration
• rescale(shape: SloppyDuration) => Duration
• add(duration: Duration): Duration
• subtract(duration: Duration): Duration
• asHours(), asDays(), etc

Use Intl number format to localise strings using units. See how Luxon does this!
Check Temporal for balancing https://tc39.es/proposal-temporal/docs/balancing.html and compare that to Luxon's round, rescale & shift!

When using <input type="datetime-local"> it's quite common to go straight from and to JS Date. We could provide some utils to help:

• datetimeLocalToInstant(timezone: string)(datetimeLocal: string): Date
• instantToDatetimeLocal(timezone: string)(instant: Date): string

"Package does not specify a list of contributors or an author in package.json."

See https://socket.dev/npm/package/complaindate/issues/1.0.0