@tstdl/base 0.93.139 → 0.93.140

package/intl/README.md

@@ -0,0 +1,113 @@
+# @tstdl/base/intl
+
+The `intl` module provides utilities for handling internationalization tasks, specifically focusing on robust, locale-aware number parsing. It allows you to convert formatted number strings (e.g., "1.234,56" in German) back into standard JavaScript numbers by correctly identifying decimal and group separators based on the locale.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Loose Parsing](#loose-parsing)
+  - [Non-Latin Numerals](#non-latin-numerals)
+  - [Performance & Memoization](#performance--memoization)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Locale-Aware Parsing**: Handles `,`, `.`, and spaces as separators depending on the locale.
+- **Group Separator Support**: Automatically handles thousands separators (e.g., `1,000` vs `1.000`).
+- **Loose Mode**: Strips non-numeric characters (like currency symbols or units) before parsing.
+- **Numeral System Support**: Automatically maps non-Latin numerals (e.g., Arabic-Indic `١٢٣`) to standard digits.
+- **Memoization**: Optimized performance through cached parser instances.
+
+## Core Concepts
+
+Standard JavaScript functions like `parseFloat()` or `Number()` are designed for machine-readable formats (usually English-based, using `.` for decimals and no thousands separators). They often fail or produce incorrect results when dealing with user input in other locales (e.g., `parseFloat('1.234,56')` results in `1.234` instead of `1234.56`).
+
+The `NumberParser` class uses the native `Intl.NumberFormat` API to inspect the formatting rules of a given locale. It normalizes the input string by removing group separators and converting decimal separators to `.` before using the standard `Number()` constructor.
+
+## 🚀 Basic Usage
+
+The most common way to use this module is via the `parseNumber` helper function.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// US English: Comma for thousands, Dot for decimals
+const usValue = parseNumber('en-US', '12,345.67');
+console.log(usValue); // 12345.67
+
+// German: Dot for thousands, Comma for decimals
+const deValue = parseNumber('de-DE', '12.345,67');
+console.log(deValue); // 12345.67
+
+// French: Space for thousands, Comma for decimals
+const frValue = parseNumber('fr-FR', '12 345,67');
+console.log(frValue); // 12345.67
+```
+
+## 🔧 Advanced Topics
+
+### Loose Parsing
+
+When dealing with user input or scraped data, strings often contain currency symbols, units, or other text. The `loose` parameter (default `false`) instructs the parser to strip out any characters that are not valid numerals or separators for the target locale before parsing.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// Standard parsing fails on non-numeric characters
+const strict = parseNumber('en-US', '$1,234.56 USD');
+console.log(strict); // NaN
+
+// Loose parsing strips the currency symbol and text
+const loose = parseNumber('en-US', '$1,234.56 USD', true);
+console.log(loose); // 1234.56
+
+// Works with locale-specific formatting
+const looseDe = parseNumber('de-DE', '1.234,56 €', true);
+console.log(looseDe); // 1234.56
+```
+
+### Non-Latin Numerals
+
+The module automatically handles locales that use non-Latin numeral systems by mapping them back to standard digits.
+
+```typescript
+import { parseNumber } from '@tstdl/base/intl';
+
+// Arabic (Egypt): Uses Arabic-Indic numerals
+const arValue = parseNumber('ar-EG', '١٢٬٣٤٥٫٦٧');
+console.log(arValue); // 12345.67
+```
+
+### Performance & Memoization
+
+Creating a `NumberParser` instance involves some overhead. To mitigate this, the module exports `getNumberParser`, which memoizes instances based on the locale string. The `parseNumber` helper uses this internally.
+
+```typescript
+import { getNumberParser } from '@tstdl/base/intl';
+
+// Uses the memoized instance (Recommended)
+const parser = getNumberParser('en-GB');
+const value = parser.parse('10,000.50');
+```
+
+## 📚 API
+
+### Functions
+
+| Function | Description |
+| :--- | :--- |
+| `parseNumber(locale: string, value: string, loose?: boolean): number` | Parses a localized string into a number. |
+| `getNumberParser(locale: string): NumberParser` | Returns a memoized `NumberParser` instance for the specified locale. |
+
+### Classes
+
+#### `NumberParser`
+
+| Method / Property | Type | Description |
+| :--- | :--- | :--- |
+| `constructor(locale: string)` | `void` | Creates a new parser for the given locale. |
+| `locale` | `string` | The locale string this parser was initialized with. |
+| `parse(value: string, loose?: boolean): number` | `number` | Parses the string. If `loose` is true, strips invalid characters first. |

package/json-path/README.md

@@ -0,0 +1,182 @@
+# @tstdl/base/json-path
+
+A robust utility module for parsing, encoding, and manipulating JSON Path strings. It provides both functional helpers and a fluent class interface to convert between string representations (e.g., `$.users[0].name`) and structural arrays of property keys.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Using the JsonPath Class](#using-the-jsonpath-class)
+  - [Functional Encoding & Decoding](#functional-encoding--decoding)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Formatting Options](#formatting-options)
+  - [Working with Symbols](#working-with-symbols)
+  - [Iteration](#iteration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Two-way Conversion**: reliable parsing of JSON path strings into node arrays and encoding arrays back to strings.
+- **Fluent Interface**: An immutable `JsonPath` class for building and modifying paths.
+- **Symbol Support**: Handles `Symbol` property keys in paths.
+- **Configurable Formatting**: Control over dot notation vs. bracket notation and root prefixes.
+- **Type Safety**: Built with TypeScript for strong typing support.
+
+## Core Concepts
+
+A **JSON Path** is a string representing a location within a JSON object or array.
+
+- **Nodes**: The individual segments of a path. A node can be a `string`, `number` (array index), or `symbol`.
+- **Root**: The `$` character typically represents the root of the object.
+- **Notation**:
+  - **Dot Notation**: `.property` (used for valid identifiers).
+  - **Bracket Notation**: `['property']` or `[0]` (used for special characters, numbers, or when forced).
+
+## 🚀 Basic Usage
+
+### Using the JsonPath Class
+
+The `JsonPath` class provides an object-oriented, immutable way to manage paths.
+
+```ts
+import { JsonPath } from '@tstdl/base/json-path';
+
+// Create from a string
+const path = new JsonPath('$.users[0].profile');
+// or using static from
+const pathFromStr = JsonPath.from('$.users[0].profile');
+
+console.log(path.nodes); // ['users', 0, 'profile']
+
+// Create from an array of nodes
+const pathFromNodes = new JsonPath(['users', 0, 'profile']);
+console.log(pathFromNodes.toString()); // "$.users[0].profile"
+
+// Use the ROOT constant for the root path ($)
+const root = JsonPath.ROOT;
+console.log(root.toString()); // "$"
+```
+
+### Path Manipulation
+
+`JsonPath` instances are immutable. Methods that modify the path return a new instance.
+
+```ts
+import { JsonPath } from '@tstdl/base/json-path';
+
+const base = new JsonPath('$.data');
+
+// Add nodes
+const child = base.add('items').add(5);
+console.log(child.toString()); // "$.data.items[5]"
+
+// Slice nodes
+const sliced = child.slice(1, 2);
+console.log(sliced.toString()); // "$.items" (note: dollar prefix added by default)
+
+// Change options on an existing path
+const bracketed = child.options({ forceBrackets: true });
+console.log(bracketed.toString()); // "$['data']['items'][5]"
+```
+
+### Functional Encoding & Decoding
+
+You can use the standalone functions if you don't need the class wrapper.
+
+```ts
+import { encodeJsonPath, decodeJsonPath } from '@tstdl/base/json-path';
+
+// Encoding: Array -> String
+const encoded = encodeJsonPath(['store', 'book', 0, 'title']);
+console.log(encoded); // "$.store.book[0].title"
+
+// Decoding: String -> Array
+const decoded = decodeJsonPath('$.store.book[0].title');
+console.log(decoded); // ["store", "book", 0, "title"]
+```
+
+## 🔧 Advanced Topics
+
+### Formatting Options
+
+You can customize how the path string is generated using `JsonPathOptions`.
+
+```ts
+import { JsonPath, encodeJsonPath } from '@tstdl/base/json-path';
+
+const nodes = ['foo', 'bar', 0];
+
+// Option 1: Force brackets for everything
+const bracketPath = encodeJsonPath(nodes, { forceBrackets: true });
+console.log(bracketPath); // "$['foo']['bar'][0]"
+
+// Option 2: Treat array indices as object properties (dot notation)
+const dotPath = encodeJsonPath(nodes, { treatArrayAsObject: true });
+console.log(dotPath); // "$.foo.bar.0"
+
+// Option 3: Remove the root '$' prefix
+const noRootPath = encodeJsonPath(nodes, { dollar: false });
+console.log(noRootPath); // "foo.bar[0]"
+
+// Using options with the class
+const path = new JsonPath(['a', 'b'], { forceBrackets: true });
+console.log(path.toString()); // "$['a']['b']"
+```
+
+### Working with Symbols
+
+The module supports `Symbol` keys, which are encoded using the syntax `[Symbol(description)]`.
+
+```ts
+import { JsonPath, decodeJsonPath } from '@tstdl/base/json-path';
+
+const sym = Symbol('uniqueId'); // Note: not using Symbol.for here for the example
+const path = new JsonPath(['data', sym]);
+
+console.log(path.toString()); // "$.data[Symbol(uniqueId)]"
+
+// Decoding can map back to specific symbol instances via JsonPathContext
+const decodedNodes = decodeJsonPath('$.data[Symbol(uniqueId)]', { symbols: [sym] });
+const decodedSym = decodedNodes[1] as symbol;
+
+console.log(decodedSym === sym); // true
+
+// If no context is provided, it falls back to Symbol.for(description)
+const fallbackNodes = decodeJsonPath('$.data[Symbol(uniqueId)]');
+const fallbackSym = fallbackNodes[1] as symbol;
+
+console.log(fallbackSym === Symbol.for('uniqueId')); // true
+```
+
+### Iteration
+
+The `JsonPath` class implements `Iterable`, allowing you to loop over its nodes directly.
+
+```ts
+import { JsonPath } from '@tstdl/base/json-path';
+
+const path = new JsonPath('$.a.b.c');
+
+for (const node of path) {
+  console.log(node);
+}
+// Output:
+// "a"
+// "b"
+// "c"
+```
+
+## 📚 API
+
+| Export              | Type       | Description                                                                     |
+| :------------------ | :--------- | :------------------------------------------------------------------------------ |
+| `JsonPath`          | `class`    | Main class for building and manipulating JSON paths. Implements `Iterable`.     |
+| `JsonPathNode`      | `type`     | Alias for `PropertyKey` (`string \| number \| symbol`).                         |
+| `JsonPathInput`     | `type`     | `string \| JsonPath \| Iterable<JsonPathNode>`                                  |
+| `JsonPathOptions`   | `type`     | Configuration object for encoding behavior (`forceBrackets`, `dollar`, etc.).   |
+| `JsonPathContext`   | `type`     | Context for decoding (e.g., to map `Symbol` descriptions).                      |
+| `encodeJsonPath`    | `function` | Converts an array of nodes into a JSON Path string.                             |
+| `decodeJsonPath`    | `function` | Parses a JSON Path string into an array of nodes.                               |
+| `isJsonPath`        | `function` | Returns `true` if the string matches the JSON Path pattern.                     |
+| `isJsonPath` (stat) | `method`   | Static method on `JsonPath` class equivalent to the standalone function.        |

package/jsx/README.md

@@ -0,0 +1,154 @@
+# @tstdl/base/jsx
+
+A lightweight utility module for server-side rendering (SSR) of JSX/TSX content using Preact. It provides a unified API for synchronously and asynchronously rendering components and Virtual DOM nodes to HTML strings.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Asynchronous Rendering](#asynchronous-rendering)
+  - [Checking Component Types](#checking-component-types)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Unified Rendering API**: Render Functional Components, Class Components, or raw VNodes using the same function signature.
+- **Server-Side Rendering (SSR)**: Generate HTML strings from JSX for emails, PDF generation, or initial page loads.
+- **Async Support**: Native support for asynchronous rendering (e.g., for Suspense boundaries).
+- **Type Guards**: Utilities to distinguish between Component Classes and Functional Components at runtime.
+
+## Core Concepts
+
+This module wraps `preact-render-to-string` to provide a strictly typed, developer-friendly interface for generating HTML from Preact components.
+
+### Rendering Strategy
+
+The module distinguishes between rendering a **Component Definition** (passing the function/class and its props separately) and a **Virtual Node** (an already instantiated `<Component />`). This allows for cleaner code when you have the component and data separate (e.g., in controller logic).
+
+### Preact Integration
+
+Under the hood, this library relies on Preact. This ensures the rendering process is fast and lightweight, making it ideal for high-throughput server environments.
+
+## 🚀 Basic Usage
+
+The most common use case is rendering a functional component to a string.
+
+### Rendering a Functional Component
+
+You can pass the component function and its properties directly to `renderJsx`.
+
+```ts
+import { renderJsx } from '@tstdl/base/jsx';
+
+type HelloProps = {
+  name: string;
+};
+
+function Hello({ name }: HelloProps) {
+  return <div>Hello, {name}!</div>;
+}
+
+// Pass component and props separately
+const html = renderJsx(Hello, { name: 'World' });
+
+console.log(html);
+// Output: <div>Hello, World!</div>
+```
+
+### Rendering a Class Component
+
+Class components are also supported.
+
+```ts
+import { Component } from 'preact';
+import { renderJsx } from '@tstdl/base/jsx';
+
+type Props = { title: string };
+
+class MyComponent extends Component<Props> {
+  render() {
+    return <h1>{this.props.title}</h1>;
+  }
+}
+
+const html = renderJsx(MyComponent, { title: 'Hello from Class' });
+```
+
+### Rendering a VNode
+
+If you already have a JSX element (VNode), you can pass it directly.
+
+```ts
+import { renderJsx } from '@tstdl/base/jsx';
+
+const element = (
+  <section>
+    <h1>Static Content</h1>
+    <p>This is a VNode.</p>
+  </section>
+);
+
+const html = renderJsx(element);
+console.log(html);
+```
+
+## 🔧 Advanced Topics
+
+### Asynchronous Rendering
+
+If your component tree involves asynchronous operations (like `Suspense`), use `renderJsxAsync`. This returns a `Promise` that resolves to the HTML string once the tree has fully settled.
+
+```ts
+import { renderJsxAsync } from '@tstdl/base/jsx';
+
+async function generateReport() {
+  // Assume ReportComponent uses Suspense or async logic
+  const html = await renderJsxAsync(ReportComponent, { data: [1, 2, 3] });
+  return html;
+}
+```
+
+### Checking Component Types
+
+When building higher-order components or framework utilities, you might need to distinguish between a Class Component and a Functional Component. The `isComponentClass` type guard handles this check, which can be tricky due to how classes are transpiled.
+
+```ts
+import { Component } from 'preact';
+import { isComponentClass } from '@tstdl/base/jsx';
+
+class MyClassComponent extends Component {
+  render() {
+    return <div>Class</div>;
+  }
+}
+
+function MyFuncComponent() {
+  return <div>Function</div>;
+}
+
+console.log(isComponentClass(MyClassComponent)); // true
+console.log(isComponentClass(MyFuncComponent));  // false
+```
+
+### Configuration
+
+To use JSX/TSX in your project with this module, ensure your `tsconfig.json` is configured to use Preact as the JSX factory.
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact"
+  }
+}
+```
+
+## 📚 API
+
+| Export             | Type     | Description                                                                                                                   |
+| :----------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------- |
+| `renderJsx`        | Function | Synchronously renders a component or VNode to an HTML string. Overloads support passing props separately or a VNode directly. |
+| `renderJsxAsync`   | Function | Asynchronously renders a component or VNode to an HTML string (Promise). Useful for Suspense-enabled trees.                   |
+| `isComponentClass` | Function | Type guard that returns `true` if the provided template is a Preact Component Class.                                          |

package/key-value-store/README.md

@@ -0,0 +1,191 @@
+# Key-Value Store
+
+A flexible, type-safe, and backend-agnostic module for persistent key-value storage, scoped by module names to prevent collisions.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Getting a Store Instance](#getting-a-store-instance)
+  - [Type Safety](#type-safety)
+  - [Basic Operations](#basic-operations)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Atomic Get or Set](#atomic-get-or-set)
+  - [Batch Operations](#batch-operations)
+  - [Transaction Support (Postgres)](#transaction-support-postgres)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type-Safe**: Full TypeScript support for defining the shape of your stored data.
+- **Module Scoping**: Automatically namespaces keys (e.g., `user-settings`, `cache`) to prevent conflicts.
+- **Backend Agnostic**: Abstract API allows swapping storage engines without changing application code.
+- **PostgreSQL Support**: Includes a robust, transaction-safe implementation using Drizzle ORM.
+- **Dependency Injection**: Seamlessly integrates with the `@tstdl/base/injector`.
+
+## Core Concepts
+
+### KeyValueStore
+
+The `KeyValueStore<KV>` is the primary abstract class. It defines the contract for all storage operations (`get`, `set`, `delete`, etc.). It is generic, allowing you to define an interface `KV` representing the valid keys and value types for a specific store.
+
+### Module Scoping
+
+Every store instance is initialized with a `module` string. This acts as a namespace in the underlying database. For example, a key named `theme` in the `user-settings` module is distinct from a key named `theme` in the `admin-panel` module.
+
+### Persistence
+
+This module provides a PostgreSQL implementation (`PostgresKeyValueStore`) that persists data to a `key_value` table. It handles serialization (JSON) and deserialization automatically.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+To use the PostgreSQL backend, you must configure it during your application's bootstrap phase. This registers the implementation in the dependency injection container.
+
+```ts
+import { Application } from '@tstdl/base/application';
+import { configurePostgresKeyValueStore, migratePostgresKeyValueStoreSchema } from '@tstdl/base/key-value-store/postgres';
+
+async function bootstrap() {
+  // Register the Postgres implementation with default settings
+  configurePostgresKeyValueStore();
+
+  // Or provide a custom database configuration
+  configurePostgresKeyValueStore({
+    database: {
+      connection: 'postgresql://user:password@localhost:5432/db'
+    }
+  });
+}
+
+async function main() {
+  // Ensure the database schema is up to date (creates the 'key_value_store' schema and 'key_value' table)
+  await migratePostgresKeyValueStoreSchema();
+}
+
+Application.run({ bootstrap }, main);
+```
+
+### Getting a Store Instance
+
+You can inject the store into your services. The `KeyValueStore` requires an argument (the module name) when being resolved.
+
+```ts
+import { inject, Singleton } from '@tstdl/base/injector';
+import { KeyValueStore } from '@tstdl/base/key-value-store';
+
+@Singleton()
+export class MyService {
+  // Inject a store scoped to 'my-feature'
+  readonly store = inject(KeyValueStore, 'my-feature');
+}
+```
+
+### Type Safety
+
+Define an interface for your data to ensure type safety across your application.
+
+```ts
+import { inject, Singleton } from '@tstdl/base/injector';
+import { KeyValueStore } from '@tstdl/base/key-value-store';
+
+type UserSettings = {
+  theme: 'dark' | 'light';
+  notificationsEnabled: boolean;
+  loginCount: number;
+};
+
+@Singleton()
+export class UserSettingsService {
+  // The store is now typed. 'theme' must be 'dark' | 'light', etc.
+  readonly settings = inject<KeyValueStore<UserSettings>>(KeyValueStore, 'user-settings');
+
+  async updateTheme(theme: 'dark' | 'light'): Promise<void> {
+    await this.settings.set('theme', theme);
+  }
+}
+```
+
+### Basic Operations
+
+```ts
+// Set a value
+await store.set('theme', 'dark');
+
+// Get a value (returns undefined if not found)
+const theme = await store.get('theme');
+
+// Get with a default value
+const notifications = await store.get('notificationsEnabled', true);
+
+// Delete a key
+await store.delete('theme');
+
+// Clear all keys in this module
+await store.clear();
+```
+
+## 🔧 Advanced Topics
+
+### Atomic Get or Set
+
+The `getOrSet` method is useful for caching or initializing values. It retrieves the value if it exists; otherwise, it sets the provided value and returns it. In the PostgreSQL implementation, this operation is atomic and transaction-safe.
+
+```ts
+// If 'loginCount' exists, return it.
+// If not, set it to 0 and return 0.
+const count = await store.getOrSet('loginCount', 0);
+```
+
+### Batch Operations
+
+You can set or delete multiple keys efficiently in a single operation.
+
+```ts
+// Set multiple values
+await store.setMany({
+  theme: 'light',
+  notificationsEnabled: false,
+  loginCount: 1,
+});
+
+// Delete multiple keys
+await store.deleteMany(['theme', 'notificationsEnabled']);
+```
+
+### Transaction Support (Postgres)
+
+The `PostgresKeyValueStore` implementation is transaction-safe. It extends `Transactional`, which means it automatically participates in existing transactions managed by the ORM.
+
+```ts
+await database.transaction(async (tx) => {
+  // These operations will run within the same database transaction
+  await store.withTransaction(tx).set('theme', 'dark');
+  await otherRepository.withTransaction(tx).save(entity);
+});
+```
+
+## 📚 API
+
+### `KeyValueStore<KV>`
+
+| Method       | Signature                                                 | Description                                                      |
+| :----------- | :-------------------------------------------------------- | :--------------------------------------------------------------- |
+| `get`        | `get<K>(key: K): Promise<KV[K] \| undefined>`             | Gets the value of a key.                                         |
+| `get`        | `get<K, D>(key: K, defaultValue: D): Promise<KV[K] \| D>` | Gets the value of a key, returning `defaultValue` if missing.    |
+| `set`        | `set<K>(key: K, value: KV[K]): Promise<void>`             | Sets the value of a key.                                         |
+| `getOrSet`   | `getOrSet<K>(key: K, value: KV[K]): Promise<KV[K]>`       | Gets a value, or sets and returns the provided value if missing. |
+| `setMany`    | `setMany(keyValues: Partial<KV>): Promise<void>`          | Sets multiple key-value pairs at once.                           |
+| `delete`     | `delete(key: keyof KV): Promise<boolean>`                 | Deletes a key. Returns `true` if deleted.                        |
+| `deleteMany` | `deleteMany(keys: (keyof KV)[]): Promise<void>`           | Deletes multiple keys.                                           |
+| `clear`      | `clear(): Promise<void>`                                  | Removes all keys associated with the current module.             |
+
+### Postgres Configuration
+
+| Function                                  | Description                                                         |
+| :---------------------------------------- | :------------------------------------------------------------------ |
+| `configurePostgresKeyValueStore(config?)` | Registers the PostgreSQL backend. Accepts optional database config. |
+| `migratePostgresKeyValueStoreSchema()`    | Runs Drizzle migrations to create/update the `key_value` table.     |