tersejson 0.2.0 → 0.3.0

package/dist/server-memory.d.mts

@@ -0,0 +1,167 @@
+import { C as CompressOptions, T as TersePayload } from './types-BTonKlz8.mjs';
+
+/**
+ * TerseJSON Server-Side Memory Optimization
+ *
+ * Utilities for memory-efficient data handling on the server:
+ * - TerseCache: Store compressed data, return Proxy-wrapped on access
+ * - compressStream: Compress data as it streams from database cursors
+ * - createTerseServiceClient: Inter-service communication with compressed payloads
+ */
+
+/**
+ * Options for TerseCache
+ */
+interface TerseCacheOptions {
+    /** Compression options passed to compress() */
+    compressOptions?: CompressOptions;
+    /** Maximum number of entries (simple LRU when exceeded) */
+    maxSize?: number;
+    /** Default TTL in milliseconds (optional) */
+    defaultTTL?: number;
+}
+/**
+ * A memory-efficient cache that stores data in compressed form.
+ *
+ * Data is compressed on set() and stays compressed in memory.
+ * On get(), data is returned wrapped in a Proxy for lazy expansion.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TerseCache<User[]>();
+ *
+ * // Store compressed - uses less memory
+ * cache.set('users', largeUserArray);
+ *
+ * // Get returns Proxy-wrapped data
+ * const users = cache.get('users');
+ * users?.map(u => u.name); // Only 'name' field expands
+ * ```
+ */
+declare class TerseCache<T extends Record<string, unknown>[] = Record<string, unknown>[]> {
+    private cache;
+    private options;
+    private accessOrder;
+    constructor(options?: TerseCacheOptions);
+    /**
+     * Store data in compressed form
+     */
+    set(key: string, data: T, ttl?: number): void;
+    /**
+     * Get data wrapped in Proxy for lazy expansion.
+     * Only accessed fields are expanded from compressed form.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Get the raw compressed payload without expansion.
+     * Useful for forwarding to other services.
+     */
+    getRaw(key: string): TersePayload<T> | undefined;
+    /**
+     * Check if key exists (and is not expired)
+     */
+    has(key: string): boolean;
+    /**
+     * Delete an entry
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+}
+/**
+ * Options for streaming compression
+ */
+interface CompressStreamOptions extends CompressOptions {
+    /** Number of items per batch (default: 100) */
+    batchSize?: number;
+}
+/**
+ * Compress data as it streams from an async source (e.g., database cursor).
+ *
+ * Yields compressed batches without loading entire result set into memory.
+ *
+ * @example
+ * ```typescript
+ * // MongoDB cursor
+ * const cursor = db.collection('users').find().stream();
+ * for await (const batch of compressStream(cursor, { batchSize: 100 })) {
+ *   // Send batch to client or process
+ *   res.write(JSON.stringify(batch));
+ * }
+ *
+ * // PostgreSQL stream
+ * const stream = client.query(new QueryStream('SELECT * FROM users'));
+ * for await (const batch of compressStream(stream)) {
+ *   // Process compressed batches
+ * }
+ * ```
+ */
+declare function compressStream<T extends Record<string, unknown>>(source: AsyncIterable<T>, options?: CompressStreamOptions): AsyncGenerator<TersePayload<T[]>, void, unknown>;
+/**
+ * Configuration for TerseServiceClient
+ */
+interface TerseServiceClientConfig {
+    /** Base URL for the service */
+    baseUrl: string;
+    /** Whether to expand responses with Proxy (default: true) */
+    expandOnReceive?: boolean;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (for testing or Node.js < 18) */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * HTTP client for inter-service communication with TerseJSON.
+ *
+ * Services can pass compressed data without intermediate expansion,
+ * reducing memory usage across the request chain.
+ *
+ * @example
+ * ```typescript
+ * const serviceB = createTerseServiceClient({
+ *   baseUrl: 'http://service-b:3000',
+ * });
+ *
+ * // GET - returns Proxy-wrapped data
+ * const users = await serviceB.get<User[]>('/api/users');
+ * users.map(u => u.name); // Only accessed fields expand
+ *
+ * // Forward compressed payload to another service
+ * const raw = cache.getRaw('users');
+ * if (raw) {
+ *   await serviceB.forward('/api/users/sync', raw);
+ * }
+ * ```
+ */
+declare function createTerseServiceClient(config: TerseServiceClientConfig): {
+    /**
+     * GET request - receives TerseJSON and returns Proxy-wrapped (or raw)
+     */
+    get<T>(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /**
+     * POST request with automatic compression
+     */
+    post<T, R = unknown>(path: string, data: T, options?: {
+        headers?: Record<string, string>;
+        compress?: boolean;
+    }): Promise<R>;
+    /**
+     * Forward a raw TersePayload to another endpoint without expansion.
+     * Useful for passing data between services without intermediate deserialization.
+     */
+    forward<T extends Record<string, unknown>[]>(path: string, payload: TersePayload<T>, options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+};
+
+export { CompressOptions, type CompressStreamOptions, TerseCache, type TerseCacheOptions, TersePayload, type TerseServiceClientConfig, compressStream, createTerseServiceClient };

package/dist/server-memory.d.ts

@@ -0,0 +1,167 @@
+import { C as CompressOptions, T as TersePayload } from './types-BTonKlz8.js';
+
+/**
+ * TerseJSON Server-Side Memory Optimization
+ *
+ * Utilities for memory-efficient data handling on the server:
+ * - TerseCache: Store compressed data, return Proxy-wrapped on access
+ * - compressStream: Compress data as it streams from database cursors
+ * - createTerseServiceClient: Inter-service communication with compressed payloads
+ */
+
+/**
+ * Options for TerseCache
+ */
+interface TerseCacheOptions {
+    /** Compression options passed to compress() */
+    compressOptions?: CompressOptions;
+    /** Maximum number of entries (simple LRU when exceeded) */
+    maxSize?: number;
+    /** Default TTL in milliseconds (optional) */
+    defaultTTL?: number;
+}
+/**
+ * A memory-efficient cache that stores data in compressed form.
+ *
+ * Data is compressed on set() and stays compressed in memory.
+ * On get(), data is returned wrapped in a Proxy for lazy expansion.
+ *
+ * @example
+ * ```typescript
+ * const cache = new TerseCache<User[]>();
+ *
+ * // Store compressed - uses less memory
+ * cache.set('users', largeUserArray);
+ *
+ * // Get returns Proxy-wrapped data
+ * const users = cache.get('users');
+ * users?.map(u => u.name); // Only 'name' field expands
+ * ```
+ */
+declare class TerseCache<T extends Record<string, unknown>[] = Record<string, unknown>[]> {
+    private cache;
+    private options;
+    private accessOrder;
+    constructor(options?: TerseCacheOptions);
+    /**
+     * Store data in compressed form
+     */
+    set(key: string, data: T, ttl?: number): void;
+    /**
+     * Get data wrapped in Proxy for lazy expansion.
+     * Only accessed fields are expanded from compressed form.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Get the raw compressed payload without expansion.
+     * Useful for forwarding to other services.
+     */
+    getRaw(key: string): TersePayload<T> | undefined;
+    /**
+     * Check if key exists (and is not expired)
+     */
+    has(key: string): boolean;
+    /**
+     * Delete an entry
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+}
+/**
+ * Options for streaming compression
+ */
+interface CompressStreamOptions extends CompressOptions {
+    /** Number of items per batch (default: 100) */
+    batchSize?: number;
+}
+/**
+ * Compress data as it streams from an async source (e.g., database cursor).
+ *
+ * Yields compressed batches without loading entire result set into memory.
+ *
+ * @example
+ * ```typescript
+ * // MongoDB cursor
+ * const cursor = db.collection('users').find().stream();
+ * for await (const batch of compressStream(cursor, { batchSize: 100 })) {
+ *   // Send batch to client or process
+ *   res.write(JSON.stringify(batch));
+ * }
+ *
+ * // PostgreSQL stream
+ * const stream = client.query(new QueryStream('SELECT * FROM users'));
+ * for await (const batch of compressStream(stream)) {
+ *   // Process compressed batches
+ * }
+ * ```
+ */
+declare function compressStream<T extends Record<string, unknown>>(source: AsyncIterable<T>, options?: CompressStreamOptions): AsyncGenerator<TersePayload<T[]>, void, unknown>;
+/**
+ * Configuration for TerseServiceClient
+ */
+interface TerseServiceClientConfig {
+    /** Base URL for the service */
+    baseUrl: string;
+    /** Whether to expand responses with Proxy (default: true) */
+    expandOnReceive?: boolean;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (for testing or Node.js < 18) */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * HTTP client for inter-service communication with TerseJSON.
+ *
+ * Services can pass compressed data without intermediate expansion,
+ * reducing memory usage across the request chain.
+ *
+ * @example
+ * ```typescript
+ * const serviceB = createTerseServiceClient({
+ *   baseUrl: 'http://service-b:3000',
+ * });
+ *
+ * // GET - returns Proxy-wrapped data
+ * const users = await serviceB.get<User[]>('/api/users');
+ * users.map(u => u.name); // Only accessed fields expand
+ *
+ * // Forward compressed payload to another service
+ * const raw = cache.getRaw('users');
+ * if (raw) {
+ *   await serviceB.forward('/api/users/sync', raw);
+ * }
+ * ```
+ */
+declare function createTerseServiceClient(config: TerseServiceClientConfig): {
+    /**
+     * GET request - receives TerseJSON and returns Proxy-wrapped (or raw)
+     */
+    get<T>(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /**
+     * POST request with automatic compression
+     */
+    post<T, R = unknown>(path: string, data: T, options?: {
+        headers?: Record<string, string>;
+        compress?: boolean;
+    }): Promise<R>;
+    /**
+     * Forward a raw TersePayload to another endpoint without expansion.
+     * Useful for passing data between services without intermediate deserialization.
+     */
+    forward<T extends Record<string, unknown>[]>(path: string, payload: TersePayload<T>, options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+};
+
+export { CompressOptions, type CompressStreamOptions, TerseCache, type TerseCacheOptions, TersePayload, type TerseServiceClientConfig, compressStream, createTerseServiceClient };