@samline/date 2.1.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +119 -34
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # @samline/date
2
2
 
3
- Small date formatting package built on top of Day.js with a shared core API, framework wrappers, and browser usage.
3
+ Small date formatting package built on top of Day.js with strict parsing, locale-aware formatting, and a shared API for core, vanilla, React, Vue, Svelte, and browser usage.
4
4
 
5
- This package uses Day.js as its date engine. We are grateful for the existence of the package and will make good use of it in this project.
5
+ This package uses Day.js as its date engine. Thanks to the Day.js project for making that foundation available.
6
6
 
7
- Repository: https://github.com/iamkun/dayjs
7
+ Day.js repository: https://github.com/iamkun/dayjs
8
8
 
9
9
  ## Features
10
10
 
@@ -16,25 +16,86 @@ Repository: https://github.com/iamkun/dayjs
16
16
  - parse and validate dates with explicit result objects
17
17
  - use the same API from core, vanilla, React, Vue, Svelte, or browser global builds
18
18
 
19
+ ## Table of Contents
20
+
21
+ - [Installation](#installation)
22
+ - [Browser and CDN](#browser-and-cdn)
23
+ - [Entrypoints](#entrypoints)
24
+ - [Quick Start](#quick-start)
25
+ - [API](#api)
26
+ - [Supported Locales](#supported-locales)
27
+ - [Documentation](#documentation)
28
+ - [License](#license)
29
+
19
30
  ## Installation
20
31
 
32
+ Use the package manager that matches your project. The published package targets Node 20 or newer.
33
+
21
34
  ```bash
22
35
  npm install @samline/date
23
36
  ```
24
37
 
38
+ ```bash
39
+ pnpm add @samline/date
40
+ ```
41
+
42
+ ```bash
43
+ yarn add @samline/date
44
+ ```
45
+
46
+ ```bash
47
+ bun add @samline/date
48
+ ```
49
+
50
+ ## Browser and CDN
51
+
52
+ If your project does not use a bundler, load the browser build from a CDN. Prefer pinning a version instead of using `latest` in production.
53
+
54
+ ```html
55
+ <script type="module">
56
+ import { DateKit } from 'https://cdn.jsdelivr.net/npm/@samline/date@2.1.1/dist/browser/global.js'
57
+
58
+ const value = await DateKit.getDate({
59
+ date: '23/03/2026',
60
+ input: 'DD/MM/YYYY',
61
+ output: 'MMMM D, YYYY'
62
+ })
63
+
64
+ console.log(value)
65
+ console.log(window.DateKit.resolveLocale('en-us'))
66
+ </script>
67
+ ```
68
+
69
+ You can also use unpkg:
70
+
71
+ ```html
72
+ <script type="module">
73
+ import { DateKit } from 'https://unpkg.com/@samline/date@2.1.1/dist/browser/global.js'
74
+
75
+ console.log(await DateKit.isValidDate({
76
+ date: '23/03/2026',
77
+ input: 'DD/MM/YYYY'
78
+ }))
79
+ </script>
80
+ ```
81
+
82
+ The browser bundle exposes `window.DateKit` and the same shared helpers documented below.
83
+
25
84
  ## Entrypoints
26
85
 
27
- | Entrypoint | Purpose |
28
- | --- | --- |
29
- | `@samline/date` | shared core API |
30
- | `@samline/date/vanilla` | utility wrapper for plain TypeScript or JavaScript |
31
- | `@samline/date/react` | React hook |
32
- | `@samline/date/vue` | Vue composable |
33
- | `@samline/date/svelte` | Svelte store helpers |
34
- | `@samline/date/browser` | browser global build |
86
+ | Entrypoint | Main API | Purpose |
87
+ | --- | --- | --- |
88
+ | `@samline/date` | `createDateFormatter`, `getDate`, `parseDate`, `isValidDate` | shared core API |
89
+ | `@samline/date/vanilla` | same exports as root | utility wrapper for plain TypeScript or JavaScript |
90
+ | `@samline/date/react` | `useDateFormatter` | React hook with scoped formatter state |
91
+ | `@samline/date/vue` | `useDateFormatter` | Vue composable with reactive locale state |
92
+ | `@samline/date/svelte` | `createDateFormatterStore` | Svelte store-driven formatter API |
93
+ | `@samline/date/browser` | `DateKit` | browser global build for projects without a bundler |
35
94
 
36
95
  ## Quick Start
37
96
 
97
+ Use the one-shot helpers when you only need a single async operation.
98
+
38
99
  ```ts
39
100
  import { getDate } from '@samline/date'
40
101
 
@@ -45,22 +106,7 @@ const date = await getDate({
45
106
  })
46
107
  ```
47
108
 
48
- You can also inspect the effective locale before formatting:
49
-
50
- ```ts
51
- import { resolveLocale } from '@samline/date'
52
-
53
- resolveLocale('es-mx')
54
- // es-mx
55
-
56
- resolveLocale('en-us')
57
- // en
58
-
59
- resolveLocale('zz-zz')
60
- // null
61
- ```
62
-
63
- For repeated work with the same locale or invalid text, create one formatter instance and reuse it:
109
+ If you need repeated formatting, parsing, or locale changes, create one formatter instance and reuse it.
64
110
 
65
111
  ```ts
66
112
  import { createDateFormatter } from '@samline/date'
@@ -76,8 +122,37 @@ const date = formatter.getDate({
76
122
  })
77
123
  ```
78
124
 
125
+ You can also inspect the effective locale before formatting:
126
+
127
+ ```ts
128
+ import { getSupportedLocales, resolveLocale } from '@samline/date'
129
+
130
+ getSupportedLocales()
131
+ // ['en', 'es', 'es-mx', 'fr', 'pt', 'pt-br', 'de', 'it', 'ja']
132
+
133
+ resolveLocale('es-mx')
134
+ // es-mx
135
+
136
+ resolveLocale('en-us')
137
+ // en
138
+
139
+ resolveLocale('zz-zz')
140
+ // null
141
+ ```
142
+
79
143
  ## API
80
144
 
145
+ The shared root entrypoint exports:
146
+
147
+ - `createDateFormatter(config?)`
148
+ - `getDate(props?, config?)`
149
+ - `parseDate(props, config?)`
150
+ - `isValidDate(props, config?)`
151
+ - `getSupportedLocales()`
152
+ - `SUPPORTED_LOCALES`
153
+ - `resolveLocale(locale)`
154
+ - `isSupportedLocale(locale)`
155
+
81
156
  ### createDateFormatter
82
157
 
83
158
  ```ts
@@ -117,15 +192,19 @@ The formatter instance exposes:
117
192
  ### Locale helpers
118
193
 
119
194
  ```ts
195
+ SUPPORTED_LOCALES: readonly SupportedLocale[]
196
+ getSupportedLocales(): readonly SupportedLocale[]
120
197
  resolveLocale(locale: LocaleInput): SupportedLocale | null
121
198
  isSupportedLocale(locale: string): boolean
122
199
  ```
123
200
 
201
+ Use `SUPPORTED_LOCALES` or `getSupportedLocales()` when you need the list of locale keys exposed by the package.
202
+
124
203
  Use `resolveLocale` when you want to know the effective locale before creating a formatter or calling a helper.
125
204
 
126
205
  Use `isSupportedLocale` when you only need a boolean check after the package applies its exact-match and base-locale fallback rules.
127
206
 
128
- These helpers are also available in the browser build through `DateKit.resolveLocale(...)` and `DateKit.isSupportedLocale(...)`.
207
+ These helpers are also available in the browser build through `DateKit.getSupportedLocales()`, `DateKit.resolveLocale(...)`, and `DateKit.isSupportedLocale(...)`.
129
208
 
130
209
  ### One-shot helpers
131
210
 
@@ -137,6 +216,8 @@ isValidDate(props: DateParsingOptions, config?: DateFormatterConfig): Promise<bo
137
216
 
138
217
  Use these helpers when you only need a single operation and do not want to create a formatter instance manually.
139
218
 
219
+ All three helpers are async because they can load locale data before running the operation.
220
+
140
221
  | Helper | Returns | Use it when you need |
141
222
  | --- | --- | --- |
142
223
  | `getDate(...)` | formatted string | a final display value |
@@ -165,6 +246,8 @@ const valid = await isValidDate({
165
246
 
166
247
  They load the requested locale automatically and also use `strict: true` by default.
167
248
 
249
+ If you call `getDate()` without props, it returns the current date formatted with the default formatter settings.
250
+
168
251
  ### parseDate
169
252
 
170
253
  ```ts
@@ -180,6 +263,8 @@ Returns a structured result.
180
263
  - Valid parse: `isValid`, `date`, `iso`, `timestamp`, `format(output?)`
181
264
  - Invalid parse: `isValid: false`, `error`, and null date fields
182
265
 
266
+ This makes `parseDate` the right choice when you need validation details, an ISO value, a timestamp, or deferred formatting from the same parsed input.
267
+
183
268
  ### isValidDate
184
269
 
185
270
  ```ts
@@ -194,7 +279,7 @@ Returns a boolean when you only need validation without formatting.
194
279
 
195
280
  ## Supported Locales
196
281
 
197
- The package ships helper support for these locale keys:
282
+ The package ships helper support for these locale keys through `SUPPORTED_LOCALES` and `getSupportedLocales()`:
198
283
 
199
284
  - `en`
200
285
  - `es`
@@ -226,11 +311,11 @@ Use a simple locale like `fr` or `en` when the base language is enough. Use a re
226
311
 
227
312
  ## Documentation
228
313
 
229
- - [docs/vanilla.md](docs/vanilla.md)
230
- - [docs/browser.md](docs/browser.md)
231
- - [docs/react.md](docs/react.md)
232
- - [docs/vue.md](docs/vue.md)
233
- - [docs/svelte.md](docs/svelte.md)
314
+ - [docs/vanilla.md](docs/vanilla.md) for the shared API in plain TypeScript or JavaScript
315
+ - [docs/browser.md](docs/browser.md) for browser-only usage without a bundler
316
+ - [docs/react.md](docs/react.md) for the React hook entrypoint
317
+ - [docs/vue.md](docs/vue.md) for the Vue composable entrypoint
318
+ - [docs/svelte.md](docs/svelte.md) for the Svelte store entrypoint
234
319
 
235
320
  ## License
236
321
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@samline/date",
3
- "version": "2.1.0",
3
+ "version": "2.1.1",
4
4
  "description": "Format and localize dates with Day.js through a small multi-entrypoint API.",
5
5
  "type": "module",
6
6
  "license": "MIT",