metal-orm 1.0.43 → 1.0.44

package/src/core/functions/standard-strategy.ts

@@ -1,9 +1,15 @@
 import { FunctionStrategy, FunctionRenderer, FunctionRenderContext } from './types.js';
 import { LiteralNode, OperandNode, isOperandNode } from '../ast/expression.js';
 
+/**
+ * Standard implementation of FunctionStrategy for ANSI SQL functions.
+ */
 export class StandardFunctionStrategy implements FunctionStrategy {
     protected renderers: Map<string, FunctionRenderer> = new Map();
 
+    /**
+     * Creates a new StandardFunctionStrategy and registers standard functions.
+     */
     constructor() {
         this.registerStandard();
     }
@@ -44,14 +50,27 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         this.add('GROUP_CONCAT', ctx => this.renderGroupConcat(ctx));
     }
 
+    /**
+     * Registers a renderer for a function name.
+     * @param name - The function name.
+     * @param renderer - The renderer function.
+     */
     protected add(name: string, renderer: FunctionRenderer) {
         this.renderers.set(name, renderer);
     }
 
+    /**
+     * @inheritDoc
+     */
     getRenderer(name: string): FunctionRenderer | undefined {
         return this.renderers.get(name);
     }
 
+    /**
+     * Renders the GROUP_CONCAT function with optional ORDER BY and SEPARATOR.
+     * @param ctx - The function render context.
+     * @returns The rendered SQL string.
+     */
     private renderGroupConcat(ctx: FunctionRenderContext): string {
         const arg = ctx.compiledArgs[0];
         const orderClause = this.buildOrderByExpression(ctx);
@@ -60,6 +79,11 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         return `GROUP_CONCAT(${arg}${orderSegment}${separatorClause})`;
     }
 
+    /**
+     * Builds the ORDER BY clause for functions like GROUP_CONCAT.
+     * @param ctx - The function render context.
+     * @returns The ORDER BY SQL clause or empty string.
+     */
     protected buildOrderByExpression(ctx: FunctionRenderContext): string {
         const orderBy = ctx.node.orderBy;
         if (!orderBy || orderBy.length === 0) {
@@ -78,6 +102,11 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         return `ORDER BY ${parts.join(', ')}`;
     }
 
+    /**
+     * Formats the SEPARATOR clause for GROUP_CONCAT.
+     * @param ctx - The function render context.
+     * @returns The SEPARATOR SQL clause or empty string.
+     */
     protected formatGroupConcatSeparator(ctx: FunctionRenderContext): string {
         if (!ctx.node.separator) {
             return '';
@@ -85,10 +114,16 @@ export class StandardFunctionStrategy implements FunctionStrategy {
         return ` SEPARATOR ${ctx.compileOperand(ctx.node.separator)}`;
     }
 
+    /**
+     * Gets the separator operand for GROUP_CONCAT, defaulting to comma.
+     * @param ctx - The function render context.
+     * @returns The separator operand.
+     */
     protected getGroupConcatSeparatorOperand(ctx: FunctionRenderContext): OperandNode {
         return ctx.node.separator ?? StandardFunctionStrategy.DEFAULT_GROUP_CONCAT_SEPARATOR;
     }
 
+    /** Default separator for GROUP_CONCAT, a comma. */
     protected static readonly DEFAULT_GROUP_CONCAT_SEPARATOR: LiteralNode = {
         type: 'Literal',
         value: ','

package/src/core/functions/text.ts

@@ -23,22 +23,30 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
 });
 
 /**
- * Helper: LOWER(str)
+ * Converts a string to lowercase.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LOWER SQL function.
  */
 export const lower = (value: OperandInput): FunctionNode => fn('LOWER', [value]);
 
 /**
- * Helper: UPPER(str)
+ * Converts a string to uppercase.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the UPPER SQL function.
  */
 export const upper = (value: OperandInput): FunctionNode => fn('UPPER', [value]);
 
 /**
- * Helper: ASCII(str)
+ * Returns the ASCII code of the first character of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the ASCII SQL function.
  */
 export const ascii = (value: OperandInput): FunctionNode => fn('ASCII', [value]);
 
 /**
- * Helper: CHAR(code[, code...])
+ * Returns a string from one or more ASCII codes.
+ * @param codes - The ASCII codes.
+ * @returns A FunctionNode representing the CHAR SQL function.
  */
 export const char = (...codes: OperandInput[]): FunctionNode => {
   if (codes.length === 0) throw new Error('char() expects at least 1 argument');
@@ -46,33 +54,46 @@ export const char = (...codes: OperandInput[]): FunctionNode => {
 };
 
 /**
- * Helper: CHAR_LENGTH(str)
+ * Returns the number of characters in a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
  */
 export const charLength = (value: OperandInput): FunctionNode => fn('CHAR_LENGTH', [value]);
 
 /**
- * Helper: LENGTH(str)
+ * Returns the length of a string in bytes or characters.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LENGTH SQL function.
  */
 export const length = (value: OperandInput): FunctionNode => fn('LENGTH', [value]);
 
 /**
- * Helper: TRIM([chars FROM] str)
+ * Removes leading and trailing whitespace or specified characters from a string.
+ * @param value - The string value.
+ * @param chars - The characters to trim (optional).
+ * @returns A FunctionNode representing the TRIM SQL function.
  */
 export const trim = (value: OperandInput, chars?: OperandInput): FunctionNode =>
   chars === undefined ? fn('TRIM', [value]) : fn('TRIM', [value, chars]);
 
 /**
- * Helper: LTRIM(str)
+ * Removes leading whitespace from a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LTRIM SQL function.
  */
 export const ltrim = (value: OperandInput): FunctionNode => fn('LTRIM', [value]);
 
 /**
- * Helper: RTRIM(str)
+ * Removes trailing whitespace from a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the RTRIM SQL function.
  */
 export const rtrim = (value: OperandInput): FunctionNode => fn('RTRIM', [value]);
 
 /**
- * Helper: CONCAT(arg1, arg2, ...)
+ * Concatenates two or more strings.
+ * @param args - The strings to concatenate.
+ * @returns A FunctionNode representing the CONCAT SQL function.
  */
 export const concat = (...args: OperandInput[]): FunctionNode => {
   if (args.length < 2) throw new Error('concat() expects at least 2 arguments');
@@ -80,7 +101,10 @@ export const concat = (...args: OperandInput[]): FunctionNode => {
 };
 
 /**
- * Helper: CONCAT_WS(separator, arg1, arg2, ...)
+ * Concatenates strings with a separator.
+ * @param separator - The separator string.
+ * @param args - The strings to concatenate.
+ * @returns A FunctionNode representing the CONCAT_WS SQL function.
  */
 export const concatWs = (separator: OperandInput, ...args: OperandInput[]): FunctionNode => {
   if (args.length < 1) throw new Error('concatWs() expects at least 2 arguments including the separator');
@@ -88,61 +112,98 @@ export const concatWs = (separator: OperandInput, ...args: OperandInput[]): Func
 };
 
 /**
- * Helper: SUBSTR(str, start[, length])
+ * Extracts a substring from a string.
+ * @param value - The string value.
+ * @param start - The starting position.
+ * @param length - The length of the substring (optional).
+ * @returns A FunctionNode representing the SUBSTR SQL function.
  */
 export const substr = (value: OperandInput, start: OperandInput, length?: OperandInput): FunctionNode =>
   length === undefined ? fn('SUBSTR', [value, start]) : fn('SUBSTR', [value, start, length]);
 
 /**
- * Helper: LEFT(str, length)
+ * Returns the leftmost characters of a string.
+ * @param value - The string value.
+ * @param len - The number of characters to return.
+ * @returns A FunctionNode representing the LEFT SQL function.
  */
 export const left = (value: OperandInput, len: OperandInput): FunctionNode => fn('LEFT', [value, len]);
 
 /**
- * Helper: RIGHT(str, length)
+ * Returns the rightmost characters of a string.
+ * @param value - The string value.
+ * @param len - The number of characters to return.
+ * @returns A FunctionNode representing the RIGHT SQL function.
  */
 export const right = (value: OperandInput, len: OperandInput): FunctionNode => fn('RIGHT', [value, len]);
 
 /**
- * Helper: POSITION(substring IN string)
+ * Returns the position of a substring in a string.
+ * @param substring - The substring to search for.
+ * @param value - The string to search in.
+ * @returns A FunctionNode representing the POSITION SQL function.
  */
 export const position = (substring: OperandInput, value: OperandInput): FunctionNode => fn('POSITION', [substring, value]);
 
 /**
- * Helper: INSTR(string, substring)
+ * Returns the position of a substring in a string.
+ * @param value - The string to search in.
+ * @param substring - The substring to search for.
+ * @returns A FunctionNode representing the INSTR SQL function.
  */
 export const instr = (value: OperandInput, substring: OperandInput): FunctionNode => fn('INSTR', [value, substring]);
 
 /**
- * Helper: LOCATE(substring, string[, start])
+ * Returns the position of a substring in a string, optionally starting from a position.
+ * @param substring - The substring to search for.
+ * @param value - The string to search in.
+ * @param start - The starting position (optional).
+ * @returns A FunctionNode representing the LOCATE SQL function.
  */
 export const locate = (substring: OperandInput, value: OperandInput, start?: OperandInput): FunctionNode =>
   start === undefined ? fn('LOCATE', [substring, value]) : fn('LOCATE', [substring, value, start]);
 
 /**
- * Helper: REPLACE(string, search, replace)
+ * Replaces occurrences of a substring in a string.
+ * @param value - The string to search in.
+ * @param search - The substring to replace.
+ * @param replacement - The replacement string.
+ * @returns A FunctionNode representing the REPLACE SQL function.
  */
 export const replace = (value: OperandInput, search: OperandInput, replacement: OperandInput): FunctionNode =>
   fn('REPLACE', [value, search, replacement]);
 
 /**
- * Helper: REPEAT(string, count)
+ * Repeats a string a specified number of times.
+ * @param value - The string to repeat.
+ * @param count - The number of times to repeat.
+ * @returns A FunctionNode representing the REPEAT SQL function.
  */
 export const repeat = (value: OperandInput, count: OperandInput): FunctionNode => fn('REPEAT', [value, count]);
 
 /**
- * Helper: LPAD(string, length, padstr)
+ * Left-pads a string to a certain length with another string.
+ * @param value - The string to pad.
+ * @param len - The length to pad to.
+ * @param pad - The padding string.
+ * @returns A FunctionNode representing the LPAD SQL function.
  */
 export const lpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
   fn('LPAD', [value, len, pad]);
 
 /**
- * Helper: RPAD(string, length, padstr)
+ * Right-pads a string to a certain length with another string.
+ * @param value - The string to pad.
+ * @param len - The length to pad to.
+ * @param pad - The padding string.
+ * @returns A FunctionNode representing the RPAD SQL function.
  */
 export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
   fn('RPAD', [value, len, pad]);
 
 /**
- * Helper: SPACE(count)
+ * Returns a string consisting of a specified number of spaces.
+ * @param count - The number of spaces.
+ * @returns A FunctionNode representing the SPACE SQL function.
  */
 export const space = (count: OperandInput): FunctionNode => fn('SPACE', [count]);

package/src/core/functions/types.ts

@@ -1,18 +1,33 @@
-import { FunctionNode, OperandNode } from '../ast/expression.js';
-
-export interface FunctionRenderContext {
-    node: FunctionNode;
-    compiledArgs: string[];
-    /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
-    compileOperand: (operand: OperandNode) => string;
-}
+import { FunctionNode, OperandNode } from '../ast/expression.js';
 
+/**
+ * Context provided to function renderers.
+ */
+export interface FunctionRenderContext {
+    /** The function node being rendered. */
+    node: FunctionNode;
+    /** The compiled arguments for the function. */
+    compiledArgs: string[];
+    /** Helper to compile additional operands (e.g., separators or ORDER BY columns). */
+    compileOperand: (operand: OperandNode) => string;
+}
+
+/**
+ * A function that renders a SQL function call.
+ * @param ctx - The rendering context.
+ * @returns The rendered SQL string.
+ */
 export type FunctionRenderer = (ctx: FunctionRenderContext) => string;
 
+/**
+ * Strategy for rendering SQL functions in a specific dialect.
+ */
 export interface FunctionStrategy {
     /**
      * Returns a renderer for a specific function name (e.g. "DATE_ADD").
      * Returns undefined if this dialect doesn't support the function.
+     * @param functionName - The name of the function.
+     * @returns The renderer function or undefined.
      */
     getRenderer(functionName: string): FunctionRenderer | undefined;
 }

package/src/decorators/bootstrap.ts

@@ -8,6 +8,7 @@ import {
   type RelationDef
 } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
+import { isTableDef } from '../schema/table-guards.js';
 import {
   buildTableDef,
   EntityConstructor,
@@ -20,10 +21,6 @@ import {
 
 import { tableRef, type TableRef } from '../schema/table.js';
 
-const isTableDef = (value: unknown): value is TableDef => {
-  return typeof value === 'object' && value !== null && 'columns' in (value as TableDef);
-};
-
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   if (typeof target === 'function' && (target as Function).prototype === undefined) {
@@ -104,6 +101,10 @@ const buildRelationDefinitions = (
   return relations;
 };
 
+/**
+ * Bootstraps all entities by building their table definitions and relations.
+ * @returns An array of table definitions for all bootstrapped entities.
+ */
 export const bootstrapEntities = (): TableDef[] => {
   const metas = getAllEntityMetadata();
   const tableMap = new Map<EntityConstructor, TableDef>();
@@ -122,6 +123,12 @@ export const bootstrapEntities = (): TableDef[] => {
   return metas.map(meta => meta.table!) as TableDef[];
 };
 
+/**
+ * Gets the table definition for a given entity constructor.
+ * Bootstraps entities if necessary.
+ * @param ctor - The entity constructor.
+ * @returns The table definition or undefined if not found.
+ */
 export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor): TTable | undefined => {
   const meta = getEntityMetadata(ctor);
   if (!meta) return undefined;
@@ -131,6 +138,11 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
   return meta.table as TTable;
 };
 
+/**
+ * Creates a select query builder for the given entity.
+ * @param ctor - The entity constructor.
+ * @returns A select query builder for the entity.
+ */
 export const selectFromEntity = <TTable extends TableDef = TableDef>(
   ctor: EntityConstructor
 ): SelectQueryBuilder<unknown, TTable> => {

package/src/decorators/column.ts

@@ -12,6 +12,9 @@ import {
   StandardDecoratorContext
 } from './decorator-metadata.js';
 
+/**
+ * Options for defining a column in an entity.
+ */
 export interface ColumnOptions {
   type: ColumnType;
   args?: ColumnDef['args'];
@@ -20,6 +23,9 @@ export interface ColumnOptions {
   tsType?: ColumnDef['tsType'];
 }
 
+/**
+ * Input type for column definitions, either as options object or direct ColumnDef.
+ */
 export type ColumnInput = ColumnOptions | ColumnDef;
 
 const normalizeColumnInput = (input: ColumnInput): ColumnDefLike => {
@@ -89,6 +95,11 @@ const registerColumnFromContext = (
 
 };
 
+/**
+ * Decorator to define a column on an entity property.
+ * @param definition - The column definition or options.
+ * @returns A property decorator that registers the column metadata.
+ */
 export function Column(definition: ColumnInput) {
   const normalized = normalizeColumnInput(definition);
   const decorator: DualModePropertyDecorator = (targetOrValue, propertyKeyOrContext) => {
@@ -108,6 +119,12 @@ export function Column(definition: ColumnInput) {
   return decorator;
 }
 
+/**
+ * Decorator to define a primary key column on an entity property.
+ * Sets the primary flag to true and delegates to Column decorator.
+ * @param definition - The column definition or options.
+ * @returns A property decorator that registers the primary key column metadata.
+ */
 export function PrimaryKey(definition: ColumnInput) {
   const normalized = normalizeColumnInput(definition);
   normalized.primary = true;

package/src/decorators/decorator-metadata.ts

@@ -1,5 +1,8 @@
 import { ColumnDefLike, RelationMetadata } from '../orm/entity-metadata.js';
 
+/**
+ * Context object provided by standard decorators in newer TypeScript versions.
+ */
 export interface StandardDecoratorContext {
   kind: string;
   name?: string | symbol;
@@ -8,11 +11,17 @@ export interface StandardDecoratorContext {
   private?: boolean;
 }
 
+/**
+ * Dual-mode property decorator that supports both legacy and standard decorator syntax.
+ */
 export interface DualModePropertyDecorator {
   (target: object, propertyKey: string | symbol): void;
   (value: unknown, context: StandardDecoratorContext): void;
 }
 
+/**
+ * Dual-mode class decorator that supports both legacy and standard decorator syntax.
+ */
 export interface DualModeClassDecorator {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   <TFunction extends Function>(value: TFunction): void | TFunction;
@@ -20,6 +29,9 @@ export interface DualModeClassDecorator {
   <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
 }
 
+/**
+ * Bag for storing decorator metadata during the decoration phase.
+ */
 export interface DecoratorMetadataBag {
   columns: Array<{ propertyName: string; column: ColumnDefLike }>;
   relations: Array<{ propertyName: string; relation: RelationMetadata }>;
@@ -27,10 +39,20 @@ export interface DecoratorMetadataBag {
 
 const METADATA_KEY = 'metal-orm:decorators';
 
+/**
+ * Checks if a value is a StandardDecoratorContext.
+ * @param value - The value to check.
+ * @returns True if the value is a StandardDecoratorContext.
+ */
 export const isStandardDecoratorContext = (value: unknown): value is StandardDecoratorContext => {
   return typeof value === 'object' && value !== null && 'kind' in (value as object);
 };
 
+/**
+ * Gets or creates a metadata bag for the given decorator context.
+ * @param context - The decorator context.
+ * @returns The metadata bag.
+ */
 export const getOrCreateMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag => {
   const metadata = context.metadata || (context.metadata = {} as Record<PropertyKey, unknown>);
   const existing = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
@@ -42,6 +64,11 @@ export const getOrCreateMetadataBag = (context: StandardDecoratorContext): Decor
   return bag;
 };
 
+/**
+ * Reads the metadata bag from the given decorator context.
+ * @param context - The decorator context.
+ * @returns The metadata bag if present.
+ */
 export const readMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag | undefined => {
   return context.metadata?.[METADATA_KEY] as DecoratorMetadataBag | undefined;
 };

package/src/decorators/entity.ts

@@ -9,6 +9,9 @@ import {
 } from '../orm/entity-metadata.js';
 import { DualModeClassDecorator, isStandardDecoratorContext, readMetadataBag } from './decorator-metadata.js';
 
+/**
+ * Options for defining an entity.
+ */
 export interface EntityOptions {
   tableName?: string;
   hooks?: TableHooks;
@@ -34,6 +37,11 @@ const deriveTableNameFromConstructor = (ctor: EntityConstructor<unknown>): strin
   return normalized.endsWith('s') ? normalized : `${normalized}s`;
 };
 
+/**
+ * Class decorator to mark a class as an entity and configure its table mapping.
+ * @param options - Configuration options for the entity.
+ * @returns A class decorator that registers the entity metadata.
+ */
 export function Entity(options: EntityOptions = {}) {
   const decorator: DualModeClassDecorator = value => {
     const tableName = options.tableName ?? deriveTableNameFromConstructor(value);

package/src/decorators/index.ts

@@ -1,3 +1,6 @@
+/**
+ * Decorators for defining entities, columns, and relations in Metal ORM.
+ */
 export * from './entity.js';
 export * from './column.js';
 export * from './relations.js';

package/src/decorators/relations.ts

@@ -18,18 +18,30 @@ interface BaseRelationOptions {
   localKey?: string;
 }
 
+/**
+ * Options for HasMany relation.
+ */
 export interface HasManyOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for HasOne relation.
+ */
 export interface HasOneOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for BelongsTo relation.
+ */
 export interface BelongsToOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for BelongsToMany relation.
+ */
 export interface BelongsToManyOptions {
   target: EntityOrTableTargetResolver;
   pivotTable: EntityOrTableTargetResolver;
@@ -93,6 +105,11 @@ const createFieldDecorator = (
   return decorator;
 };
 
+/**
+ * Decorator to define a HasMany relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function HasMany(options: HasManyOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.HasMany,
@@ -104,6 +121,11 @@ export function HasMany(options: HasManyOptions) {
   }));
 }
 
+/**
+ * Decorator to define a HasOne relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function HasOne(options: HasOneOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.HasOne,
@@ -115,6 +137,11 @@ export function HasOne(options: HasOneOptions) {
   }));
 }
 
+/**
+ * Decorator to define a BelongsTo relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function BelongsTo(options: BelongsToOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsTo,
@@ -126,6 +153,11 @@ export function BelongsTo(options: BelongsToOptions) {
   }));
 }
 
+/**
+ * Decorator to define a BelongsToMany relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function BelongsToMany(options: BelongsToManyOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsToMany,

package/src/orm/als.ts

@@ -1,18 +1,31 @@
 // In a real Node environment: import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
- * Browser-compatible implementation of AsyncLocalStorage
- * Provides a simple in-memory store for browser environments
- * @typeParam T - Type of the stored data
+ * Browser-compatible implementation of AsyncLocalStorage.
+ * Provides a simple in-memory store for browser environments while maintaining
+ * Node.js AsyncLocalStorage API compatibility.
+ * 
+ * @template T Type of the data stored in the async context
  */
 export class AsyncLocalStorage<T> {
   private store: T | undefined;
 
   /**
-   * Executes a callback with the specified store value
-   * @param store - Value to store during callback execution
-   * @param callback - Function to execute with the store value
-   * @returns Result of the callback function
+   * Executes a callback function within a context containing the specified store value.
+   * The store value is only available during the callback's execution and is automatically
+   * cleared afterward.
+   * 
+   * @param store - The context value to make available during callback execution
+   * @param callback - Function to execute with the store value available
+   * @returns Result of the callback function execution
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<number>();
+   * als.run(42, () => {
+   *   console.log(als.getStore()); // Outputs: 42
+   * });
+   * ```
    */
   run<R>(store: T, callback: () => R): R {
     this.store = store;
@@ -24,8 +37,20 @@ export class AsyncLocalStorage<T> {
   }
 
   /**
-   * Gets the currently stored value
-   * @returns Current store value or undefined if none exists
+   * Retrieves the current store value from the async context.
+   * Returns undefined if called outside of a `run()` callback execution.
+   * 
+   * @returns Current store value or undefined if no context exists
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<string>();
+   * console.log(als.getStore()); // Outputs: undefined
+   * 
+   * als.run('hello', () => {
+   *   console.log(als.getStore()); // Outputs: 'hello'
+   * });
+   * ```
    */
   getStore(): T | undefined {
     return this.store;