@tstdl/base 0.93.139 → 0.93.141

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.     |

package/key-value-store/postgres/module.d.ts

@@ -2,6 +2,7 @@ import { Injector } from '../../injector/index.js';
 import { type DatabaseConfig } from '../../orm/server/index.js';
 export declare class PostgresKeyValueStoreModuleConfig {
     database?: DatabaseConfig;
+    autoMigrate?: boolean;
 }
 /**
  * configure key-value store module

package/key-value-store/postgres/module.js

@@ -1,10 +1,11 @@
 import { inject, Injector } from '../../injector/index.js';
-import { Database, migrate } from '../../orm/server/index.js';
+import { Database, migrate, registerDatabaseMigration } from '../../orm/server/index.js';
 import { isDefined } from '../../utils/type-guards.js';
 import { KeyValueStore } from '../key-value.store.js';
 import { PostgresKeyValueStore } from './key-value-store.service.js';
 export class PostgresKeyValueStoreModuleConfig {
     database;
+    autoMigrate;
 }
 /**
  * configure key-value store module
@@ -15,6 +16,9 @@ export function configurePostgresKeyValueStore({ injector, ...config } = {}) {
         targetInjector.register(PostgresKeyValueStoreModuleConfig, { useValue: config });
     }
     targetInjector.registerSingleton(KeyValueStore, { useToken: PostgresKeyValueStore });
+    if (config.autoMigrate != false) {
+        registerDatabaseMigration('PostgresKeyValueStore', migratePostgresKeyValueStoreSchema, { injector });
+    }
 }
 export async function migratePostgresKeyValueStoreSchema() {
     const connection = inject(PostgresKeyValueStoreModuleConfig, undefined, { optional: true })?.database?.connection;