@simplysm/core-common 13.0.85 → 13.0.87

package/docs/template-strings.md

@@ -1,105 +0,0 @@
-# Template Strings
-
-Tagged template literals for IDE code highlighting with automatic indentation normalization.
-
-These are directly exported (not namespaced).
-
-```typescript
-import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
-```
-
-## js
-
-```typescript
-function js(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for JavaScript code. Provides syntax highlighting in supported IDEs and normalizes indentation.
-
----
-
-## ts
-
-```typescript
-function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for TypeScript code.
-
----
-
-## html
-
-```typescript
-function html(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for HTML markup.
-
----
-
-## tsql
-
-```typescript
-function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for MSSQL T-SQL queries.
-
----
-
-## mysql
-
-```typescript
-function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for MySQL SQL queries.
-
----
-
-## pgsql
-
-```typescript
-function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-Template tag for PostgreSQL SQL queries.
-
----
-
-## Behavior
-
-All template tags perform the same operations:
-1. Concatenate the template strings with interpolated values.
-2. Strip leading and trailing empty lines.
-3. Determine the minimum indentation across all non-empty lines.
-4. Remove that common indentation prefix from every line.
-
----
-
-## Usage Examples
-
-```typescript
-import { js, html, tsql } from "@simplysm/core-common";
-
-const name = "World";
-const code = js`
-  function hello() {
-    return "${name}";
-  }
-`;
-// "function hello() {\n  return \"World\";\n}"
-
-const markup = html`
-  <div class="container">
-    <span>${name}</span>
-  </div>
-`;
-
-const query = tsql`
-  SELECT TOP 10 *
-  FROM Users
-  WHERE Name LIKE '%${name}%'
-`;
-```

package/docs/transfer-utilities.md

@@ -1,53 +0,0 @@
-# Transfer Utilities
-
-Imported as the `transfer` namespace. Serialization/deserialization for Worker data transfer.
-
-```typescript
-import { transfer } from "@simplysm/core-common";
-```
-
-## encode
-
-```typescript
-function encode(obj: unknown): {
-  result: unknown;
-  transferList: Transferable[];
-};
-```
-
-Converts objects with custom types into plain objects suitable for `postMessage`. Returns the encoded result and a list of transferable `ArrayBuffer` objects for zero-copy transfer. Throws `TypeError` on circular references (with path info).
-
-**Supported types:** `Date`, `DateTime`, `DateOnly`, `Time`, `Uuid`, `RegExp`, `Error`, `Uint8Array`, `Array`, `Map`, `Set`, plain objects.
-
----
-
-## decode
-
-```typescript
-function decode(obj: unknown): unknown;
-```
-
-Restores tagged objects (with `__type__` markers) back to their original custom types. Use this on the receiving side of Worker messages.
-
----
-
-## Usage Examples
-
-```typescript
-import { transfer, DateTime, Uuid } from "@simplysm/core-common";
-
-// Sending data to Worker
-const data = {
-  id: Uuid.generate(),
-  timestamp: new DateTime(),
-  buffer: new Uint8Array([1, 2, 3]),
-};
-const { result, transferList } = transfer.encode(data);
-worker.postMessage(result, transferList);
-
-// Receiving data from Worker
-worker.onmessage = (event) => {
-  const decoded = transfer.decode(event.data);
-  // decoded.id is Uuid, decoded.timestamp is DateTime, etc.
-};
-```

package/docs/wait-utilities.md

@@ -1,50 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 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

@@ -1,61 +0,0 @@
-# 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();
-```