zeed 1.2.2 → 1.3.0

package/dist/uuid-ININPGKB.d.mts

@@ -0,0 +1,196 @@
+//#region src/common/uuid.d.ts
+/**
+ * Generate raw UUID bytes (128 bits / 16 bytes).
+ *
+ * Uses a cryptographically secure random source provided by
+ * `randomUint8Array`.
+ *
+ * @returns Uint8Array of length 16 with random bytes
+ */
+declare function uuidBytes(): Uint8Array;
+/**
+ * Create a Base62-encoded UUID string from the provided bytes or a newly
+ * generated random UUID. The result is a compact, URL-safe identifier.
+ *
+ * @param bytes - optional 16-byte Uint8Array; if omitted a new random UUID is generated
+ * @returns Base62 string representation (22 characters)
+ */
+declare function uuidB62(bytes?: Uint8Array): string;
+/**
+ * Encode raw UUID bytes to a Base62 string.
+ *
+ * @param bytes - 16-byte UUID as Uint8Array
+ * @returns Base62-encoded string
+ */
+declare function uuidEncodeB62(bytes: Uint8Array): string;
+/**
+ * Decode a Base62-encoded UUID string into raw bytes.
+ *
+ * @param uuid - Base62 string
+ * @returns 16-byte Uint8Array
+ */
+declare function uuidDecodeB62(uuid: string): Uint8Array;
+/**
+ * Create a Base32-encoded UUID string from bytes or a new random UUID.
+ *
+ * @param bytes - optional 16-byte Uint8Array; if omitted a new random UUID is generated
+ * @returns Base32 string representation (26 characters)
+ */
+declare function uuidB32(bytes?: Uint8Array): string;
+/**
+ * Encode raw UUID bytes to a Base32 string.
+ *
+ * @param bytes - 16-byte UUID as Uint8Array
+ * @returns Base32-encoded string
+ */
+declare function uuidEncodeB32(bytes: Uint8Array): string;
+/**
+ * Decode a Base32-encoded UUID string into raw bytes.
+ *
+ * @param uuid - Base32 string
+ * @returns 16-byte Uint8Array
+ */
+declare function uuidDecodeB32(uuid: string): Uint8Array;
+/**
+ * Generate a UUID v4 string.
+ *
+ * Uses the native `crypto.randomUUID()` if available; otherwise falls back to
+ * a random-based implementation using `randomUint8Array`.
+ *
+ * @returns UUID v4 string in standard 8-4-4-4-12 hex format
+ */
+declare function uuidv4(): string;
+/**
+ * Encode 16 raw bytes as a UUID v4 formatted string (hex with dashes).
+ *
+ * @param bytes - 16-byte Uint8Array
+ * @returns UUID string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+ */
+declare function uuidEncodeV4(bytes: Uint8Array): string;
+/**
+ * Decode a UUID v4 string (hex with dashes) into raw bytes.
+ *
+ * @param uuid - UUID string
+ * @returns 16-byte Uint8Array
+ */
+declare function uuidDecodeV4(uuid: string): Uint8Array;
+/**
+ * Create a sortable unique identifier (SUID) as raw bytes.
+ *
+ * The first 6 bytes encode a millisecond timestamp offset from an internal
+ * reference date to allow lexicographic sorting by creation time. The
+ * remaining 10 bytes are random.
+ *
+ * @returns 16-byte Uint8Array where bytes 0-5 are timestamp and 6-15 are random
+ */
+declare function suidBytes(): Uint8Array;
+/**
+ * Create a sortable unique identifier (SUID) and return it encoded using the
+ * currently configured UUID encoding.
+ *
+ * @returns encoded SUID string
+ */
+declare function suid(): string;
+/**
+ * Extract the creation Date from an encoded SUID string.
+ *
+ * @param id - encoded SUID
+ * @returns Date corresponding to the timestamp component of the SUID
+ */
+declare function suidDate(id: string): Date;
+/**
+ * Extract the creation Date from raw SUID bytes.
+ *
+ * @param id - 16-byte SUID as Uint8Array
+ * @returns Date corresponding to the timestamp encoded in bytes 0-5
+ */
+declare function suidBytesDate(id: Uint8Array): Date;
+/**
+ * Generate a 32-bit unsigned integer from 4 random bytes.
+ *
+ * @returns a random 32-bit unsigned integer
+ */
+declare function uuid32bit(): number;
+declare const mapModes: {
+  base62: {
+    uuid: typeof uuidB62;
+    uuidDecode: typeof uuidDecodeB62;
+    uuidEncode: typeof uuidEncodeB62;
+  };
+  base32: {
+    uuid: typeof uuidB32;
+    uuidDecode: typeof uuidDecodeB32;
+    uuidEncode: typeof uuidEncodeB32;
+  };
+  uuidv4: {
+    uuid: typeof uuidv4;
+    uuidDecode: typeof uuidDecodeV4;
+    uuidEncode: typeof uuidEncodeV4;
+  };
+  test: {
+    uuid: () => string;
+    uuidDecode: (id: string) => Uint8Array;
+    uuidEncode: (bin: Uint8Array) => string;
+  };
+};
+/**
+ * Configure the default encoding and whether generated IDs should be
+ * lexicographically sortable.
+ *
+ * @param mode - encoding mode ('base62' | 'base32' | 'uuidv4' | 'test')
+ * @param sorted - when true, `uuid()` will prefer sortable SUIDs
+ */
+declare function setUuidDefaultEncoding(mode?: keyof typeof mapModes, sorted?: boolean): void;
+/**
+ * Generate an identifier using the current encoding mode.
+ *
+ * If the default encoding is configured with `sorted=true`, this returns a
+ * sortable SUID; otherwise a random UUID is returned.
+ *
+ * @returns encoded identifier string
+ */
+declare function uuid(): string;
+/**
+ * Decode an encoded identifier according to the current encoding mode into
+ * raw bytes.
+ *
+ * @param uuid - encoded identifier string
+ * @returns raw 16-byte Uint8Array
+ */
+declare function uuidDecode(uuid: string): Uint8Array;
+/**
+ * Encode raw UUID bytes using the current encoding mode.
+ *
+ * @param bytes - 16-byte Uint8Array
+ * @returns encoded identifier string
+ */
+declare function uuidEncode(bytes: Uint8Array): string;
+/**
+ * Validate an encoded identifier by attempting to decode it and checking
+ * for the expected byte length.
+ *
+ * @param uuid - encoded identifier string
+ * @returns true when valid and decodes to 16 bytes
+ */
+declare function uuidIsValid(uuid: string): boolean;
+/**
+ * Simple counter-based unique name generator.
+ *
+ * Returns strings like 'name-0', 'name-1', ... and increments an internal
+ * counter per `name`.
+ *
+ * @param name - base name for the counter (default: 'id')
+ * @returns generated unique name
+ */
+declare function uname(name?: string): string;
+/** Reset the counter used by `uname` for the given name. */
+declare function unameReset(name?: string): void;
+/**
+ * Quick global incremental id generator.
+ *
+ * Returns strings like 'id-0', 'id-1', ... using a single global counter.
+ */
+declare function qid(): string;
+//#endregion
+export { uuidv4 as C, uuidIsValid as S, uuidDecodeV4 as _, suidBytesDate as a, uuidEncodeB62 as b, unameReset as c, uuidB32 as d, uuidB62 as f, uuidDecodeB62 as g, uuidDecodeB32 as h, suidBytes as i, uuid as l, uuidDecode as m, setUuidDefaultEncoding as n, suidDate as o, uuidBytes as p, suid as r, uname as s, qid as t, uuid32bit as u, uuidEncode as v, uuidEncodeV4 as x, uuidEncodeB32 as y };
+//# sourceMappingURL=uuid-ININPGKB.d.mts.map

package/dist/wordlist-B9EjFfv6.d.mts

@@ -0,0 +1,6 @@
+//#region src/common/data/wordlist.d.ts
+declare function Uint8ArrayToWords(bytes: Uint8Array, sepPair?: string, sepGroup?: string): string;
+declare function wordsToUint8Array(words: string[]): Uint8Array;
+//#endregion
+export { wordsToUint8Array as n, Uint8ArrayToWords as t };
+//# sourceMappingURL=wordlist-B9EjFfv6.d.mts.map

package/dist/wordlist-b4438KR_.d.cts

@@ -0,0 +1,6 @@
+//#region src/common/data/wordlist.d.ts
+declare function Uint8ArrayToWords(bytes: Uint8Array, sepPair?: string, sepGroup?: string): string;
+declare function wordsToUint8Array(words: string[]): Uint8Array;
+//#endregion
+export { wordsToUint8Array as n, Uint8ArrayToWords as t };
+//# sourceMappingURL=wordlist-b4438KR_.d.cts.map

package/dist/xaes-BuoCo_7y.d.cts

@@ -0,0 +1,41 @@
+//#region src/common/crypto/xaes.d.ts
+/**
+ * Encrypts data using XAES-256-GCM with the given key and iv.
+ * Key must be a 256-bit AES-CBC CryptoKey with 'encrypt' usage.
+ */
+declare function encryptXAES(params: {
+  iv: BufferSource;
+  additionalData?: BufferSource;
+}, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+/**
+ * Decrypts data using XAES-256-GCM with the given key and iv.
+ * Key must be a 256-bit AES-CBC CryptoKey with 'encrypt' and 'decrypt' usages.
+ */
+declare function decryptXAES(params: {
+  iv: BufferSource;
+  additionalData?: BufferSource;
+}, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+/**
+ * Generate a random key suitable for XAES-256-GCM.
+ * The actual key is an AES-CBC CryptoKey with 256-bit length.
+ *
+ * This function is not necessary, as you can use crypto.subtle.generateKey with AES-CBC directly.
+ */
+declare function generateKeyXAES(extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Import a key suitable for XAES-256-GCM.
+ * The actual key must be an AES-CBC CryptoKey with 256-bit length.
+ *
+ * This function is not necessary, as you can use crypto.subtle.importKey with AES-CBC directly.
+ */
+declare function importKeyXAES(format: 'jwk' | 'raw' | 'pkcs8' | 'spki', keyData: BufferSource | JsonWebKey, extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Export a key.
+ * The resulting export will have AES-CBC algorithm specified.
+ *
+ * This function is not necessary, as you can use crypto.subtle.exportKey directly.
+ */
+declare function exportKeyXAES(format: 'jwk' | 'pkcs8' | 'raw' | 'spki', key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
+//#endregion
+export { importKeyXAES as a, generateKeyXAES as i, encryptXAES as n, exportKeyXAES as r, decryptXAES as t };
+//# sourceMappingURL=xaes-BuoCo_7y.d.cts.map

package/dist/xaes-CTLXxroU.d.mts

@@ -0,0 +1,41 @@
+//#region src/common/crypto/xaes.d.ts
+/**
+ * Encrypts data using XAES-256-GCM with the given key and iv.
+ * Key must be a 256-bit AES-CBC CryptoKey with 'encrypt' usage.
+ */
+declare function encryptXAES(params: {
+  iv: BufferSource;
+  additionalData?: BufferSource;
+}, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+/**
+ * Decrypts data using XAES-256-GCM with the given key and iv.
+ * Key must be a 256-bit AES-CBC CryptoKey with 'encrypt' and 'decrypt' usages.
+ */
+declare function decryptXAES(params: {
+  iv: BufferSource;
+  additionalData?: BufferSource;
+}, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+/**
+ * Generate a random key suitable for XAES-256-GCM.
+ * The actual key is an AES-CBC CryptoKey with 256-bit length.
+ *
+ * This function is not necessary, as you can use crypto.subtle.generateKey with AES-CBC directly.
+ */
+declare function generateKeyXAES(extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Import a key suitable for XAES-256-GCM.
+ * The actual key must be an AES-CBC CryptoKey with 256-bit length.
+ *
+ * This function is not necessary, as you can use crypto.subtle.importKey with AES-CBC directly.
+ */
+declare function importKeyXAES(format: 'jwk' | 'raw' | 'pkcs8' | 'spki', keyData: BufferSource | JsonWebKey, extractable?: boolean): Promise<CryptoKey>;
+/**
+ * Export a key.
+ * The resulting export will have AES-CBC algorithm specified.
+ *
+ * This function is not necessary, as you can use crypto.subtle.exportKey directly.
+ */
+declare function exportKeyXAES(format: 'jwk' | 'pkcs8' | 'raw' | 'spki', key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
+//#endregion
+export { importKeyXAES as a, generateKeyXAES as i, encryptXAES as n, exportKeyXAES as r, decryptXAES as t };
+//# sourceMappingURL=xaes-CTLXxroU.d.mts.map

package/dist/xrx-CNr9xKen.d.cts

@@ -0,0 +1,19 @@
+//#region src/common/data/xrx.d.ts
+declare function regExpString(rx: string | RegExp): string;
+declare function regExpEscape(str: string): string;
+declare class XRX {
+  lookBehind: any;
+  namedGroups: Record<string, number>;
+  names: string[];
+  rx: RegExp;
+  constructor(pattern: string | RegExp, flags?: string);
+  get lastIndex(): number;
+  set lastIndex(index: number);
+  _handleMatch(m: any): any;
+  exec(str: string): any;
+  execAll(str: string): any[];
+  replace(str: string, replacement: string | ((m: string) => string)): string;
+}
+//#endregion
+export { regExpEscape as n, regExpString as r, XRX as t };
+//# sourceMappingURL=xrx-CNr9xKen.d.cts.map

package/dist/xrx-DN94xdqR.d.mts

@@ -0,0 +1,19 @@
+//#region src/common/data/xrx.d.ts
+declare function regExpString(rx: string | RegExp): string;
+declare function regExpEscape(str: string): string;
+declare class XRX {
+  lookBehind: any;
+  namedGroups: Record<string, number>;
+  names: string[];
+  rx: RegExp;
+  constructor(pattern: string | RegExp, flags?: string);
+  get lastIndex(): number;
+  set lastIndex(index: number);
+  _handleMatch(m: any): any;
+  exec(str: string): any;
+  execAll(str: string): any[];
+  replace(str: string, replacement: string | ((m: string) => string)): string;
+}
+//#endregion
+export { regExpEscape as n, regExpString as r, XRX as t };
+//# sourceMappingURL=xrx-DN94xdqR.d.mts.map

package/dist/z-ClMox7qS.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/z-collection-BmuBin--.d.mts

@@ -0,0 +1,9 @@
+import { C as rpc, D as union, E as tuple, S as record, T as stringLiterals, _ as literal, b as object, d as array, f as boolean, g as int, h as func, m as float, n as Type, p as double, t as Infer, u as any, v as none, w as string, x as real, y as number } from "./schema-eMFkYY24.mjs";
+
+//#region src/common/schema/z-collection.d.ts
+declare namespace z_collection_d_exports {
+  export { any, array, boolean, double, stringLiterals as enum, float, func, Infer as infer, int, literal, none, number, object, real, record, rpc, string, tuple, Type as type, union };
+}
+//#endregion
+export { z_collection_d_exports as t };
+//# sourceMappingURL=z-collection-BmuBin--.d.mts.map

package/dist/z-collection-HtNirovS.d.cts

@@ -0,0 +1,9 @@
+import { C as rpc, D as union, E as tuple, S as record, T as stringLiterals, _ as literal, b as object, d as array, f as boolean, g as int, h as func, m as float, n as Type, p as double, t as Infer, u as any, v as none, w as string, x as real, y as number } from "./schema-BNke0iHR.cjs";
+
+//#region \0rolldown/runtime.js
+declare namespace z_collection_d_exports {
+  export { any, array, boolean, double, stringLiterals as enum, float, func, Infer as infer, int, literal, none, number, object, real, record, rpc, string, tuple, Type as type, union };
+}
+//#endregion
+export { z_collection_d_exports as t };
+//# sourceMappingURL=z-collection-HtNirovS.d.cts.map

package/dist/z-dtM4F8Lo.d.cts

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "zeed",
   "type": "module",
-  "version": "1.2.2",
+  "version": "1.3.0",
+  "packageManager": "pnpm@10.32.1",
   "description": "🌱 Simple foundation library",
   "author": {
     "name": "Dirk Holtwick",
@@ -34,15 +35,16 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.all.d.ts",
-      "node": "./dist/index.node.js",
-      "default": "./dist/index.browser.js"
+      "types": "./dist/index.all.d.mts",
+      "require": "./dist/index.node.cjs",
+      "node": "./dist/index.node.mjs",
+      "default": "./dist/index.browser.mjs"
     },
     "./eslint": "./src/eslint-defaults.js"
   },
   "main": "dist/index.node.cjs",
-  "module": "dist/index.browser.js",
-  "types": "dist/index.all.d.ts",
+  "module": "dist/index.browser.mjs",
+  "types": "dist/index.all.d.mts",
   "files": [
     "AGENTS.md",
     "LICENSE",
@@ -54,24 +56,8 @@
   "engines": {
     "node": ">=20"
   },
-  "devDependencies": {
-    "@antfu/eslint-config": "^7.3.0",
-    "@antfu/ni": "^28.2.0",
-    "@types/node": "^25.2.2",
-    "@vitejs/plugin-vue": "^6.0.4",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18",
-    "esbuild": "^0.27.3",
-    "eslint": "<10.0.0",
-    "playwright": "^1.58.2",
-    "pnpm": "^10.17.1",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
-  },
   "scripts": {
-    "build": "nr clean && NODE_ENV=production tsup",
+    "build": "nr clean && NODE_ENV=production tsdown",
     "build:docs": "nlx typedoc --skipErrorChecking ./src/index.all.ts",
     "check": "tsc --noEmit --skipLibCheck",
     "credits": "nlx credits-cli",
@@ -81,16 +67,33 @@
     "coverage": "vitest --run --coverage",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "prepublishOnly": "nr build && nr circles",
     "start": "nr watch",
     "test": "nr check && vitest --run",
-    "test:release": "nr lint:fix && nr check && vitest --run",
-    "post:release": "nr upload:docs",
     "test:browser": "PREVIEW=1 vitest",
     "test:firefox": "BROWSER=firefox vitest",
     "test:webkit": "BROWSER=webkit vitest",
     "test:chromium": "BROWSER=chromium vitest",
-    "test:publish": "vitest --run",
+    "test:release": "nr lint:fix && nr check && vitest --run",
+    "post:release": "nr upload:docs && nr npm:release",
+    "npm:release": "npm login && npm publish --access public",
     "watch": "nr build -- --watch src",
     "prep": "nr lint:fix && nr check && nr test:release && nr upload:docs"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.7.2",
+    "@antfu/ni": "^28.3.0",
+    "@types/node": "^25.5.0",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "@vitest/browser": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "esbuild": "^0.27.4",
+    "eslint": "^10.0.3",
+    "playwright": "^1.58.2",
+    "pnpm": "^10.32.1",
+    "tsdown": "^0.21.2",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   }
-}
+}

package/src/browser/log/log-colors.ts

@@ -19,7 +19,7 @@ export function browserSupportsColors(): boolean {
   if (
     typeof navigator !== 'undefined'
     && navigator.userAgent
-    && navigator.userAgent.toLowerCase().match(/(edge|trident)\/(\d+)/)
+    && /(?:edge|trident)\/\d+/.test(navigator.userAgent.toLowerCase())
   ) {
     return false
   }

package/src/common/bin/lib0/buffer.spec.ts

@@ -11,7 +11,7 @@ describe('lib0/buffer', () => {
     const arr = new Uint8Array([1, 2, 3])
     const copy = copyUint8Array(arr)
     expect(copy).not.toBe(arr)
-    expect(Array.from(copy)).toEqual([1, 2, 3])
+    expect([...copy]).toEqual([1, 2, 3])
   })
 
   it('should encode and decode any value', () => {

package/src/common/bin/lib0/decoding.spec.ts

@@ -34,7 +34,7 @@ describe('lib0/decoding', () => {
     const arr = new Uint8Array(e.cbuf.buffer, 0, e.cpos)
     const d = createDecoder(arr)
     expect(readVarString(d)).toBe('hello')
-    expect(Array.from(readVarUint8Array(d))).toEqual([1, 2, 3])
+    expect([...readVarUint8Array(d)]).toEqual([1, 2, 3])
   })
 
   it('should decode floats and bigints', () => {
@@ -75,7 +75,7 @@ describe('lib0/decoding', () => {
     expect(readAny(d)).toBe(false)
     expect(readAny(d)).toBe('str')
     expect(readAny(d)).toEqual([1, 2, 3])
-    expect(Array.from(readAny(d))).toEqual([1, 2, 3])
+    expect([...readAny(d)]).toEqual([1, 2, 3])
     expect(readAny(d)).toEqual({ a: 1, b: 2 })
   })
 

package/src/common/bin/lib0/decoding.ts

@@ -275,7 +275,7 @@ function _readVarStringPolyfill(decoder: BinDecoder): string {
         const bytes = decoder.arr.subarray(decoder.pos, decoder.pos + nextLen)
         decoder.pos += nextLen
         // Starting with ES5.1 we can supply a generic array-like object as arguments
-        encodedString += String.fromCodePoint.apply(null, (bytes as any))
+        encodedString += String.fromCodePoint(...bytes as any)
         remainingLen -= nextLen
       }
     }

package/src/common/bin/lib0/encoding.ts

@@ -344,8 +344,7 @@ let floatTestBed: DataView
  * Check if a number can be encoded as a 32 bit float.
  */
 function isFloat32(num: number): boolean {
-  if (floatTestBed == null)
-    floatTestBed = new DataView(new ArrayBuffer(4))
+  floatTestBed ??= new DataView(new ArrayBuffer(4))
   floatTestBed.setFloat32(0, num)
   return floatTestBed.getFloat32(0) === num
 }

package/src/common/bin/lib0/string.ts

@@ -63,7 +63,7 @@ function _decodeUtf8Polyfill(buf: Uint8Array): string {
     const bytes = buf.subarray(bufPos, bufPos + nextLen)
     bufPos += nextLen
     // Starting with ES5.1 we can supply a generic array-like object as arguments
-    encodedString += String.fromCodePoint.apply(null, (bytes as any))
+    encodedString += String.fromCodePoint(...bytes as any)
     remainingLen -= nextLen
   }
   return decodeURIComponent(escape(encodedString))

package/src/common/crypto/crypto.spec.ts

@@ -1,6 +1,6 @@
-/* eslint-disable prefer-spread */
 /* eslint-disable no-cond-assign */
 
+import { createArray } from '../data'
 import { equalBinary, fromBase64, toBase64 } from '../data/bin'
 import { DefaultLogger } from '../log/log'
 import { decrypt, deriveKeyPbkdf2, digest, encrypt, randomUint8Array } from './crypto'
@@ -10,9 +10,7 @@ const log = DefaultLogger('crypto.spec')
 describe('crypto', () => {
   it('should not have collisions', () => {
     expect(equalBinary(new Uint8Array(2), new Uint8Array([0, 0]))).toBe(true)
-    const list: Uint8Array[] = Array.apply(null, Array.from({ length: 100 })).map(() =>
-      randomUint8Array(8),
-    )
+    const list: Uint8Array[] = createArray(100, () => randomUint8Array(8))
     let id: Uint8Array | undefined
     while ((id = list.pop())) {
       // console.log(id)

package/src/common/data/day.spec.ts

@@ -1,4 +1,4 @@
-import { dayDiff, dayFromAny, dayFromDate, dayFromString, dayFromTimestamp, dayFromTimestampSeconds, dayFromToday, dayIterator, dayMonthStart, dayOffset, dayRange, dayToDate, dayToParts, dayToString, dayToTimestamp, dayToTimestampSeconds, dayYearStart } from './day'
+import { dayDiff, dayFromAny, dayFromDate, dayFromString, dayFromTimestamp, dayFromTimestampSeconds, dayFromToday, dayIterator, dayMonthOffset, dayMonthStart, dayOffset, dayRange, dayToDate, dayToParts, dayToString, dayToTimestamp, dayToTimestampSeconds, dayYearOffset, dayYearStart } from './day'
 import { Day, dateStringToDays, forEachDay } from './day-legacy'
 
 describe('days', () => {
@@ -155,6 +155,25 @@ describe('days', () => {
       expect(dayYearStart(d, -10)).toMatchInlineSnapshot('19890101')
       expect(dayYearStart(d, +10)).toMatchInlineSnapshot('20090101')
     }
+    {
+      const d = dayFromString('2021-01-31')!
+      expect(dayMonthOffset(d, +1)).toBe(20210228)
+      expect(dayMonthOffset(d, +2)).toBe(20210331)
+      expect(dayMonthOffset(d, -1)).toBe(20201231)
+    }
+    {
+      const d = dayFromString('2020-01-31')!
+      expect(dayMonthOffset(d, +1)).toBe(20200229)
+    }
+    {
+      const d = dayFromString('2020-02-29')!
+      expect(dayYearOffset(d, +1)).toBe(20210228)
+      expect(dayYearOffset(d, -1)).toBe(20190228)
+    }
+    {
+      const d = dayFromString('2021-03-31')!
+      expect(dayYearOffset(d, +1)).toBe(20220331)
+    }
   })
 
   it('should parse date string', () => {

package/src/common/data/day.ts

@@ -283,6 +283,30 @@ export function dayMonthStart(day: DayValue, offset = 0): DayValue {
   return dayFromParts(year, month, 1)!
 }
 
+/**
+ * Return the day offset by whole months, keeping the day-of-month when possible.
+ * If the target month has fewer days, the result is clamped to the last day.
+ *
+ * @param day - source DayValue
+ * @param offset - months to offset (positive or negative)
+ */
+export function dayMonthOffset(day: DayValue, offset: number): DayValue {
+  let year = dayYear(day)
+  let month = dayMonth(day)
+  const dayOfMonth = dayDay(day)
+
+  if (offset !== 0) {
+    month += offset
+    year += Math.floor((month - 1) / 12)
+    month = Math.floor((month - 1) % 12) + 1
+    if (month === 0)
+      month = 12
+  }
+
+  const maxDay = dayDaysInMonth(year, month)
+  return dayFromParts(year, month, Math.min(dayOfMonth, maxDay))!
+}
+
 /**
  * Return the first day of the year for the given DayValue. `offset` moves
  * the year by the given amount.
@@ -292,6 +316,26 @@ export function dayYearStart(day: DayValue, offset = 0): DayValue {
   return dayFromParts(year + offset, 1, 1)!
 }
 
+/**
+ * Return the day offset by whole years, keeping month and day when possible.
+ * If the target month has fewer days, the result is clamped to the last day.
+ *
+ * @param day - source DayValue
+ * @param offset - years to offset (positive or negative)
+ */
+export function dayYearOffset(day: DayValue, offset: number): DayValue {
+  const year = dayYear(day) + offset
+  const month = dayMonth(day)
+  const dayOfMonth = dayDay(day)
+  const maxDay = dayDaysInMonth(year, month)
+  return dayFromParts(year, month, Math.min(dayOfMonth, maxDay))!
+}
+
+/** Return number of days in a given month. Month is 1-12. */
+export function dayDaysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate()
+}
+
 /**
  * Offset a DayValue by a number of days. Uses timestamp math to avoid local
  * DST issues.