@stoneforge/quarry 0.1.0

package/dist/services/id-length-cache.js

@@ -0,0 +1,197 @@
+/**
+ * ID Length Cache Service
+ *
+ * Provides efficient caching for ID hash length calculation.
+ * This service avoids querying element count on every ID generation
+ * by caching the count and calculated length with periodic invalidation.
+ *
+ * The cache is automatically invalidated:
+ * - After a configurable TTL (default: 60 seconds)
+ * - When explicitly refreshed
+ * - After a significant number of creates (growth threshold)
+ */
+import { calculateIdLength, MIN_HASH_LENGTH, MAX_HASH_LENGTH } from '@stoneforge/core';
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_TTL_MS = 60000; // 60 seconds
+const DEFAULT_GROWTH_THRESHOLD = 100;
+const DEFAULT_MIN_LENGTH = MIN_HASH_LENGTH + 1; // 4 characters
+// ============================================================================
+// IdLengthCache Service
+// ============================================================================
+/**
+ * Service for caching ID hash length calculations.
+ *
+ * This service provides efficient access to the optimal ID hash length
+ * without querying the database on every ID generation.
+ *
+ * @example
+ * ```typescript
+ * const cache = createIdLengthCache(storage);
+ *
+ * // Get optimal hash length for ID generation
+ * const hashLength = cache.getHashLength();
+ *
+ * // Notify cache of new element creation (for growth tracking)
+ * cache.notifyCreate();
+ *
+ * // Force refresh if needed
+ * cache.refresh();
+ * ```
+ */
+export class IdLengthCache {
+    db;
+    cache = null;
+    hits = 0;
+    misses = 0;
+    ttlMs;
+    growthThreshold;
+    minLength;
+    constructor(db, config = {}) {
+        this.db = db;
+        this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+        this.growthThreshold = config.growthThreshold ?? DEFAULT_GROWTH_THRESHOLD;
+        this.minLength = Math.max(MIN_HASH_LENGTH, Math.min(MAX_HASH_LENGTH, config.minLength ?? DEFAULT_MIN_LENGTH));
+    }
+    /**
+     * Get the optimal hash length for ID generation.
+     *
+     * Returns the cached hash length if valid, otherwise refreshes
+     * the cache first. This is the main method to call when generating IDs.
+     *
+     * @returns The optimal hash length (3-8)
+     */
+    getHashLength() {
+        if (this.isStale()) {
+            this.refresh();
+            this.misses++;
+        }
+        else {
+            this.hits++;
+        }
+        return this.cache.hashLength;
+    }
+    /**
+     * Get the cached element count.
+     *
+     * This is the element count at the last refresh, not necessarily
+     * the current count in the database.
+     *
+     * @returns The cached element count
+     */
+    getElementCount() {
+        if (!this.cache) {
+            this.refresh();
+        }
+        return this.cache.elementCount;
+    }
+    /**
+     * Notify the cache that a new element was created.
+     *
+     * This increments the internal counter and may trigger a refresh
+     * if the growth threshold is exceeded.
+     */
+    notifyCreate() {
+        if (this.cache) {
+            this.cache.createsSinceRefresh++;
+            // Check if growth threshold exceeded
+            if (this.cache.createsSinceRefresh >= this.growthThreshold) {
+                // Check if we might need a longer hash
+                const newCount = this.cache.elementCount + this.cache.createsSinceRefresh;
+                const newLength = this.calculateLength(newCount);
+                if (newLength > this.cache.hashLength) {
+                    this.refresh();
+                }
+            }
+        }
+    }
+    /**
+     * Force a cache refresh.
+     *
+     * Queries the database for the current element count and
+     * recalculates the optimal hash length.
+     */
+    refresh() {
+        const elementCount = this.db.getElementCount();
+        const hashLength = this.calculateLength(elementCount);
+        this.cache = {
+            elementCount,
+            hashLength,
+            updatedAt: Date.now(),
+            createsSinceRefresh: 0,
+        };
+    }
+    /**
+     * Check if the cache is stale and needs refresh.
+     */
+    isStale() {
+        if (!this.cache) {
+            return true;
+        }
+        const age = Date.now() - this.cache.updatedAt;
+        return age >= this.ttlMs;
+    }
+    /**
+     * Clear the cache, forcing a refresh on next access.
+     */
+    clear() {
+        this.cache = null;
+    }
+    /**
+     * Get cache statistics for monitoring.
+     */
+    getStats() {
+        if (!this.cache) {
+            this.refresh();
+        }
+        const totalAccesses = this.hits + this.misses;
+        const hitRate = totalAccesses > 0 ? this.hits / totalAccesses : 0;
+        const ageMs = Date.now() - this.cache.updatedAt;
+        return {
+            elementCount: this.cache.elementCount,
+            hashLength: this.cache.hashLength,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+            ageMs,
+            isStale: this.isStale(),
+        };
+    }
+    /**
+     * Calculate the optimal hash length for an element count.
+     *
+     * Applies the minimum length constraint.
+     */
+    calculateLength(elementCount) {
+        const calculated = calculateIdLength(elementCount);
+        return Math.max(this.minLength, calculated);
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new IdLengthCache instance.
+ *
+ * @param db - Storage backend for querying element count
+ * @param config - Optional cache configuration
+ * @returns A new IdLengthCache instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const cache = createIdLengthCache(storage);
+ *
+ * // With custom configuration
+ * const cache = createIdLengthCache(storage, {
+ *   ttlMs: 30000, // 30 second TTL
+ *   growthThreshold: 50, // Refresh after 50 creates
+ *   minLength: 5, // Minimum 5-character hashes
+ * });
+ * ```
+ */
+export function createIdLengthCache(db, config) {
+    return new IdLengthCache(db, config);
+}
+//# sourceMappingURL=id-length-cache.js.map

package/dist/services/id-length-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-length-cache.js","sourceRoot":"","sources":["../../src/services/id-length-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAiEvF,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,aAAa;AAC3C,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,kBAAkB,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC,eAAe;AAE/D,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,aAAa;IASL;IARX,KAAK,GAAsB,IAAI,CAAC;IAChC,IAAI,GAAW,CAAC,CAAC;IACjB,MAAM,GAAW,CAAC,CAAC;IACV,KAAK,CAAS;IACd,eAAe,CAAS;IACxB,SAAS,CAAS;IAEnC,YACmB,EAAkB,EACnC,SAA8B,EAAE;QADf,OAAE,GAAF,EAAE,CAAgB;QAGnC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,cAAc,CAAC;QAC5C,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,wBAAwB,CAAC;QAC1E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CACvB,eAAe,EACf,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAClE,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,aAAa;QACX,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACnB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,KAAM,CAAC,UAAU,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,eAAe;QACb,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;QACD,OAAO,IAAI,CAAC,KAAM,CAAC,YAAY,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,YAAY;QACV,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC;YAEjC,qCAAqC;YACrC,IAAI,IAAI,CAAC,KAAK,CAAC,mBAAmB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBAC3D,uCAAuC;gBACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC;gBAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;gBACjD,IAAI,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;oBACtC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,MAAM,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QAEtD,IAAI,CAAC,KAAK,GAAG;YACX,YAAY;YACZ,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,mBAAmB,EAAE,CAAC;SACvB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAC9C,OAAO,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9C,MAAM,OAAO,GAAG,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAM,CAAC,SAAS,CAAC;QAEjD,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,KAAM,CAAC,YAAY;YACtC,UAAU,EAAE,IAAI,CAAC,KAAM,CAAC,UAAU;YAClC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO;YACP,KAAK;YACL,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;SACxB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,eAAe,CAAC,YAAoB;QAC1C,MAAM,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC9C,CAAC;CACF;AAED,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAAkB,EAClB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC"}

package/dist/services/inbox.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Inbox Service - Unified notification inbox management
+ *
+ * Provides CRUD operations for inbox items:
+ * - addToInbox: Add a new notification to an entity's inbox
+ * - getInbox: Get inbox items for an entity with optional filtering
+ * - getInboxPaginated: Get inbox items with pagination and total count
+ * - markAsRead: Mark an inbox item as read
+ * - markAsUnread: Mark an inbox item as unread
+ * - markAllAsRead: Mark all unread items as read for an entity
+ * - archive: Archive an inbox item
+ *
+ * The service does NOT integrate with MessageService - that is handled
+ * in a separate integration layer (Phase 4).
+ */
+import type { StorageBackend } from '@stoneforge/storage';
+import type { EntityId, ChannelId, InboxItem, InboxFilter, CreateInboxItemInput } from '@stoneforge/core';
+/**
+ * Service for managing inbox items
+ */
+export declare class InboxService {
+    private readonly db;
+    constructor(db: StorageBackend);
+    /**
+     * Initialize the inbox_items table schema
+     * Should be called during database setup
+     *
+     * Note: In production, use migrations instead of this method.
+     * This is provided for testing and standalone service usage.
+     */
+    initSchema(): void;
+    /**
+     * Add a new item to an entity's inbox
+     *
+     * @param input - Inbox item creation input
+     * @returns The created inbox item
+     * @throws ValidationError if input is invalid
+     * @throws ConflictError if inbox item already exists for this recipient/message
+     */
+    addToInbox(input: CreateInboxItemInput): InboxItem;
+    /**
+     * Get inbox items for a recipient with optional filtering
+     *
+     * @param recipientId - Entity to get inbox for
+     * @param filter - Optional filter criteria
+     * @returns Array of inbox items
+     */
+    getInbox(recipientId: EntityId, filter?: InboxFilter): InboxItem[];
+    /**
+     * Get inbox items with pagination info
+     *
+     * @param recipientId - Entity to get inbox for
+     * @param filter - Optional filter criteria (limit and offset used for pagination)
+     * @returns Object with items and total count
+     */
+    getInboxPaginated(recipientId: EntityId, filter?: InboxFilter): {
+        items: InboxItem[];
+        total: number;
+    };
+    /**
+     * Get the count of unread inbox items for a recipient
+     *
+     * @param recipientId - Entity to get unread count for
+     * @returns Number of unread items
+     */
+    getUnreadCount(recipientId: EntityId): number;
+    /**
+     * Get a single inbox item by ID
+     *
+     * @param id - Inbox item ID
+     * @returns The inbox item or null if not found
+     */
+    getInboxItem(id: string): InboxItem | null;
+    /**
+     * Mark an inbox item as read
+     *
+     * @param itemId - Inbox item ID to mark as read
+     * @returns The updated inbox item
+     * @throws NotFoundError if inbox item doesn't exist
+     */
+    markAsRead(itemId: string): InboxItem;
+    /**
+     * Mark multiple inbox items as read in a single operation.
+     *
+     * @param itemIds - Inbox item IDs to mark as read
+     * @returns Number of items actually marked as read
+     */
+    markAsReadBatch(itemIds: string[]): number;
+    /**
+     * Mark an inbox item as unread
+     *
+     * @param itemId - Inbox item ID to mark as unread
+     * @returns The updated inbox item
+     * @throws NotFoundError if inbox item doesn't exist
+     */
+    markAsUnread(itemId: string): InboxItem;
+    /**
+     * Mark all unread inbox items as read for a recipient
+     *
+     * @param recipientId - Entity to mark all items as read for
+     * @returns Number of items marked as read
+     */
+    markAllAsRead(recipientId: EntityId): number;
+    /**
+     * Archive an inbox item
+     *
+     * @param itemId - Inbox item ID to archive
+     * @returns The updated inbox item
+     * @throws NotFoundError if inbox item doesn't exist
+     */
+    archive(itemId: string): InboxItem;
+    /**
+     * Get inbox items for a specific channel
+     *
+     * @param recipientId - Entity to get inbox for
+     * @param channelId - Channel to filter by
+     * @returns Array of inbox items for the channel
+     */
+    getInboxByChannel(recipientId: EntityId, channelId: ChannelId): InboxItem[];
+    /**
+     * Delete inbox items by message ID (for cascade deletion)
+     *
+     * @param messageId - Message ID to delete inbox items for
+     * @returns Number of items deleted
+     */
+    deleteByMessage(messageId: string): number;
+    /**
+     * Delete all inbox items for a recipient
+     *
+     * @param recipientId - Entity to delete inbox items for
+     * @returns Number of items deleted
+     */
+    deleteByRecipient(recipientId: EntityId): number;
+    /**
+     * Build a SQL query from filter options
+     */
+    private buildFilterQuery;
+    /**
+     * Convert a database row to an InboxItem object
+     */
+    private rowToInboxItem;
+}
+/**
+ * Create a new InboxService instance
+ */
+export declare function createInboxService(db: StorageBackend): InboxService;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/services/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/services/inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAO,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAa,SAAS,EAAa,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAgDhI;;GAEG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,cAAc;IAM/C;;;;;;OAMG;IACH,UAAU,IAAI,IAAI;IAsClB;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS;IA6ElD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,EAAE;IAMlE;;;;;;OAMG;IACH,iBAAiB,CACf,WAAW,EAAE,QAAQ,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAiBxC;;;;;OAKG;IACH,cAAc,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM;IAS7C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAc1C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IA2BrC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM;IAe1C;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAyBvC;;;;;OAKG;IACH,aAAa,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM;IAa5C;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAuBlC;;;;;;OAMG;IACH,iBAAiB,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE;IAQ3E;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQ1C;;;;;OAKG;IACH,iBAAiB,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM;IAYhD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuFxB;;OAEG;IACH,OAAO,CAAC,cAAc;CAYvB;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,GAAG,YAAY,CAEnE"}