es-date-fiddler

An ES Date with nifty extensions using ES Proxy. It is programmed in a class free object oriented coding style.

See demo for examples.

What is it?

The datefiddler library by default delivers an enhanced ES-Date constructor, and a factory to create the constructor (DateXFactory). In the following we name the constructor $D.

$D is a normal ECMAScript Date constructor, without the need to use new. By using Proxy functionality one can use and/or create a localized ES-Date making a number of additional setters and getters (e.g. for arithmetic, formatting, locale awareness) available, as well as use all regular Date getters/setters/methods. So, to create a $D extended Date, instead of new Date(...) one uses $D(...).

Locaclized means that one can set (associate) the locale (e.g. de-DE) and/or timeZone identifier (e.g. Europe/Berlin) for an $D instance. Subsequently all retrieved date/time values from the instance are the values within the associated Timezone. By default an instance is associated with the local locale and timeZone identifier within the environment (browser, node) of the user.

Syntax

$D([dateOrLocale: Date | string | Array[Number] | {locale, timeZone}], [localeInfo: {locale, timeZone}])

A few examples:

const myDate = $D();
myDate.date = { year: myDate.year + 3, date: 12, month: 1 };
// one doesn't need to fill all values, the following keeps the current year of the XDate
myDate.date = { date: 12, month: 5 };
const nowInGermany = $D({locale: `de-DE`, timeZone: `Europe/Berlin`});
const aCloneInFrance = myDate.clone.relocate({locale: `fr-FR`, timeZone: `Europe/Paris`});
aCloneInFrance.locale; //=> {locale: `fr-FR`, timeZone: `Europe/Paris`}
const myDateHere = acCloneInFrance.cloneLocal;
myDateHere.locale; //=> {locale: [user environment locale], timeZone: [user environment time zone]};

Usage examples

The DEMO contains a lot of usage examples.

Import & initialize

There are three flavors of this library. One for scripts with type module (or projects with "type": "module" in package.json). One for the browser and one to use with require in NodeJS.

For each flavor, the script is (bundled and) minified. The location of the minified scripts is https://kooiinc.github.io/es-date-fiddler/Bundle

Note: earlier version of this module exported DateX. That’s still available, but may be deprecated in a later version.

NodeJS commonjs

The cjs-code exports the constructor as DateX and $D and the factory DateXFactory.

Download links:

// no package.json or "type": "commonjs" in your package.json
const $D = require("[local location of the cjs bundle]/index.bundle.cjs").$D;

// "type": "module" in your package.json:
// after download of the bundle from one of the download links
// Note: in this case you may as well use the esm import.
// See next chapter (ESM import) 
import {$D} from "[local location of the cjs bundle]/index.bundle.cjs";
/* ... */

ESM import

Import links:

import $D = from "https://kooiinc.github.io/es-date-fiddler/Bundle/index.esm.min.js";

// Note: the module also exports a factory named DateXFactory. Use it as
import {DateXFactory} from "https://kooiinc.github.io/es-date-fiddler/Bundle/index.esm.min.js";
const $D = dxFactory();
/* ... */

Browser script

The browser-code makes the constructor available as window.$D or window.DateX, and the factory as window.DateXFactory.

Import links:

<script 
  src="https://kooiinc.github.io/es-date-fiddler/Bundle/index.browser.min.js">
</script>
<script>
  const $D = window.$D;
  /* ... */
</script>

Getters and setters of $D instances

A number of getter (-methods) return the instance. These may be chained. For example:

const nextweek = $D(`2024/01/01`)
  .nextMonth
  .add(`-3 hours, 20 minutes, 5 seconds`)
  .relocate({locale: `en-AU`, timeZone: 'Australia/Darwin'})
  .format(`WD MM d yyyy hh:mmi:ss dp`); //=> 'Thursday February 1 2024 06:50:05 am'

Simple getters/setters are:

Additional getters are

Additional getter and/or setters are:

Setters to add or subtract days, years, hours etc.

The following setters use the following basic syntax for adding or subtracting things from the date at hand.

  your$D.[add/subtract](
    "[n year(s)], [n month(s)], [n week(s)], [n day(s)], 
     [n hour(s)], [n minute(s)], [n second(s)], [n millisecond(s)]"
  );

See the demo for examples.

Notes:

Instance utilities

now, validateLocale

extendWith: create additonal setters and getters for $D

One can create additional setters/getter (properties/methods) to the constructor using:

$D.extendWith({name: string, fn: Function, isMethod: boolean, proxifyResult: boolean})

The demo contains examples.

This site is open source. Improve this page.