vue-use-date-format 1.0.1

package/README.github.md

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="banner.svg" alt="vue-use-date-format" width="100%" />
+</p>
+
+<h1 align="center">vue-use-date-format</h1>
+
+<p align="center">A Vue 3 composition API utility for formatting dates reactively using format tokens (YYYY, MM, DD, HH, mm, ss, etc.). Supports localization and custom meridiem.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/v/vue-use-date-format.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/dm/vue-use-date-format.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/vuefrag/vue-use-date-format/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vue-use-date-format.svg" alt="license" /></a>
+</p>
+
+
+## Installation
+
+```bash
+npm install vue-use-date-format
+```
+
+## Usage
+
+```ts
+import { useDateFormat } from 'vue-use-date-format';
+```
+
+Get the formatted date according to the string of tokens passed in, inspired
+by [dayjs](https://github.com/iamkun/dayjs).
+
+**List of all available formats (HH:mm:ss by default):**
+
+| Format | Output                   | Description                             |
+| ------ | ------------------------ | --------------------------------------- |
+| `Yo`   | 2018th                   | Ordinal formatted year                  |
+| `YY`   | 18                       | Two-digit year                          |
+| `YYYY` | 2018                     | Four-digit year                         |
+| `M`    | 1-12                     | The month, beginning at 1               |
+| `Mo`   | 1st, 2nd, ..., 12th      | The month, ordinal formatted            |
+| `MM`   | 01-12                    | The month, 2-digits                     |
+| `MMM`  | Jan-Dec                  | The abbreviated month name              |
+| `MMMM` | January-December         | The full month name                     |
+| `D`    | 1-31                     | The day of the month                    |
+| `Do`   | 1st, 2nd, ..., 31st      | The day of the month, ordinal formatted |
+| `DD`   | 01-31                    | The day of the month, 2-digits          |
+| `H`    | 0-23                     | The hour                                |
+| `Ho`   | 0th, 1st, 2nd, ..., 23rd | The hour, ordinal formatted             |
+| `HH`   | 00-23                    | The hour, 2-digits                      |
+| `h`    | 1-12                     | The hour, 12-hour clock                 |
+| `ho`   | 1st, 2nd, ..., 12th      | The hour, 12-hour clock, sorted         |
+| `hh`   | 01-12                    | The hour, 12-hour clock, 2-digits       |
+| `m`    | 0-59                     | The minute                              |
+| `mo`   | 0th, 1st, ..., 59th      | The minute, ordinal formatted           |
+| `mm`   | 00-59                    | The minute, 2-digits                    |
+| `s`    | 0-59                     | The second                              |
+| `so`   | 0th, 1st, ..., 59th      | The second, ordinal formatted           |
+| `ss`   | 00-59                    | The second, 2-digits                    |
+| `SSS`  | 000-999                  | The millisecond, 3-digits               |
+| `A`    | AM PM                    | The meridiem                            |
+| `AA`   | A.M. P.M.                | The meridiem, periods                   |
+| `a`    | am pm                    | The meridiem, lowercase                 |
+| `aa`   | a.m. p.m.                | The meridiem, lowercase and periods     |
+| `d`    | 0-6                      | The day of the week, with Sunday as 0   |
+| `dd`   | S-S                      | The min name of the day of the week     |
+| `ddd`  | Sun-Sat                  | The short name of the day of the week   |
+| `dddd` | Sunday-Saturday          | The name of the day of the week         |
+| `z`    | GMT, GMT+1               | The timezone with offset                |
+| `zz`   | GMT, GMT+1               | The timezone with offset                |
+| `zzz`  | GMT, GMT+1               | The timezone with offset                |
+| `zzzz` | GMT, GMT+01:00           | The long timezone with offset           |
+
+- Meridiem is customizable by defining `customMeridiem` in `options`.
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with locales
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with custom meridiem
+
+```vue
+<script setup lang="ts">
+import { useDateFormat } from 'vue-use-date-format'
+
+function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
+  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
+  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
+}
+
+const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
+// am.value = '05:05:05 ΠΜ'
+const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
+// pm.value = '05:05:05 Μ.Μ.'
+</script>
+```
+
+> Extracted from [VueUse](https://vueuse.org/) for standalone use.
+
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="logo.svg" alt="vue-use-date-format" width="180" />
+</p>
+
+<h1 align="center">vue-use-date-format</h1>
+
+<p align="center">A Vue 3 composition API utility for formatting dates reactively using format tokens (YYYY, MM, DD, HH, mm, ss, etc.). Supports localization and custom meridiem.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/v/vue-use-date-format.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/dm/vue-use-date-format.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/vuefrag/vue-use-date-format/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vue-use-date-format.svg" alt="license" /></a>
+</p>
+
+
+## Installation
+
+```bash
+npm install vue-use-date-format
+```
+
+## Usage
+
+```ts
+import { useDateFormat } from 'vue-use-date-format';
+```
+
+Get the formatted date according to the string of tokens passed in, inspired
+by [dayjs](https://github.com/iamkun/dayjs).
+
+**List of all available formats (HH:mm:ss by default):**
+
+| Format | Output                   | Description                             |
+| ------ | ------------------------ | --------------------------------------- |
+| `Yo`   | 2018th                   | Ordinal formatted year                  |
+| `YY`   | 18                       | Two-digit year                          |
+| `YYYY` | 2018                     | Four-digit year                         |
+| `M`    | 1-12                     | The month, beginning at 1               |
+| `Mo`   | 1st, 2nd, ..., 12th      | The month, ordinal formatted            |
+| `MM`   | 01-12                    | The month, 2-digits                     |
+| `MMM`  | Jan-Dec                  | The abbreviated month name              |
+| `MMMM` | January-December         | The full month name                     |
+| `D`    | 1-31                     | The day of the month                    |
+| `Do`   | 1st, 2nd, ..., 31st      | The day of the month, ordinal formatted |
+| `DD`   | 01-31                    | The day of the month, 2-digits          |
+| `H`    | 0-23                     | The hour                                |
+| `Ho`   | 0th, 1st, 2nd, ..., 23rd | The hour, ordinal formatted             |
+| `HH`   | 00-23                    | The hour, 2-digits                      |
+| `h`    | 1-12                     | The hour, 12-hour clock                 |
+| `ho`   | 1st, 2nd, ..., 12th      | The hour, 12-hour clock, sorted         |
+| `hh`   | 01-12                    | The hour, 12-hour clock, 2-digits       |
+| `m`    | 0-59                     | The minute                              |
+| `mo`   | 0th, 1st, ..., 59th      | The minute, ordinal formatted           |
+| `mm`   | 00-59                    | The minute, 2-digits                    |
+| `s`    | 0-59                     | The second                              |
+| `so`   | 0th, 1st, ..., 59th      | The second, ordinal formatted           |
+| `ss`   | 00-59                    | The second, 2-digits                    |
+| `SSS`  | 000-999                  | The millisecond, 3-digits               |
+| `A`    | AM PM                    | The meridiem                            |
+| `AA`   | A.M. P.M.                | The meridiem, periods                   |
+| `a`    | am pm                    | The meridiem, lowercase                 |
+| `aa`   | a.m. p.m.                | The meridiem, lowercase and periods     |
+| `d`    | 0-6                      | The day of the week, with Sunday as 0   |
+| `dd`   | S-S                      | The min name of the day of the week     |
+| `ddd`  | Sun-Sat                  | The short name of the day of the week   |
+| `dddd` | Sunday-Saturday          | The name of the day of the week         |
+| `z`    | GMT, GMT+1               | The timezone with offset                |
+| `zz`   | GMT, GMT+1               | The timezone with offset                |
+| `zzz`  | GMT, GMT+1               | The timezone with offset                |
+| `zzzz` | GMT, GMT+01:00           | The long timezone with offset           |
+
+- Meridiem is customizable by defining `customMeridiem` in `options`.
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with locales
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with custom meridiem
+
+```vue
+<script setup lang="ts">
+import { useDateFormat } from 'vue-use-date-format'
+
+function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
+  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
+  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
+}
+
+const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
+// am.value = '05:05:05 ΠΜ'
+const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
+// pm.value = '05:05:05 Μ.Μ.'
+</script>
+```
+
+> Extracted from [VueUse](https://vueuse.org/) for standalone use.
+
+
+## License
+
+MIT

package/README.npm.md

@@ -0,0 +1,125 @@
+<p align="center">
+  <img src="logo.svg" alt="vue-use-date-format" width="180" />
+</p>
+
+<h1 align="center">vue-use-date-format</h1>
+
+<p align="center">A Vue 3 composition API utility for formatting dates reactively using format tokens (YYYY, MM, DD, HH, mm, ss, etc.). Supports localization and custom meridiem.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/v/vue-use-date-format.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/vue-use-date-format"><img src="https://img.shields.io/npm/dm/vue-use-date-format.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/vuefrag/vue-use-date-format/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vue-use-date-format.svg" alt="license" /></a>
+</p>
+
+
+## Installation
+
+```bash
+npm install vue-use-date-format
+```
+
+## Usage
+
+```ts
+import { useDateFormat } from 'vue-use-date-format';
+```
+
+Get the formatted date according to the string of tokens passed in, inspired
+by [dayjs](https://github.com/iamkun/dayjs).
+
+**List of all available formats (HH:mm:ss by default):**
+
+| Format | Output                   | Description                             |
+| ------ | ------------------------ | --------------------------------------- |
+| `Yo`   | 2018th                   | Ordinal formatted year                  |
+| `YY`   | 18                       | Two-digit year                          |
+| `YYYY` | 2018                     | Four-digit year                         |
+| `M`    | 1-12                     | The month, beginning at 1               |
+| `Mo`   | 1st, 2nd, ..., 12th      | The month, ordinal formatted            |
+| `MM`   | 01-12                    | The month, 2-digits                     |
+| `MMM`  | Jan-Dec                  | The abbreviated month name              |
+| `MMMM` | January-December         | The full month name                     |
+| `D`    | 1-31                     | The day of the month                    |
+| `Do`   | 1st, 2nd, ..., 31st      | The day of the month, ordinal formatted |
+| `DD`   | 01-31                    | The day of the month, 2-digits          |
+| `H`    | 0-23                     | The hour                                |
+| `Ho`   | 0th, 1st, 2nd, ..., 23rd | The hour, ordinal formatted             |
+| `HH`   | 00-23                    | The hour, 2-digits                      |
+| `h`    | 1-12                     | The hour, 12-hour clock                 |
+| `ho`   | 1st, 2nd, ..., 12th      | The hour, 12-hour clock, sorted         |
+| `hh`   | 01-12                    | The hour, 12-hour clock, 2-digits       |
+| `m`    | 0-59                     | The minute                              |
+| `mo`   | 0th, 1st, ..., 59th      | The minute, ordinal formatted           |
+| `mm`   | 00-59                    | The minute, 2-digits                    |
+| `s`    | 0-59                     | The second                              |
+| `so`   | 0th, 1st, ..., 59th      | The second, ordinal formatted           |
+| `ss`   | 00-59                    | The second, 2-digits                    |
+| `SSS`  | 000-999                  | The millisecond, 3-digits               |
+| `A`    | AM PM                    | The meridiem                            |
+| `AA`   | A.M. P.M.                | The meridiem, periods                   |
+| `a`    | am pm                    | The meridiem, lowercase                 |
+| `aa`   | a.m. p.m.                | The meridiem, lowercase and periods     |
+| `d`    | 0-6                      | The day of the week, with Sunday as 0   |
+| `dd`   | S-S                      | The min name of the day of the week     |
+| `ddd`  | Sun-Sat                  | The short name of the day of the week   |
+| `dddd` | Sunday-Saturday          | The name of the day of the week         |
+| `z`    | GMT, GMT+1               | The timezone with offset                |
+| `zz`   | GMT, GMT+1               | The timezone with offset                |
+| `zzz`  | GMT, GMT+1               | The timezone with offset                |
+| `zzzz` | GMT, GMT+01:00           | The long timezone with offset           |
+
+- Meridiem is customizable by defining `customMeridiem` in `options`.
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with locales
+
+```vue
+<script setup lang="ts">
+import { useDateFormat, useNow } from 'vue-use-date-format'
+
+const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
+</script>
+
+<template>
+  <div>{{ formatted }}</div>
+</template>
+```
+
+### Use with custom meridiem
+
+```vue
+<script setup lang="ts">
+import { useDateFormat } from 'vue-use-date-format'
+
+function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
+  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
+  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
+}
+
+const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
+// am.value = '05:05:05 ΠΜ'
+const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
+// pm.value = '05:05:05 Μ.Μ.'
+</script>
+```
+
+> Extracted from [VueUse](https://vueuse.org/) for standalone use.
+
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+const vue = require('vue');
+
+const REGEX_PARSE = /^(\d{4})[-/]?(\d{1,2})?[-/]?(\d{0,2})[T\s]*(\d{1,2})?:?(\d{1,2})?:?(\d{1,2})?[.:]?(\d+)?$/i;
+const REGEX_FORMAT = /[YMDHhms]o|\[([^\]]+)\]|Y{1,4}|M{1,4}|D{1,2}|d{1,4}|H{1,2}|h{1,2}|a{1,2}|A{1,2}|m{1,2}|s{1,2}|Z{1,2}|z{1,4}|SSS/g;
+function defaultMeridiem(hours, minutes, isLowercase, hasPeriod) {
+  let m = hours < 12 ? "AM" : "PM";
+  if (hasPeriod)
+    m = m.split("").reduce((acc, curr) => acc += `${curr}.`, "");
+  return isLowercase ? m.toLowerCase() : m;
+}
+function formatOrdinal(num) {
+  const suffixes = ["th", "st", "nd", "rd"];
+  const v = num % 100;
+  return num + (suffixes[(v - 20) % 10] || suffixes[v] || suffixes[0]);
+}
+function formatDate(date, formatStr, options = {}) {
+  const years = date.getFullYear();
+  const month = date.getMonth();
+  const days = date.getDate();
+  const hours = date.getHours();
+  const minutes = date.getMinutes();
+  const seconds = date.getSeconds();
+  const milliseconds = date.getMilliseconds();
+  const day = date.getDay();
+  const meridiem = options.customMeridiem ?? defaultMeridiem;
+  const stripTimeZone = (dateString) => {
+    return dateString.split(" ")[1] ?? "";
+  };
+  const matches = {
+    Yo: () => formatOrdinal(years),
+    YY: () => String(years).slice(-2),
+    YYYY: () => years,
+    M: () => month + 1,
+    Mo: () => formatOrdinal(month + 1),
+    MM: () => `${month + 1}`.padStart(2, "0"),
+    MMM: () => date.toLocaleDateString(vue.toValue(options.locales), { month: "short" }),
+    MMMM: () => date.toLocaleDateString(vue.toValue(options.locales), { month: "long" }),
+    D: () => String(days),
+    Do: () => formatOrdinal(days),
+    DD: () => `${days}`.padStart(2, "0"),
+    H: () => String(hours),
+    Ho: () => formatOrdinal(hours),
+    HH: () => `${hours}`.padStart(2, "0"),
+    h: () => `${hours % 12 || 12}`.padStart(1, "0"),
+    ho: () => formatOrdinal(hours % 12 || 12),
+    hh: () => `${hours % 12 || 12}`.padStart(2, "0"),
+    m: () => String(minutes),
+    mo: () => formatOrdinal(minutes),
+    mm: () => `${minutes}`.padStart(2, "0"),
+    s: () => String(seconds),
+    so: () => formatOrdinal(seconds),
+    ss: () => `${seconds}`.padStart(2, "0"),
+    SSS: () => `${milliseconds}`.padStart(3, "0"),
+    d: () => day,
+    dd: () => date.toLocaleDateString(vue.toValue(options.locales), { weekday: "narrow" }),
+    ddd: () => date.toLocaleDateString(vue.toValue(options.locales), { weekday: "short" }),
+    dddd: () => date.toLocaleDateString(vue.toValue(options.locales), { weekday: "long" }),
+    A: () => meridiem(hours, minutes),
+    AA: () => meridiem(hours, minutes, false, true),
+    a: () => meridiem(hours, minutes, true),
+    aa: () => meridiem(hours, minutes, true, true),
+    z: () => stripTimeZone(date.toLocaleDateString(vue.toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zz: () => stripTimeZone(date.toLocaleDateString(vue.toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zzz: () => stripTimeZone(date.toLocaleDateString(vue.toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zzzz: () => stripTimeZone(date.toLocaleDateString(vue.toValue(options.locales), { timeZoneName: "longOffset" }))
+  };
+  return formatStr.replace(REGEX_FORMAT, (match, $1) => $1 ?? matches[match]?.() ?? match);
+}
+function normalizeDate(date) {
+  if (date === null)
+    return new Date(Number.NaN);
+  if (date === void 0)
+    return /* @__PURE__ */ new Date();
+  if (date instanceof Date)
+    return new Date(date);
+  if (typeof date === "string" && !/Z$/i.test(date)) {
+    const d = date.match(REGEX_PARSE);
+    if (d) {
+      const m = d[2] - 1 || 0;
+      const ms = (d[7] || "0").substring(0, 3);
+      return new Date(d[1], m, d[3] || 1, d[4] || 0, d[5] || 0, d[6] || 0, ms);
+    }
+  }
+  return new Date(date);
+}
+// @__NO_SIDE_EFFECTS__
+function useDateFormat(date, formatStr = "HH:mm:ss", options = {}) {
+  return vue.computed(() => formatDate(normalizeDate(vue.toValue(date)), vue.toValue(formatStr), options));
+}
+
+exports.formatDate = formatDate;
+exports.normalizeDate = normalizeDate;
+exports.useDateFormat = useDateFormat;

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { MaybeRefOrGetter, ComputedRef } from 'vue';
+
+type DateLike = Date | number | string | undefined;
+interface UseDateFormatOptions {
+    /**
+     * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+     */
+    locales?: MaybeRefOrGetter<Intl.LocalesArgument>;
+    /**
+     * A custom function to re-modify the way to display meridiem
+     *
+     */
+    customMeridiem?: (hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) => string;
+}
+declare function formatDate(date: Date, formatStr: string, options?: UseDateFormatOptions): string;
+declare function normalizeDate(date: DateLike): Date;
+type UseDateFormatReturn = ComputedRef<string>;
+/**
+ * Get the formatted date according to the string of tokens passed in.
+ *
+ * @see https://vueuse.org/useDateFormat
+ * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
+ * @param formatStr - The combination of tokens to format the date
+ * @param options - UseDateFormatOptions
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function useDateFormat(date: MaybeRefOrGetter<DateLike>, formatStr?: MaybeRefOrGetter<string>, options?: UseDateFormatOptions): UseDateFormatReturn;
+
+export { formatDate, normalizeDate, useDateFormat };
+export type { DateLike, UseDateFormatOptions, UseDateFormatReturn };

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+import { MaybeRefOrGetter, ComputedRef } from 'vue';
+
+type DateLike = Date | number | string | undefined;
+interface UseDateFormatOptions {
+    /**
+     * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+     */
+    locales?: MaybeRefOrGetter<Intl.LocalesArgument>;
+    /**
+     * A custom function to re-modify the way to display meridiem
+     *
+     */
+    customMeridiem?: (hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) => string;
+}
+declare function formatDate(date: Date, formatStr: string, options?: UseDateFormatOptions): string;
+declare function normalizeDate(date: DateLike): Date;
+type UseDateFormatReturn = ComputedRef<string>;
+/**
+ * Get the formatted date according to the string of tokens passed in.
+ *
+ * @see https://vueuse.org/useDateFormat
+ * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
+ * @param formatStr - The combination of tokens to format the date
+ * @param options - UseDateFormatOptions
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function useDateFormat(date: MaybeRefOrGetter<DateLike>, formatStr?: MaybeRefOrGetter<string>, options?: UseDateFormatOptions): UseDateFormatReturn;
+
+export { formatDate, normalizeDate, useDateFormat };
+export type { DateLike, UseDateFormatOptions, UseDateFormatReturn };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { MaybeRefOrGetter, ComputedRef } from 'vue';
+
+type DateLike = Date | number | string | undefined;
+interface UseDateFormatOptions {
+    /**
+     * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+     */
+    locales?: MaybeRefOrGetter<Intl.LocalesArgument>;
+    /**
+     * A custom function to re-modify the way to display meridiem
+     *
+     */
+    customMeridiem?: (hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) => string;
+}
+declare function formatDate(date: Date, formatStr: string, options?: UseDateFormatOptions): string;
+declare function normalizeDate(date: DateLike): Date;
+type UseDateFormatReturn = ComputedRef<string>;
+/**
+ * Get the formatted date according to the string of tokens passed in.
+ *
+ * @see https://vueuse.org/useDateFormat
+ * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
+ * @param formatStr - The combination of tokens to format the date
+ * @param options - UseDateFormatOptions
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function useDateFormat(date: MaybeRefOrGetter<DateLike>, formatStr?: MaybeRefOrGetter<string>, options?: UseDateFormatOptions): UseDateFormatReturn;
+
+export { formatDate, normalizeDate, useDateFormat };
+export type { DateLike, UseDateFormatOptions, UseDateFormatReturn };

package/dist/index.mjs

@@ -0,0 +1,91 @@
+import { computed, toValue } from 'vue';
+
+const REGEX_PARSE = /^(\d{4})[-/]?(\d{1,2})?[-/]?(\d{0,2})[T\s]*(\d{1,2})?:?(\d{1,2})?:?(\d{1,2})?[.:]?(\d+)?$/i;
+const REGEX_FORMAT = /[YMDHhms]o|\[([^\]]+)\]|Y{1,4}|M{1,4}|D{1,2}|d{1,4}|H{1,2}|h{1,2}|a{1,2}|A{1,2}|m{1,2}|s{1,2}|Z{1,2}|z{1,4}|SSS/g;
+function defaultMeridiem(hours, minutes, isLowercase, hasPeriod) {
+  let m = hours < 12 ? "AM" : "PM";
+  if (hasPeriod)
+    m = m.split("").reduce((acc, curr) => acc += `${curr}.`, "");
+  return isLowercase ? m.toLowerCase() : m;
+}
+function formatOrdinal(num) {
+  const suffixes = ["th", "st", "nd", "rd"];
+  const v = num % 100;
+  return num + (suffixes[(v - 20) % 10] || suffixes[v] || suffixes[0]);
+}
+function formatDate(date, formatStr, options = {}) {
+  const years = date.getFullYear();
+  const month = date.getMonth();
+  const days = date.getDate();
+  const hours = date.getHours();
+  const minutes = date.getMinutes();
+  const seconds = date.getSeconds();
+  const milliseconds = date.getMilliseconds();
+  const day = date.getDay();
+  const meridiem = options.customMeridiem ?? defaultMeridiem;
+  const stripTimeZone = (dateString) => {
+    return dateString.split(" ")[1] ?? "";
+  };
+  const matches = {
+    Yo: () => formatOrdinal(years),
+    YY: () => String(years).slice(-2),
+    YYYY: () => years,
+    M: () => month + 1,
+    Mo: () => formatOrdinal(month + 1),
+    MM: () => `${month + 1}`.padStart(2, "0"),
+    MMM: () => date.toLocaleDateString(toValue(options.locales), { month: "short" }),
+    MMMM: () => date.toLocaleDateString(toValue(options.locales), { month: "long" }),
+    D: () => String(days),
+    Do: () => formatOrdinal(days),
+    DD: () => `${days}`.padStart(2, "0"),
+    H: () => String(hours),
+    Ho: () => formatOrdinal(hours),
+    HH: () => `${hours}`.padStart(2, "0"),
+    h: () => `${hours % 12 || 12}`.padStart(1, "0"),
+    ho: () => formatOrdinal(hours % 12 || 12),
+    hh: () => `${hours % 12 || 12}`.padStart(2, "0"),
+    m: () => String(minutes),
+    mo: () => formatOrdinal(minutes),
+    mm: () => `${minutes}`.padStart(2, "0"),
+    s: () => String(seconds),
+    so: () => formatOrdinal(seconds),
+    ss: () => `${seconds}`.padStart(2, "0"),
+    SSS: () => `${milliseconds}`.padStart(3, "0"),
+    d: () => day,
+    dd: () => date.toLocaleDateString(toValue(options.locales), { weekday: "narrow" }),
+    ddd: () => date.toLocaleDateString(toValue(options.locales), { weekday: "short" }),
+    dddd: () => date.toLocaleDateString(toValue(options.locales), { weekday: "long" }),
+    A: () => meridiem(hours, minutes),
+    AA: () => meridiem(hours, minutes, false, true),
+    a: () => meridiem(hours, minutes, true),
+    aa: () => meridiem(hours, minutes, true, true),
+    z: () => stripTimeZone(date.toLocaleDateString(toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zz: () => stripTimeZone(date.toLocaleDateString(toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zzz: () => stripTimeZone(date.toLocaleDateString(toValue(options.locales), { timeZoneName: "shortOffset" })),
+    zzzz: () => stripTimeZone(date.toLocaleDateString(toValue(options.locales), { timeZoneName: "longOffset" }))
+  };
+  return formatStr.replace(REGEX_FORMAT, (match, $1) => $1 ?? matches[match]?.() ?? match);
+}
+function normalizeDate(date) {
+  if (date === null)
+    return new Date(Number.NaN);
+  if (date === void 0)
+    return /* @__PURE__ */ new Date();
+  if (date instanceof Date)
+    return new Date(date);
+  if (typeof date === "string" && !/Z$/i.test(date)) {
+    const d = date.match(REGEX_PARSE);
+    if (d) {
+      const m = d[2] - 1 || 0;
+      const ms = (d[7] || "0").substring(0, 3);
+      return new Date(d[1], m, d[3] || 1, d[4] || 0, d[5] || 0, d[6] || 0, ms);
+    }
+  }
+  return new Date(date);
+}
+// @__NO_SIDE_EFFECTS__
+function useDateFormat(date, formatStr = "HH:mm:ss", options = {}) {
+  return computed(() => formatDate(normalizeDate(toValue(date)), toValue(formatStr), options));
+}
+
+export { formatDate, normalizeDate, useDateFormat };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "vue-use-date-format",
+  "version": "1.0.1",
+  "description": "Vue 3 reactive date formatting with customizable tokens",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "prepublishOnly": "cp README.npm.md README.md && npm run build",
+    "postpublish": "cp README.github.md README.md"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "vue-3",
+    "composable",
+    "composition-api",
+    "vueuse",
+    "time",
+    "date",
+    "datetime",
+    "timer",
+    "use",
+    "format",
+    "reactive",
+    "tokens",
+    "strftime",
+    "localize",
+    "useDateFormat"
+  ],
+  "author": "VueFrag",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuefrag/vue-use-date-format.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vuefrag/vue-use-date-format/issues"
+  },
+  "homepage": "https://github.com/vuefrag/vue-use-date-format#readme",
+  "peerDependencies": {
+    "vue": ">=3.0.0"
+  },
+  "devDependencies": {
+    "unbuild": "^2.0.0",
+    "typescript": "^5.0.0",
+    "vue": "^3.4.0"
+  }
+}