@samline/date 2.1.2 → 2.2.0

package/README.md

@@ -11,6 +11,7 @@ Day.js repository: https://github.com/iamkun/dayjs
 - format dates with configurable input and output patterns
 - default locale is English
 - load and switch supported locales on demand
+- manipulate and compare dates through a chainable helper
 - create formatter instances with isolated locale state
 - enable strict parsing globally per formatter or per call
 - parse and validate dates with explicit result objects
@@ -54,7 +55,7 @@ Use the browser bundle when your project loads scripts directly in the page and
 This is useful in environments such as Shopify themes, WordPress templates, or plain HTML pages with no build step.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@samline/date@2.1.2/dist/browser/date.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@samline/date@2.2.0/dist/browser/date.global.js"></script>
 ```
 
 Then use it from a normal script:
@@ -82,11 +83,11 @@ Use one of the package manager commands above when your project has a build step
 
 | Entrypoint | Main API | Purpose |
 | --- | --- | --- |
-| `@samline/date` | `createDateFormatter`, `getDate`, `parseDate`, `isValidDate` | shared core API |
+| `@samline/date` | `createDateChain`, `createDateFormatter`, `getDate`, `parseDate`, `isValidDate` | shared core API |
 | `@samline/date/vanilla` | same exports as root | utility wrapper for plain TypeScript or JavaScript |
-| `@samline/date/react` | `useDateFormatter` | React hook with scoped formatter state |
-| `@samline/date/vue` | `useDateFormatter` | Vue composable with reactive locale state |
-| `@samline/date/svelte` | `createDateFormatterStore` | Svelte store-driven formatter API |
+| `@samline/date/react` | `useDateFormatter` | React hook with scoped formatter and chain state |
+| `@samline/date/vue` | `useDateFormatter` | Vue composable with reactive formatter and chain state |
+| `@samline/date/svelte` | `createDateFormatterStore` | Svelte store-driven formatter and chain API |
 | `@samline/date/browser` | `DateKit` | browser global build for projects without a bundler |
 
 ## Quick Start
@@ -141,6 +142,7 @@ resolveLocale('zz-zz')
 
 The shared root entrypoint exports:
 
+- `createDateChain(props?, config?)`
 - `createDateFormatter(config?)`
 - `getDate(props?, config?)`
 - `parseDate(props, config?)`
@@ -158,6 +160,7 @@ createDateFormatter(config?: {
   strict?: boolean
   invalid?: string
 }): {
+  createDateChain(props?: CreateDateChainOptions): DateChain
   getDate(props?: GetDateOptions): string
   parseDate(props: DateParsingOptions): ParseDateResult
   isValidDate(props: DateParsingOptions): boolean
@@ -178,6 +181,7 @@ Regional locale input falls back to the base locale when the exact variant is no
 
 The formatter instance exposes:
 
+- `createDateChain(props?)`
 - `getDate(props?)`
 - `parseDate(props)`
 - `isValidDate(props)`
@@ -206,6 +210,7 @@ These helpers are also available in the browser build through `DateKit.getSuppor
 ### One-shot helpers
 
 ```ts
+createDateChain(props?: CreateDateChainOptions, config?: DateFormatterConfig): DateChain
 getDate(props?: GetDateOptions, config?: DateFormatterConfig): Promise<string>
 parseDate(props: DateParsingOptions, config?: DateFormatterConfig): Promise<ParseDateResult>
 isValidDate(props: DateParsingOptions, config?: DateFormatterConfig): Promise<boolean>
@@ -217,12 +222,25 @@ All three helpers are async because they can load locale data before running the
 
 | Helper | Returns | Use it when you need |
 | --- | --- | --- |
+| `createDateChain(...)` | chainable date helper | a one-shot manipulation or comparison flow with multiple date operations |
 | `getDate(...)` | formatted string | a final display value |
 | `parseDate(...)` | structured parse result | validation details, `Date`, `iso`, `timestamp`, or deferred formatting |
 | `isValidDate(...)` | boolean | only a yes or no validation check |
 
 ```ts
-import { getDate, isValidDate, parseDate } from '@samline/date'
+import { createDateChain, getDate, isValidDate, parseDate } from '@samline/date'
+
+const chain = createDateChain({
+  date: '23/03/2026',
+  input: 'DD/MM/YYYY'
+})
+
+await chain.ready
+
+const moved = chain
+  .add(3, 'month')
+  .set('day', 1)
+  .format('YYYY-MM-DD')
 
 const value = await getDate({
   date: '23/03/2026',
@@ -241,10 +259,76 @@ const valid = await isValidDate({
 })
 ```
 
-They load the requested locale automatically and also use `strict: true` by default.
+`getDate`, `parseDate`, and `isValidDate` are async because they can load locale data before running the operation.
+
+`createDateChain` is also a valid one-shot helper. It returns immediately, but you must `await chain.ready` before using it when the locale may need to load.
+
+All of these helpers use `strict: true` by default.
 
 If you call `getDate()` without props, it returns the current date formatted with the default formatter settings.
 
+### createDateChain
+
+```ts
+const chain = createDateChain({
+  date: '23/03/2026',
+  input: 'DD/MM/YYYY',
+  locale: 'es',
+  strict: true,
+  invalid: 'Fecha invalida'
+})
+
+await chain.ready
+
+chain
+  .add(3, 'month')
+  .set('day', 1)
+  .format('YYYY-MM-DD')
+```
+
+Use this helper when you want to parse a date and then manipulate or compare it in the same flow.
+
+The chainable helper exposes:
+
+- `add(value, unit)`
+- `subtract(value, unit)`
+- `set(unit, value)`
+- `startOf(unit)`
+- `endOf(unit)`
+- `format(output?)`
+- `toDate()`
+- `toISOString()`
+- `toTimestamp()`
+- `isValid()`
+- `isBefore(other, unit?)`
+- `isAfter(other, unit?)`
+- `isSame(other, unit?)`
+- `toState()`
+- `ready`
+
+`set('day', value)` is the public way to change the day of the month. Internally it maps to Day.js `set('date', value)` so the behavior stays aligned with Day.js while the public API stays clearer.
+
+`toState()` returns the current structured state of the chain:
+
+- valid state: `isValid`, `locale`, `date`, `iso`, `timestamp`
+- invalid state: `isValid`, `locale`, `date: null`, `iso: null`, `timestamp: null`, `error`
+
+Example:
+
+```ts
+const chain = createDateChain({
+  date: '23/03/2026',
+  input: 'DD/MM/YYYY'
+})
+
+await chain.ready
+
+const finalState = chain
+  .add(3, 'month')
+  .endOf('month')
+  .toState()
+```
+
 ### parseDate
 
 ```ts

package/dist/browser/date.global.js

@@ -655,6 +655,9 @@
   var markLocaleAsLoaded = (locale) => {
     loadedLocales.add(locale);
   };
+  var isLocaleLoaded = (locale) => {
+    return loadedLocales.has(locale);
+  };
   var ensureLocaleLoaded = async (locale) => {
     if (loadedLocales.has(locale)) {
       return;
@@ -694,7 +697,13 @@
     invalid: config?.invalid ?? DEFAULT_INVALID_DATE
   });
   var getInvalidDateText = (config, props) => {
-    return props?.invalid ?? config?.invalid ?? DEFAULT_INVALID_DATE;
+    if (typeof props === "object" && props !== null && "invalid" in props) {
+      const invalid = props.invalid;
+      if (invalid !== void 0) {
+        return invalid;
+      }
+    }
+    return config?.invalid ?? DEFAULT_INVALID_DATE;
   };
   var getTargetLocale = (currentLocale, props) => {
     if (!props?.locale) {
@@ -720,29 +729,193 @@
     }
     return (0, import_dayjs.default)(value, [...input], locale, strict).locale(locale);
   };
+  var getCurrentDayjs = (locale) => {
+    return (0, import_dayjs.default)().locale(locale);
+  };
+  var createParseSuccess = (parsed, locale) => {
+    return {
+      isValid: true,
+      locale,
+      date: parsed.toDate(),
+      iso: parsed.toISOString(),
+      timestamp: parsed.valueOf(),
+      format: (output = DEFAULT_FORMAT) => parsed.format(output)
+    };
+  };
+  var createParseFailure = (locale, error) => {
+    return {
+      isValid: false,
+      locale,
+      date: null,
+      iso: null,
+      timestamp: null,
+      error
+    };
+  };
+  var createDateChainSuccessState = (parsed, locale) => {
+    return {
+      isValid: true,
+      locale,
+      date: parsed.toDate(),
+      iso: parsed.toISOString(),
+      timestamp: parsed.valueOf()
+    };
+  };
+  var createDateChainFailureState = (locale, error) => {
+    return {
+      isValid: false,
+      locale,
+      date: null,
+      iso: null,
+      timestamp: null,
+      error
+    };
+  };
+  var mapChainSetUnit = (unit) => {
+    if (unit === "day") {
+      return "date";
+    }
+    return unit;
+  };
+  var createReadyError = () => {
+    return new Error("Date chain is not ready. Await chain.ready before using it with locales that may need to load.");
+  };
+  var assertDateChainReady = (state) => {
+    if (!state.ready) {
+      throw createReadyError();
+    }
+  };
+  var getComparableDayjs = (value) => {
+    if (typeof value === "object" && value !== null && "toState" in value) {
+      const state = value.toState();
+      if (!state.isValid) {
+        return null;
+      }
+      return (0, import_dayjs.default)(state.date);
+    }
+    const comparable = (0, import_dayjs.default)(value);
+    if (!comparable.isValid()) {
+      return null;
+    }
+    return comparable;
+  };
+  var createDateChainApi = (state, ready) => {
+    const applyMutation = (transform) => {
+      assertDateChainReady(state);
+      if (state.current) {
+        state.current = transform(state.current);
+      }
+      return chain;
+    };
+    const compare = (other, comparator) => {
+      assertDateChainReady(state);
+      if (!state.current) {
+        return false;
+      }
+      const comparable = getComparableDayjs(other);
+      if (!comparable) {
+        return false;
+      }
+      return comparator(state.current, comparable);
+    };
+    const chain = {
+      ready,
+      add: (value, unit) => applyMutation((current) => current.add(value, unit)),
+      subtract: (value, unit) => applyMutation((current) => current.subtract(value, unit)),
+      set: (unit, value) => applyMutation((current) => current.set(mapChainSetUnit(unit), value)),
+      startOf: (unit) => applyMutation((current) => current.startOf(unit)),
+      endOf: (unit) => applyMutation((current) => current.endOf(unit)),
+      format: (output = DEFAULT_FORMAT) => {
+        assertDateChainReady(state);
+        if (!state.current) {
+          return state.invalid;
+        }
+        return state.current.format(output);
+      },
+      toDate: () => {
+        assertDateChainReady(state);
+        return state.current ? state.current.toDate() : null;
+      },
+      toISOString: () => {
+        assertDateChainReady(state);
+        return state.current ? state.current.toISOString() : null;
+      },
+      toTimestamp: () => {
+        assertDateChainReady(state);
+        return state.current ? state.current.valueOf() : null;
+      },
+      isValid: () => {
+        assertDateChainReady(state);
+        return state.current !== null;
+      },
+      isBefore: (other, unit) => compare(other, (current, comparable) => current.isBefore(comparable, unit)),
+      isAfter: (other, unit) => compare(other, (current, comparable) => current.isAfter(comparable, unit)),
+      isSame: (other, unit) => compare(other, (current, comparable) => current.isSame(comparable, unit)),
+      toState: () => {
+        assertDateChainReady(state);
+        if (!state.current) {
+          return createDateChainFailureState(state.locale, state.error ?? state.invalid);
+        }
+        return createDateChainSuccessState(state.current, state.locale);
+      }
+    };
+    return chain;
+  };
+  var createDateChainState = (locale, invalid, getInitialDate) => {
+    const state = {
+      locale,
+      invalid,
+      current: null,
+      ready: false,
+      error: invalid
+    };
+    const initialize = () => {
+      const parsed = getInitialDate();
+      state.ready = true;
+      if (!parsed.isValid()) {
+        state.current = null;
+        state.error = invalid;
+        return;
+      }
+      state.current = parsed;
+      state.error = null;
+    };
+    if (isLocaleLoaded(locale)) {
+      initialize();
+      return {
+        state,
+        ready: Promise.resolve()
+      };
+    }
+    return {
+      state,
+      ready: ensureLocaleLoaded(locale).then(() => {
+        initialize();
+      })
+    };
+  };
+  var createDateChainFromResolvedConfig = (props, config) => {
+    const locale = getTargetLocale(config.locale, props);
+    const invalid = getInvalidDateText(config, props);
+    const strict = props?.strict ?? config.strict;
+    const getInitialDate = () => {
+      if (props?.date === void 0) {
+        return getCurrentDayjs(locale);
+      }
+      return parseDateValue(props.date, props.input, locale, strict);
+    };
+    const { state, ready } = createDateChainState(locale, invalid, getInitialDate);
+    return createDateChainApi(state, ready);
+  };
   var createFormatterParseDate = (getConfig) => {
     return (props) => {
       const config = getConfig();
       const locale = getTargetLocale(config.locale, props);
       const parsed = parseDateValue(props.date, props.input, locale, props.strict ?? config.strict);
       if (!parsed.isValid()) {
-        return {
-          isValid: false,
-          locale,
-          date: null,
-          iso: null,
-          timestamp: null,
-          error: getInvalidDateText(config, props)
-        };
+        return createParseFailure(locale, getInvalidDateText(config, props));
       }
-      return {
-        isValid: true,
-        locale,
-        date: parsed.toDate(),
-        iso: parsed.toISOString(),
-        timestamp: parsed.valueOf(),
-        format: (output = DEFAULT_FORMAT) => parsed.format(output)
-      };
+      return createParseSuccess(parsed, locale);
     };
   };
   var createFormatterIsValidDate = (parseDate2) => {
@@ -755,10 +928,10 @@
       const locale = getTargetLocale(config.locale, props);
       const output = props?.output ?? DEFAULT_FORMAT;
       if (!props) {
-        return (0, import_dayjs.default)().locale(locale).format(DEFAULT_FORMAT);
+        return getCurrentDayjs(locale).format(DEFAULT_FORMAT);
       }
       if (props.date === void 0) {
-        return (0, import_dayjs.default)().locale(locale).format(output);
+        return getCurrentDayjs(locale).format(output);
       }
       const parsed = parseDate2({
         date: props.date,
@@ -772,6 +945,11 @@
       return parsed.format(output);
     };
   };
+  var createFormatterCreateDateChain = (getConfig) => {
+    return (props) => {
+      return createDateChainFromResolvedConfig(props, getConfig());
+    };
+  };
   function resolveLocaleOrThrow(locale) {
     const resolvedLocale = resolveLocale(locale);
     if (!resolvedLocale) {
@@ -782,6 +960,10 @@
     return resolvedLocale;
   }
   var getSupportedLocales = () => SUPPORTED_LOCALES;
+  var createDateChain = (props, config) => {
+    const locale = getHelperLocale(config, props);
+    return createDateChainFromResolvedConfig(props, createResolvedConfig(locale, config));
+  };
   var getDate = async (props, config) => {
     const locale = getHelperLocale(config, props);
     const formatter = createDateFormatter({ ...config, locale });
@@ -809,6 +991,7 @@
       getDate: createFormatterGetDate(getConfig),
       parseDate: parseDate2,
       isValidDate: createFormatterIsValidDate(parseDate2),
+      createDateChain: createFormatterCreateDateChain(getConfig),
       getSupportedLocales,
       getCurrentLocale: () => currentLocale,
       setLocale: async (locale) => {
@@ -822,6 +1005,7 @@
 
   // src/browser/global.ts
   var DateKit = {
+    createDateChain,
     createDateFormatter,
     getDate,
     getSupportedLocales,