Package Exports

@solid-primitives/date
@solid-primitives/date/dist/index.cjs
@solid-primitives/date/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@solid-primitives/date) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@solid-primitives/date

Collection of reactive primitives and utility functions, providing easier ways to deal with dates in SolidJS.

createDate - Creates a reactive Date signal.
createDateNow - Creates an autoupdating and reactive new Date().
createTime - Creates a reactive timestamp number signal.
createTimeDifference - Provides a reactive time difference (in ms) signal.
createTimeDifferenceFromNow - Provides a autoupdating, reactive time difference (in ms) from now as a signal.
createTimeAgo - Provides a reactive, formatted, autoupdating date difference in relation to now.
createCountdown - Provides a reactive broken down time remaining Store.
createCountdownFromNow - Provides a reactive, autoupdating (from now), broken down "time remaining" as a Store.
+ some non-reactive date-related utility functions.

Note: This package consolidates date-related primitives formerly contained countdown and date-diff.

Installation

npm install @solid-primitives/date
# or
yarn add @solid-primitives/date

Reactive Primitives:

`createDate`

Creates a reactive Date signal.

const [date, setDate] = createDate(1641408329089);

date(); // T: Date

setDate("2020 1 11");

// passed initial value can be reactive
const [timestamp, setTimestamp] = createSignal(1641408329089);
const [date, setDate] = createDate(timestamp);

setTimestamp(1341708325070); // will update the date

`createDateNow`

Creates an autoupdating and reactive new Date().

import { createDateNow } from "@solid-primitives/date";

// updates every second:
const [now] = createDateNow(1000);

// won't autoupdate:
const [now, update] = createDateNow(false);

// update manually:
update();

`createTime`

Creates a reactive timestamp number signal.

const [time, setTime] = createTime("2020 1 11");

time(); // T: number

setDate(1641408329089);

// passed initial value can be reactive
const [date, setDate] = createSignal("2020 1 11");
const [time, setTime] = createTime(date);

setTimestamp("2021 5 23"); // will update the time

`createTimeDifference`

Provides a reactive time difference (in ms) signal.

// the arguments can be reactive
const [target, setTarget] = createSignal(1641408329089);
const [diff, { from, to }] = createTimeDifference("2020 1 11", target);
diff(); // T: number
from(); // T: Date
to(); // T: Date

`createTimeDifferenceFromNow`

Provides a autoupdating, reactive time difference (in ms) from now as a signal.

const [target, setTarget] = createSignal(1641408329089);
const [diff, { target, now, update }] = createTimeDifferenceFromNow(target);
diff(); // T: number
target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// you can pass a custom interval (number or function or false)
createTimeDifferenceFromNow(target, diff => (diff > 100000 ? 30000 : 1000));

`createTimeAgo`

Provides a reactive, formatted date difference in relation to now.

import { createTimeAgo, createDate } from "@solid-primitives/date";

const [myDate, setMyDate] = createDate("Jun 28, 2021");
const [timeago, { target, now, update, difference }] = createTimeAgo(myDate);
// => 5 months ago

timeago(); // => 5 months ago
difference(); // T: number
target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// use custom libraries to change formatting:
import { formatRelative } from "date-fns";
const [timeago] = createTimeAgo(1577836800000, {
  min: 10000,
  interval: 30000,
  relativeFormatter: (target, now) => formatRelative(target, now)
});
// => last Monday at 9:25 AM

`createCountdown`

Provides a reactive broken down time remaining Store.

const [to, setTo] = createSignal(1641408329089);
const countdown = createCountdown("2020 1 11", to);

countdown.minutes; // e.g. 5
countdown.hours; // e.g. 1
countdown.seconds; // e.g. 48

`createCountdownFromNow`

Provides a reactive, autoupdating (from now), broken down "time remaining" as a Store.

// target date may be reactive
const [to, setTo] = createSignal(1641408329089);
const [countdown, { now, target, update }] = createCountdownFromNow(to);

countdown.minutes; // e.g. 5
countdown.hours; // e.g. 1
countdown.seconds; // e.g. 48

target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// you can pass a custom interval (number or function or false)
createCountdownFromNow(to, diff => (diff > 100000 ? 30000 : 1000));

Utility Functions

`getDate`

/**
 * @param init timestamp `number` | date `string` | `Date` instance
 * @returns `Date` instance
 */
const getDate = (init: DateInit): Date

`getTime`

/**
 * @param init timestamp `number` | date `string` | `Date` instance
 * @returns timestamp `number`
 */
const getTime = (init: DateInit): number

`getDateDifference`

Get the time difference between two dates [ms]

const getDateDifference = (from: Date, to: Date): number

`getCountdown`

Provides broken down time remaining from a time difference.

/**
 * @param difference time difference between two dates *[ms]*
 * @returns countdown object with keys: `days`, `hours`, `minutes`, etc.
 */
const getCountdown = (difference: number): Countdown

`formatDate`

Apply basic formatting to a Date instance.

const formatDate = (date: Date): string

// example
const date = new Date("2020 1 11")
formatDate(date) // => '2020-01-10'

`formatDateRelative`

Applies relative time formatting based on a time difference from now.

/**
 * @param difference time difference between a date and now *[ms]*
 * @param messages custom messages for changing formatting
 * @returns formatted string, e.g. *"2 seconds ago"*, *"in 3 weeks"*...
 */
function formatDateRelative(difference: number, messages?: Partial<RelativeFormatMessages>): string;

Demo

https://codesandbox.io/s/solid-date-hjxui?file=/index.tsx

Changelog

Expand Changelog

0.0.100

Initial release as a Stage-0 package.

1.0.0

Stage-2 realease.

1.0.2

Updated build process and documentation.

1.1.0

Rename to date, merge with countdown, refactor primitives to split them into smaller functions.

Acknowledgement

VueUse — useTimeAgo