/**
 * @db4/core - Utility Functions
 *
 * Common utilities used across all @db4 packages.
 *
 * @packageDocumentation
 */
import type { Document, StoredDocument, DocumentMeta, BatchMetadata, DocumentBatch, QueryFilter, QueryOptions, SortSpec, FieldDefinition, PrimitiveType, FieldModifier, FilterOperator, SortDirection, DocumentId, BatchId, ShardId } from './types.js';
/**
 * Generates a unique ID using timestamp and cryptographically secure random components.
 * Format: t{timestamp_base32_10}-{random_base32_16}
 *
 * Properties:
 * - Uses crypto.getRandomValues() for cryptographic randomness
 * - URL-safe (uses Crockford's Base32: 0-9, a-z excluding i, l, o, u)
 * - Time-sortable (timestamp prefix ensures chronological ordering)
 * - Consistent length (28 characters: 1 prefix + 10 timestamp + 1 separator + 16 random)
 * - Starts with 't' (never starts with a number for compatibility)
 */
export declare function generateId(): string;
/**
 * Generates a UUID v4 using crypto.randomUUID().
 */
export declare function generateUUID(): string;
/**
 * Generates a DocumentId with a doc_ prefix.
 * Returns a branded DocumentId type for type safety.
 */
export declare function generateDocumentId(): DocumentId;
/**
 * Generates a batch ID with collection prefix.
 * Returns a branded BatchId type for type safety.
 *
 * @param collection - Optional collection name prefix. Defaults to 'batch'.
 */
export declare function generateBatchId(collection?: string): BatchId;
/**
 * Generates a shard ID with optional shard number.
 * Returns a branded ShardId type for type safety.
 *
 * @param shardNumber - Optional shard number to include in the ID.
 */
export declare function generateShardId(shardNumber?: number): ShardId;
/**
 * Calculates JSON size in bytes.
 */
export declare function jsonSize(obj: unknown): number;
/**
 * Estimates the size of a value in bytes.
 * More accurate for primitive values than full JSON serialization.
 */
export declare function estimateSize(value: unknown): number;
/**
 * Calculates the size of a document.
 */
export declare function documentSize(doc: Document): number;
/**
 * Type guard to check if a value is a valid Document.
 * A valid document must have an 'id' property of type string.
 */
export declare function isDocument(value: unknown): value is Document;
/**
 * Type guard to check if a value is a valid DocumentMeta.
 */
export declare function isDocumentMeta(value: unknown): value is DocumentMeta;
/**
 * Type guard to check if a value is a valid StoredDocument.
 */
export declare function isStoredDocument(value: unknown): value is StoredDocument;
/**
 * Type guard to check if a value is a valid BatchMetadata.
 */
export declare function isBatchMetadata(value: unknown): value is BatchMetadata;
/**
 * Type guard to check if a value is a valid DocumentBatch.
 */
export declare function isDocumentBatch(value: unknown): value is DocumentBatch;
/**
 * Type guard to check if a value is a valid PrimitiveType.
 */
export declare function isPrimitiveType(value: unknown): value is PrimitiveType;
/**
 * Type guard to check if a value is a valid FieldModifier.
 */
export declare function isFieldModifier(value: unknown): value is FieldModifier;
/**
 * Type guard to check if a value is a valid FieldDefinition.
 */
export declare function isFieldDefinition(value: unknown): value is FieldDefinition;
/**
 * Type guard to check if a value is a valid FilterOperator.
 */
export declare function isFilterOperator(value: unknown): value is FilterOperator;
/**
 * Type guard to check if a value is a valid QueryFilter.
 */
export declare function isQueryFilter(value: unknown): value is QueryFilter;
/**
 * Type guard to check if a value is a valid SortDirection.
 */
export declare function isSortDirection(value: unknown): value is SortDirection;
/**
 * Type guard to check if a value is a valid SortSpec.
 */
export declare function isSortSpec(value: unknown): value is SortSpec;
/**
 * Type guard to check if a value is a valid QueryOptions.
 */
export declare function isQueryOptions(value: unknown): value is QueryOptions;
import { ValidationError } from './errors.js';
/**
 * Validation result type.
 */
export type ValidationResult = {
    valid: true;
    value: unknown;
} | {
    valid: false;
    error: ValidationError;
};
/**
 * Validates that a value is a non-empty string.
 */
export declare function validateNonEmptyString(value: unknown, fieldName: string): ValidationResult;
/**
 * Validates that a value is a positive number.
 */
export declare function validatePositiveNumber(value: unknown, fieldName: string): ValidationResult;
/**
 * Validates that a value is a non-negative integer.
 */
export declare function validateNonNegativeInteger(value: unknown, fieldName: string): ValidationResult;
/**
 * Validates that a value is a valid timestamp (positive integer in ms).
 */
export declare function validateTimestamp(value: unknown, fieldName: string): ValidationResult;
/**
 * Validates a Document and returns detailed errors.
 */
export declare function validateDocument(value: unknown): ValidationResult;
/**
 * Validates a DocumentMeta and returns detailed errors.
 */
export declare function validateDocumentMeta(value: unknown): ValidationResult;
/**
 * Validates a StoredDocument and returns detailed errors.
 */
export declare function validateStoredDocument(value: unknown): ValidationResult;
/**
 * Validates QueryOptions and returns detailed errors.
 */
export declare function validateQueryOptions(value: unknown): ValidationResult;
/**
 * Deep clones an object using JSON serialization.
 */
export declare function deepClone<T>(obj: T): T;
/**
 * Safely clones an object, handling circular references.
 */
export declare function safeClone<T>(obj: T, seen?: WeakSet<object>): T;
/**
 * Deep merges two objects.
 * Arrays are replaced, not merged.
 */
export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
/**
 * Gets a nested value from an object using dot notation.
 */
export declare function getNestedValue(obj: unknown, path: string): unknown;
/**
 * Sets a nested value in an object using dot notation.
 */
export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
/**
 * Picks specific keys from an object.
 */
export declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
/**
 * Omits specific keys from an object.
 */
export declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
/**
 * Gets the current timestamp in milliseconds.
 */
export declare function now(): number;
/**
 * Creates a delay promise.
 */
export declare function delay(ms: number): Promise<void>;
/**
 * Formats a timestamp as ISO 8601 string.
 */
export declare function formatTimestamp(timestamp: number): string;
/**
 * Truncates a string to a maximum length.
 */
export declare function truncate(str: string, maxLength: number, suffix?: string): string;
/**
 * Converts a string to a slug format.
 */
export declare function slugify(str: string): string;
/**
 * Chunks an array into smaller arrays of a specified size.
 */
export declare function chunk<T>(array: T[], size: number): T[][];
/**
 * Removes duplicates from an array.
 */
export declare function unique<T>(array: T[]): T[];
/**
 * Groups array elements by a key function.
 */
export declare function groupBy<T, K extends string | number | symbol>(array: T[], keyFn: (item: T) => K): Record<K, T[]>;
//# sourceMappingURL=utils.d.ts.map