@relax.js/core 1.0.0

package/dist/lib/DataLoader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Interface for loading paginated data from a data source.
+ * Implement this interface to provide data to table or list components
+ * that support pagination and sorting.
+ *
+ * Used by components like `r-table` to fetch data on demand as users
+ * navigate through pages or change sort order.
+ *
+ * @example
+ * // Implement for an API-backed data source
+ * class UserDataLoader implements DataLoader {
+ *     async load(options) {
+ *         const params = new URLSearchParams({
+ *             page: options.page.toString(),
+ *             pageSize: options.pageSize.toString(),
+ *             sort: JSON.stringify(options.sort)
+ *         });
+ *
+ *         const response = await fetch(`/api/users?${params}`);
+ *         return response.json();
+ *     }
+ * }
+ *
+ * @example
+ * // Use with a table component
+ * const loader: DataLoader = new UserDataLoader();
+ * const result = await loader.load({ page: 1, pageSize: 25, sort: [] });
+ * table.render(result.rows);
+ */
+export interface DataLoader {
+    /**
+     * Loads a page of data with optional sorting.
+     *
+     * @param options - The loading options
+     * @param options.page - The 1-based page number to load
+     * @param options.pageSize - Number of rows per page
+     * @param options.sort - Array of sort specifications
+     * @returns Promise resolving to rows and total count for pagination
+     */
+    load(options: {
+        page: number;
+        pageSize: number;
+        sort: {
+            column: string;
+            direction: 'asc' | 'desc';
+        }[];
+    }): Promise<{
+        rows: Record<string, any>[];
+        totalCount: number;
+    }>;
+}

package/dist/lib/DependencyInjection.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Generic constructor type used for dependency registration and injection.
+ * Represents any class constructor that can be used with the DI container.
+ *
+ * @template T - The type of object the constructor creates
+ *
+ * @example
+ * // Use with service registration
+ * class UserService {}
+ * const ctor: Constructor<UserService> = UserService;
+ * serviceCollection.registerByType(ctor, { inject: [] });
+ */
+export type Constructor<T extends object = object> = new (...args: any[]) => T;
+/**
+ * Controls how service instances are shared across the container hierarchy.
+ * Used when registering services to define their lifetime behavior.
+ *
+ * - `global`: Single instance shared everywhere (singleton pattern)
+ * - `closest`: New instance per container scope (scoped lifetime)
+ *
+ * @example
+ * // Singleton service - same instance everywhere
+ * serviceCollection.register(LoggerService, { scope: 'global', inject: [] });
+ *
+ * // Scoped service - new instance per scope
+ * serviceCollection.register(RequestContext, { scope: 'closest', inject: [] });
+ */
+export type ServiceScope = 'global' | 'closest';
+/**
+ * Configuration options for registering a service in the DI container.
+ * Controls identification, lifetime, and dependency resolution.
+ *
+ * @example
+ * // Register with constructor injection
+ * const options: RegistrationOptions = {
+ *     scope: 'global',
+ *     inject: [DatabaseConnection, ConfigService]
+ * };
+ * serviceCollection.register(UserRepository, options);
+ *
+ * @example
+ * // Register with property injection
+ * const options: RegistrationOptions = {
+ *     inject: [],
+ *     properties: { logger: Logger, config: 'appConfig' }
+ * };
+ *
+ * @example
+ * // Register with a pre-created instance
+ * const options: RegistrationOptions = {
+ *     inject: [],
+ *     instance: existingService
+ * };
+ */
+export interface RegistrationOptions {
+    /** Service lifetime - 'global' for singleton, 'closest' for scoped */
+    scope?: ServiceScope;
+    /** Optional string key for resolving by name instead of type */
+    key?: string;
+    /** Pre-existing instance to use instead of creating new one */
+    instance?: unknown;
+    /** Types or keys for constructor parameters, in order */
+    inject: (string | Constructor)[];
+    /** Map of property names to their injection types/keys */
+    properties?: Record<string, string | Constructor>;
+}
+/**
+ * Field decorator that collects property injection configuration.
+ * Updates or creates the properties mapping in registration options.
+ *
+ * @example
+ * @ContainerService({
+ *   inject: [Database],
+ *   properties: {
+ *     logger: Logger,        // Inject by type
+ *     audit: 'auditLogger'   // Inject by key
+ *   }
+ * })
+ * class UserService {
+ *   @Inject(Logger)
+ *   private logger!: Logger;
+ *
+ *   @Inject('auditLogger')
+ *   private audit!: Logger;
+ *
+ *   constructor(db: Database) {}
+ * }
+ */
+export declare function Inject<T extends object>(typeOrKey: Constructor<T> | string): (_: undefined, context: ClassFieldDecoratorContext) => (this: any) => T;
+/**
+ * Class decorator that automatically registers a service in the global DI container.
+ * Use this to declaratively register services without manual registration calls.
+ *
+ * Services are registered at module load time, so ensure this file is imported
+ * before attempting to resolve the decorated service.
+ *
+ * @param options - Registration configuration including scope and dependencies
+ *
+ * @example
+ * // Simple service with constructor injection
+ * @ContainerService({ inject: [DatabaseConnection] })
+ * class UserRepository {
+ *     constructor(private db: DatabaseConnection) {}
+ * }
+ *
+ * @example
+ * // Service with custom key for named resolution
+ * @ContainerService({ key: 'primaryCache', scope: 'global', inject: [] })
+ * class CacheService {}
+ *
+ * // Later resolve by key
+ * const cache = container.resolve('primaryCache');
+ */
+export declare function ContainerService<T extends object>(options?: RegistrationOptions): (target: Constructor<T>) => void;
+/**
+ * Internal class representing a registered service's metadata.
+ * Holds all information needed to create and configure service instances.
+ *
+ * @internal This is an implementation detail and should not be used directly.
+ */
+declare class Registration {
+    classConstructor: Constructor;
+    scope: ServiceScope;
+    inject: (string | Constructor)[];
+    properties: Record<string, string | Constructor>;
+    key?: string;
+    instance?: unknown;
+    /**
+     * Creates a new registration record.
+     *
+     * @param classConstructor - The class constructor function
+     * @param scope - Instance sharing behavior
+     * @param inject - Constructor parameter dependencies
+     * @param properties - Property injection mappings
+     * @param key - Optional string identifier
+     * @param instance - Optional pre-created instance
+     */
+    constructor(classConstructor: Constructor, scope: ServiceScope, inject: (string | Constructor)[], properties?: Record<string, string | Constructor>, key?: string, instance?: unknown);
+}
+/**
+ * Registry that stores service registration metadata.
+ * Use this to register services before they can be resolved by a ServiceContainer.
+ *
+ * Typically you'll use the global `serviceCollection` instance rather than creating your own.
+ *
+ * @example
+ * // Register a service by type
+ * serviceCollection.registerByType(LoggerService, { inject: [] });
+ *
+ * // Register with a string key
+ * serviceCollection.register(CacheService, { key: 'cache', inject: [] });
+ *
+ * // Check if service is registered
+ * const reg = serviceCollection.tryGet(LoggerService);
+ * if (reg) {
+ *     console.log('Logger is registered');
+ * }
+ */
+export declare class ServiceCollection {
+    private servicesByKey;
+    private servicesByClassName;
+    /**
+     * Registers a service with full configuration options.
+     * The service will be resolvable by both its class name and optional key.
+     *
+     * @param constructor - The service class constructor
+     * @param options - Registration configuration
+     */
+    register<T extends object>(constructor: Constructor<T>, options: RegistrationOptions): void;
+    /**
+     * Registers a service by its class type.
+     * The service will be resolvable by its class constructor.
+     *
+     * @param constructor - The service class constructor
+     * @param options - Optional registration configuration
+     */
+    registerByType<T extends object>(constructor: Constructor<T>, options?: RegistrationOptions): void;
+    private checkNameCollision;
+    private validateRegistration;
+    /**
+     * Attempts to retrieve a service registration.
+     * Returns undefined if the service is not registered.
+     *
+     * @param key - Either a string key or class constructor
+     * @returns The registration or undefined
+     */
+    tryGet<T extends object>(key: string | Constructor<T>): Registration | undefined;
+    /**
+     * Retrieves a service registration or throws if not found.
+     *
+     * @param key - Either a string key or class constructor
+     * @returns The registration
+     * @throws Error if the service is not registered
+     */
+    get<T extends object>(key: string | Constructor<T>): Registration;
+}
+/**
+ * IoC container that resolves and manages service instances.
+ * Creates instances based on registrations in a ServiceCollection,
+ * handling constructor injection, property injection, and lifetime management.
+ *
+ * Typically you'll use the global `container` instance rather than creating your own.
+ *
+ * @example
+ * // Resolve a service by class
+ * const logger = container.resolve(LoggerService);
+ *
+ * // Resolve by string key
+ * const cache = container.resolve<CacheService>('primaryCache');
+ *
+ * @example
+ * // Full setup workflow
+ * serviceCollection.register(UserService, {
+ *     inject: [DatabaseConnection],
+ *     scope: 'global'
+ * });
+ *
+ * const userService = container.resolve(UserService);
+ */
+export declare class ServiceContainer {
+    private serviceCollection;
+    private instances;
+    /**
+     * Creates a new container backed by the given service collection.
+     *
+     * @param serviceCollection - The registry containing service registrations
+     */
+    constructor(serviceCollection: ServiceCollection);
+    /**
+     * Resolves a service instance by class type or string key.
+     * Creates the instance if not already cached (for global scope).
+     * Handles constructor and property injection automatically.
+     *
+     * @param keyOrType - Either a string key or class constructor
+     * @returns The resolved service instance
+     * @throws Error if the service is not registered
+     *
+     * @example
+     * const service = container.resolve(MyService);
+     */
+    resolve<T extends object>(keyOrType: string | Constructor<T>): T;
+    /**
+     * Creates a new instance of a service, resolving all constructor dependencies.
+     */
+    private createInstance;
+    /**
+     * Injects dependencies into instance properties based on registration config.
+     */
+    private injectFields;
+}
+/**
+ * Global service collection instance for registering services.
+ * Use this to register services that can later be resolved by the container.
+ *
+ * @example
+ * import { serviceCollection } from 'relaxjs';
+ *
+ * serviceCollection.register(MyService, { inject: [Dependency] });
+ */
+export declare const serviceCollection: ServiceCollection;
+/**
+ * Global service container instance for resolving dependencies.
+ * Use this to obtain service instances with all dependencies injected.
+ *
+ * @example
+ * import { container } from 'relaxjs';
+ *
+ * const service = container.resolve(MyService);
+ */
+export declare const container: ServiceContainer;
+export {};

package/dist/lib/InvokeParent.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Finds the closest parent of a specific type by traversing up the DOM tree.
+ *
+ * @param node - The starting node to search from.
+ * @param constructor - The constructor of the desired element type (e.g., MyParentComponent).
+ * @returns The matching element or null if not found.
+ */
+export declare function getParentComponent<T extends HTMLElement>(node: Node, constructor: {
+    new (...args: any[]): T;
+}): T | null;

package/dist/lib/Pipes.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @module pipes
+ * Data transformation functions (pipes) for use in template expressions.
+ * Pipes transform values for display, like formatting dates, currencies, or text.
+ *
+ * Locale-aware pipes (currency, date, daysAgo, pieces) use the i18n system
+ * for formatting and translations. Call `setLocale()` before using these pipes.
+ *
+ * Pipes can be chained in templates: `{{value | uppercase | shorten:20}}`
+ *
+ * @example
+ * // In templates
+ * <span>{{user.name | uppercase}}</span>
+ * <span>{{price | currency}}</span>
+ * <span>{{createdAt | daysAgo}}</span>
+ *
+ * @example
+ * // Programmatic usage
+ * import { applyPipes, defaultPipes } from 'relaxjs';
+ * const result = applyPipes('hello world', ['uppercase', 'shorten:8']);
+ * // Returns: 'HELLO...'
+ */
+/**
+ * Type definition for pipe transformation functions.
+ * Pipes take a value and optional arguments, returning a transformed value.
+ *
+ * @example
+ * // Define a custom pipe
+ * const reversePipe: PipeFunction = (value: string) => {
+ *     return value.split('').reverse().join('');
+ * };
+ */
+export type PipeFunction = (value: any, ...args: any[]) => any;
+/**
+ * Converts a string to uppercase
+ * @param value The string to convert
+ * @returns The uppercase string
+ */
+export declare function uppercasePipe(value: string): string;
+/**
+ * Converts a string to uppercase
+ * @param value The string to convert
+ * @returns The uppercase string
+ */
+export declare function trimPipe(value: string): string;
+/**
+ * Converts a string to lowercase
+ * @param value The string to convert
+ * @returns The lowercase string
+ */
+export declare function lowercasePipe(value: string): string;
+/**
+ * Capitalizes the first character of a string
+ * @param value The string to capitalize
+ * @returns The capitalized string
+ */
+export declare function capitalizePipe(value: string): string;
+/**
+ * Shortens a string to a specified length and adds ellipsis.
+ * @param value The string to shorten
+ * @param length Maximum length including ellipsis
+ * @returns The shortened string with ellipsis if needed
+ */
+export declare function shortenPipe(value: string, length: string): string;
+/**
+ * Formats a number as currency using the current locale.
+ * Uses the i18n system's current locale for formatting.
+ *
+ * @param value The number to format
+ * @param currency Currency code (defaults to USD)
+ * @returns Formatted currency string
+ *
+ * @example
+ * // In template: {{price | currency}} or {{price | currency:EUR}}
+ * currencyPipe(1234.56);        // "$1,234.56" (en) or "1 234,56 $" (sv)
+ * currencyPipe(1234.56, 'SEK'); // "SEK 1,234.56" (en) or "1 234,56 kr" (sv)
+ */
+export declare function currencyPipe(value: number, currency?: string): string;
+/**
+ * Formats a date value according to the specified format.
+ * Uses the i18n system's current locale for formatting.
+ *
+ * @param value Date value (string, number, or Date object)
+ * @param format Format type: 'short', 'long', or default (ISO)
+ * @returns Formatted date string
+ *
+ * @example
+ * // In template: {{date | date:short}} or {{date | date:long}}
+ * datePipe(new Date(), 'short'); // "1/15/2024" (en) or "2024-01-15" (sv)
+ * datePipe(new Date(), 'long');  // "Monday, January 15, 2024" (en) or "måndag 15 januari 2024" (sv)
+ */
+export declare function datePipe(value: string | number | Date, format?: string): string;
+/**
+ * Prints today, yesterday or X days ago.
+ * Uses the i18n system for translations (requires pipes namespace loaded).
+ *
+ * @param value Date value (string, number, or Date object)
+ * @returns Formatted relative date string
+ *
+ * @example
+ * // In template: {{createdAt | daysAgo}}
+ * // English: "today", "yesterday", "3 days ago"
+ * // Swedish: "idag", "igår", "3 dagar sedan"
+ */
+export declare function daysAgoPipe(value: string | number | Date): string;
+/**
+ * Formats a count as pieces/items.
+ * Uses the i18n system for translations (requires pipes namespace loaded).
+ *
+ * @param value Count value
+ * @returns Formatted piece count string
+ *
+ * @example
+ * // In template: {{quantity | pieces}}
+ * // English: "none", "one", "3 pcs"
+ * // Swedish: "inga", "en", "3 st"
+ */
+export declare function piecesPipe(value: string | number): string;
+/**
+ * Joins array elements with the specified separator
+ * @param value Array to join
+ * @param separator Character(s) to use between elements (defaults to comma)
+ * @returns Joined string or original value if not an array
+ */
+export declare function joinPipe(value: any[], separator?: string): string | any;
+/**
+ * Returns the first element of an array
+ * @param value Array to extract from
+ * @returns First element or empty string if array is empty/invalid
+ */
+export declare function firstPipe(value: any[]): any;
+/**
+ * Returns the last element of an array
+ * @param value Array to extract from
+ * @returns Last element or empty string if array is empty/invalid
+ */
+export declare function lastPipe(value: any[]): any;
+/**
+ * Returns the keys of an object
+ * @param value Object to extract keys from
+ * @returns Array of object keys or empty array if not an object
+ */
+export declare function keysPipe(value: object): string[];
+/**
+ * Returns a default value if the input is falsy
+ * @param value Input value to check
+ * @param defaultValue Value to return if input is falsy
+ * @returns Original value or default value
+ */
+export declare function defaultPipe(value: any, defaultValue: string): any;
+/**
+ * Implements ternary operator as a pipe
+ * @param value Condition to evaluate
+ * @param trueValue Value to return if condition is truthy
+ * @param falseValue Value to return if condition is falsy
+ * @returns Selected value based on condition
+ */
+export declare function ternaryPipe(value: any, trueValue: string, falseValue: string): string;
+/**
+ * Interface for a collection of pipe functions.
+ * Use this to look up pipes by name for template processing.
+ *
+ * @example
+ * // Check if a pipe exists before using
+ * if (registry.has('currency')) {
+ *     const formatted = registry.get('currency')(price);
+ * }
+ */
+export interface PipeRegistry {
+    /**
+     * Looks up a pipe by name, returning null if not found.
+     */
+    lookup(name: string): PipeFunction | null;
+    /**
+     * Gets a pipe by name, throwing if not found.
+     */
+    get(name: string): PipeFunction;
+    /**
+     * Checks if a pipe with the given name exists.
+     */
+    has(name: string): boolean;
+}
+/**
+ * Creates a new pipe registry with all built-in pipes registered.
+ * Built-in pipes include:
+ *
+ * **Text:** uppercase, lowercase, capitalize, trim, shorten
+ * **Formatting:** currency, date, daysAgo, pieces
+ * **Arrays:** join, first, last
+ * **Objects:** keys
+ * **Conditionals:** default, ternary
+ *
+ * @returns A new pipe registry instance
+ *
+ * @example
+ * const registry = createPipeRegistry();
+ * const upperPipe = registry.get('uppercase');
+ * console.log(upperPipe('hello')); // 'HELLO'
+ */
+export declare function createPipeRegistry(): PipeRegistry;
+/**
+ * Default pipe registry instance with all built-in pipes.
+ * Used by template engines unless a custom registry is provided.
+ *
+ * @example
+ * import { defaultPipes } from 'relaxjs';
+ *
+ * if (defaultPipes.has('uppercase')) {
+ *     const result = defaultPipes.get('uppercase')('hello');
+ * }
+ */
+export declare const defaultPipes: PipeRegistry;
+/**
+ * Applies a series of pipes to a value sequentially.
+ * Each pipe transforms the output of the previous pipe.
+ *
+ * Pipe arguments are specified after a colon: `shorten:20`
+ *
+ * @param value - Initial value to transform
+ * @param pipes - Array of pipe strings (name and optional arguments separated by ':')
+ * @param registry - Optional custom pipe registry (uses defaultPipes if not provided)
+ * @returns The transformed value after applying all pipes
+ *
+ * @example
+ * // Apply single pipe
+ * applyPipes('hello', ['uppercase']); // 'HELLO'
+ *
+ * @example
+ * // Chain multiple pipes
+ * applyPipes('hello world', ['uppercase', 'shorten:8']); // 'HELLO...'
+ *
+ * @example
+ * // With pipe arguments
+ * applyPipes(1234.56, ['currency']); // '$1,234.56'
+ */
+export declare function applyPipes(value: any, pipes: string[], registry?: PipeRegistry): any;

package/dist/lib/SequentialId.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module SequentialId
+ * Generates compact, time-ordered unique identifiers suitable for distributed systems.
+ *
+ * IDs are structured to be:
+ * - Unique across multiple clients (via baseId)
+ * - Time-sortable (timestamp is the most significant bits)
+ * - Compact (Base36 encoding produces short strings)
+ *
+ * Bit allocation (58 bits total):
+ * - 30 bits for timestamp (seconds since January 1, 2025)
+ * - 8 bits for per-second counter (supports 256 IDs/second)
+ * - 20 bits for client/endpoint identifier (supports ~1M unique sources)
+ */
+/**
+ * Generates a unique, time-ordered sequential ID.
+ *
+ * The ID combines a timestamp, per-second counter, and client identifier
+ * into a compact Base36 string. IDs generated later will sort after earlier IDs,
+ * making them suitable for ordered collections.
+ *
+ * @param baseId - Unique identifier for the client/endpoint (0 to 1,048,575).
+ *                 Use different baseIds for different servers or processes to
+ *                 avoid collisions.
+ * @returns Base36 encoded string representing the unique ID
+ * @throws Error if baseId is out of valid range
+ * @throws Error if more than 256 IDs are generated in a single second
+ * @throws Error if timestamp exceeds range (after year 2045)
+ *
+ * @example
+ * // Generate ID for server instance 1
+ * const id1 = generateSequentialId(1);
+ * // Returns something like: 'k2j8m3n5p'
+ *
+ * @example
+ * // Different servers use different baseIds
+ * const SERVER_ID = parseInt(process.env.SERVER_ID || '0');
+ * const orderId = generateSequentialId(SERVER_ID);
+ *
+ * @example
+ * // IDs are time-sortable
+ * const id1 = generateSequentialId(0);
+ * await delay(1000);
+ * const id2 = generateSequentialId(0);
+ * console.log(id1 < id2); // true (lexicographic comparison works)
+ */
+export declare function generateSequentialId(baseId: number): string;

package/dist/lib/collections/Index.d.ts

@@ -0,0 +1 @@
+export { LinkedList, Node } from "./LinkedList";

package/dist/lib/collections/LinkedList.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A node in the @see LinkedList.
+ */
+export declare class Node<T> {
+    value: T;
+    private removeCallback;
+    /**
+     * Next node unless last one.
+     */
+    next: Node<T> | null;
+    /**
+     * Previous node unless first one.
+     */
+    prev: Node<T> | null;
+    /**
+     * Constructor.
+     * @param value Value contained in the node.
+     */
+    constructor(value: T, removeCallback: () => void);
+    /**
+     * Remove this node.
+     * Will notify the list of the update to ensure correct element count.
+     */
+    remove(): void;
+}
+/**
+ * A trivial linked list implementation.
+ */
+export declare class LinkedList<T> {
+    private _first?;
+    private _last?;
+    private _length;
+    /**
+     * Add a value to the beginning of the list.
+     * @param value Value that should be contained in the node.
+     */
+    addFirst(value: T): void;
+    /**
+     * Add a value to the end of the list.
+     * @param value Value that should be contained in a node.
+     */
+    addLast(value: T): void;
+    /**
+     * Remove a node from the beginning of the list.
+     * @returns Value contained in the first node.
+     */
+    removeFirst(): T;
+    /**
+     * Remove a node from the end of the list.
+     * @returns Value contained in the last node.
+     */
+    removeLast(): T;
+    /**
+     * Number of nodes in the list.
+     *
+     * The count works as long as you do not manually remove nodes (by assigning next/prev to the neighbors).
+     */
+    get length(): number;
+    /**
+     * First ndoe.
+     */
+    get first(): Node<T> | undefined;
+    /**
+     * Contained value of the first node.
+     */
+    get firstValue(): T | undefined;
+    /**
+     * Last node.
+     */
+    get last(): Node<T> | undefined;
+    /**
+     * Contained value of the last node.
+     */
+    get lastValue(): T | undefined;
+}