@simplysm/core-common 13.0.81 → 13.0.83

package/docs/types.md

@@ -0,0 +1,242 @@
+# Types
+
+Immutable date/time classes, UUID, auto-expiring map, and shared type aliases.
+
+## DateTime
+
+```typescript
+class DateTime {
+  constructor();
+  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): DateTime;
+
+  readonly date: Date;
+
+  get year(): number;
+  get month(): number;
+  get day(): number;
+  get hour(): number;
+  get minute(): number;
+  get second(): number;
+  get millisecond(): number;
+  get tick(): number;
+  get dayOfWeek(): number;
+  get timezoneOffsetMinutes(): number;
+  get isValid(): boolean;
+
+  setYear(year: number): DateTime;
+  setMonth(month: number): DateTime;
+  setDay(day: number): DateTime;
+  setHour(hour: number): DateTime;
+  setMinute(minute: number): DateTime;
+  setSecond(second: number): DateTime;
+  setMillisecond(millisecond: number): DateTime;
+
+  addYears(years: number): DateTime;
+  addMonths(months: number): DateTime;
+  addDays(days: number): DateTime;
+  addHours(hours: number): DateTime;
+  addMinutes(minutes: number): DateTime;
+  addSeconds(seconds: number): DateTime;
+  addMilliseconds(milliseconds: number): DateTime;
+
+  toFormatString(formatStr: string): string;
+  toString(): string; // "yyyy-MM-ddTHH:mm:ss.fffzzz"
+}
+```
+
+Immutable DateTime class wrapping JavaScript `Date`. Supports millisecond precision with local timezone. All setter and add methods return a new instance.
+
+**Parsing formats:** `yyyy-MM-dd HH:mm:ss`, `yyyy-MM-dd HH:mm:ss.fff`, `yyyyMMddHHmmss`, `yyyy-MM-dd AM/PM HH:mm:ss`, ISO 8601.
+
+---
+
+## DateOnly
+
+```typescript
+class DateOnly {
+  constructor();
+  constructor(year: number, month: number, day: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): DateOnly;
+  static getDateByYearWeekSeq(
+    arg: { year: number; month?: number; weekSeq: number },
+    weekStartDay?: number,
+    minDaysInFirstWeek?: number,
+  ): DateOnly;
+
+  readonly date: Date;
+
+  get year(): number;
+  get month(): number;
+  get day(): number;
+  get tick(): number;
+  get dayOfWeek(): number;
+  get isValid(): boolean;
+
+  setYear(year: number): DateOnly;
+  setMonth(month: number): DateOnly;
+  setDay(day: number): DateOnly;
+
+  addYears(years: number): DateOnly;
+  addMonths(months: number): DateOnly;
+  addDays(days: number): DateOnly;
+
+  getBaseYearMonthSeqForWeekSeq(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number };
+  getWeekSeqStartDate(weekStartDay?: number, minDaysInFirstWeek?: number): DateOnly;
+  getWeekSeqOfYear(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; weekSeq: number };
+  getWeekSeqOfMonth(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number; weekSeq: number };
+
+  toFormatString(formatStr: string): string;
+  toString(): string; // "yyyy-MM-dd"
+}
+```
+
+Immutable date-only class (no time). Includes ISO 8601 week calculation utilities.
+
+**Parsing formats:** `yyyy-MM-dd`, `yyyyMMdd`, ISO 8601.
+
+---
+
+## Time
+
+```typescript
+class Time {
+  constructor();
+  constructor(hour: number, minute: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): Time;
+
+  get hour(): number;
+  get minute(): number;
+  get second(): number;
+  get millisecond(): number;
+  get tick(): number;
+  get isValid(): boolean;
+
+  setHour(hour: number): Time;
+  setMinute(minute: number): Time;
+  setSecond(second: number): Time;
+  setMillisecond(millisecond: number): Time;
+
+  addHours(hours: number): Time;
+  addMinutes(minutes: number): Time;
+  addSeconds(seconds: number): Time;
+  addMilliseconds(milliseconds: number): Time;
+
+  toFormatString(formatStr: string): string;
+  toString(): string; // "HH:mm:ss.fff"
+}
+```
+
+Immutable time-only class. Values exceeding 24 hours or negative values are automatically normalized with wraparound.
+
+**Parsing formats:** `HH:mm:ss`, `HH:mm:ss.fff`, `AM/PM HH:mm:ss`, ISO 8601 (time part extracted).
+
+---
+
+## Uuid
+
+```typescript
+class Uuid {
+  static generate(): Uuid;
+  static fromBytes(bytes: Bytes): Uuid;
+
+  constructor(uuid: string);
+
+  toString(): string;
+  toBytes(): Bytes;
+}
+```
+
+UUID v4 class using `crypto.getRandomValues`. Validates format on construction.
+
+---
+
+## LazyGcMap
+
+```typescript
+class LazyGcMap<TKey, TValue> {
+  constructor(options: {
+    gcInterval?: number;
+    expireTime: number;
+    onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
+  });
+
+  get size(): number;
+
+  has(key: TKey): boolean;
+  get(key: TKey): TValue | undefined;
+  set(key: TKey, value: TValue): void;
+  delete(key: TKey): boolean;
+  clear(): void;
+  getOrCreate(key: TKey, factory: () => TValue): TValue;
+
+  values(): IterableIterator<TValue>;
+  keys(): IterableIterator<TKey>;
+  entries(): IterableIterator<[TKey, TValue]>;
+
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+A Map with LRU-style automatic expiration. Access time is updated on `get` and `getOrCreate`. Entries not accessed within `expireTime` are automatically removed. Must call `dispose()` or use `using` statement to stop the GC timer.
+
+---
+
+## Type Aliases
+
+```typescript
+type Bytes = Uint8Array;
+
+type PrimitiveTypeStr = "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes";
+
+type PrimitiveType = string | number | boolean | DateTime | DateOnly | Time | Uuid | Bytes | undefined;
+
+type DeepPartial<T> = Partial<{ [K in keyof T]: T[K] extends PrimitiveType ? T[K] : DeepPartial<T[K]> }>;
+
+interface Type<T> extends Function {
+  new (...args: unknown[]): T;
+}
+```
+
+---
+
+## Usage Examples
+
+```typescript
+import { DateTime, DateOnly, Time, Uuid, LazyGcMap } from "@simplysm/core-common";
+
+// DateTime
+const now = new DateTime();
+const specific = new DateTime(2025, 3, 15, 10, 30, 0);
+const parsed = DateTime.parse("2025-03-15 10:30:00");
+const tomorrow = now.addDays(1);
+const formatted = now.toFormatString("yyyy-MM-dd HH:mm");
+
+// DateOnly
+const today = new DateOnly();
+const week = today.getWeekSeqOfYear(); // { year, weekSeq }
+
+// Time
+const time = new Time(14, 30, 0);
+const wrapped = time.addHours(12); // wraps around 24h
+
+// Uuid
+const id = Uuid.generate();
+const bytes = id.toBytes();
+const restored = Uuid.fromBytes(bytes);
+
+// LazyGcMap
+using cache = new LazyGcMap<string, object>({ expireTime: 60_000 });
+cache.set("key", { data: 1 });
+const val = cache.getOrCreate("key2", () => ({ data: 2 }));
+```

package/docs/wait-utilities.md

@@ -0,0 +1,50 @@
+# Wait Utilities
+
+Imported as the `wait` namespace. Async timing utilities.
+
+```typescript
+import { wait } from "@simplysm/core-common";
+```
+
+## time
+
+```typescript
+function time(millisecond: number): Promise<void>;
+```
+
+Waits for the specified number of milliseconds.
+
+---
+
+## until
+
+```typescript
+function until(
+  forwarder: () => boolean | Promise<boolean>,
+  milliseconds?: number,
+  maxCount?: number,
+): Promise<void>;
+```
+
+Polls a condition at the given interval (default: 100ms) until it returns `true`. Returns immediately if the condition is `true` on the first call. Throws `TimeoutError` if `maxCount` attempts are exhausted.
+
+---
+
+## Usage Examples
+
+```typescript
+import { wait } from "@simplysm/core-common";
+
+// Simple delay
+await wait.time(1000); // wait 1 second
+
+// Poll until condition is met
+await wait.until(() => isReady, 100, 50);
+// Checks every 100ms, up to 50 times (5 seconds total)
+
+// With async condition
+await wait.until(async () => {
+  const status = await checkStatus();
+  return status === "complete";
+}, 500);
+```

package/docs/xml-utilities.md

@@ -0,0 +1,48 @@
+# XML Utilities
+
+Imported as the `xml` namespace. XML parsing and serialization via `fast-xml-parser`.
+
+```typescript
+import { xml } from "@simplysm/core-common";
+```
+
+## parse
+
+```typescript
+function parse(str: string, options?: { stripTagPrefix?: boolean }): unknown;
+```
+
+Parses an XML string into an object. Attributes are grouped under `$`, text content under `_`, and child elements are converted to arrays (except the root). Set `stripTagPrefix` to remove namespace prefixes from tag names.
+
+---
+
+## stringify
+
+```typescript
+function stringify(obj: unknown, options?: XmlBuilderOptions): string;
+```
+
+Serializes an object to XML string. Accepts optional `fast-xml-parser` builder options.
+
+---
+
+## Usage Examples
+
+```typescript
+import { xml } from "@simplysm/core-common";
+
+const obj = xml.parse('<root id="1"><item>hello</item><item>world</item></root>');
+// { root: { $: { id: "1" }, item: [{ _: "hello" }, { _: "world" }] } }
+
+const xmlStr = xml.stringify({
+  root: {
+    $: { id: "1" },
+    item: [{ _: "hello" }, { _: "world" }],
+  },
+});
+// '<root id="1"><item>hello</item><item>world</item></root>'
+
+// Strip namespace prefixes
+xml.parse('<ns:root><ns:item>test</ns:item></ns:root>', { stripTagPrefix: true });
+// { root: { item: [{ _: "test" }] } }
+```

package/docs/zip-archive.md

@@ -0,0 +1,61 @@
+# ZIP Archive
+
+The `ZipArchive` class for reading, writing, and compressing ZIP files. Uses `@zip.js/zip.js` internally.
+
+Directly exported (not namespaced).
+
+```typescript
+import { ZipArchive } from "@simplysm/core-common";
+```
+
+## ZipArchive
+
+```typescript
+class ZipArchive {
+  constructor(data?: Blob | Bytes);
+
+  get(fileName: string): Promise<Bytes | undefined>;
+  exists(fileName: string): Promise<boolean>;
+  write(fileName: string, bytes: Bytes): void;
+  extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
+  compress(): Promise<Bytes>;
+  close(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+interface ZipArchiveProgress {
+  fileName: string;
+  totalSize: number;
+  extractedSize: number;
+}
+```
+
+- **Read mode:** Pass existing ZIP data (`Blob` or `Uint8Array`) to the constructor. Use `get()` for individual files or `extractAll()` for everything.
+- **Write mode:** Omit the constructor argument. Use `write()` to add files, then `compress()` to generate the ZIP.
+- Supports `await using` syntax for automatic cleanup.
+- Internally caches decompressed files to prevent duplicate extraction.
+
+---
+
+## Usage Examples
+
+```typescript
+import { ZipArchive } from "@simplysm/core-common";
+
+// Read a ZIP file
+await using archive = new ZipArchive(zipBytes);
+const content = await archive.get("file.txt");
+const exists = await archive.exists("data.json");
+
+// Extract all with progress
+const files = await archive.extractAll((progress) => {
+  const pct = (progress.extractedSize / progress.totalSize * 100).toFixed(1);
+  console.log(`${progress.fileName}: ${pct}%`);
+});
+
+// Create a new ZIP file
+await using newArchive = new ZipArchive();
+newArchive.write("hello.txt", new TextEncoder().encode("Hello World"));
+newArchive.write("data.json", new TextEncoder().encode('{"key":"value"}'));
+const zipOutput = await newArchive.compress();
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "13.0.81",
+  "version": "13.0.83",
   "description": "Simplysm package - Core module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",