mcard-js/dist/model/CardCollection.d.ts

MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers

import { MCard } from './MCard';
import { StorageEngine, Page } from '../storage/StorageAdapter';
import { Maybe } from '../monads/Maybe';
/**
 * CardCollection - High-level interface for MCard operations with monadic API
 *
 * ## DOTS Vocabulary Role: CARRIER CATEGORY Car(S)
 *
 * CardCollection is the **Carrier Category** in the Double Operadic Theory of Systems.
 * - **Objects**: Individual MCards (data artifacts)
 * - **Morphisms**: Hash references between MCards (content-addressable links)
 * - **Composition**: Morphisms compose via hash chains (Merkle-DAG structure)
 *
 * The Carrier is where **actual systems live**. While the Target (CLM design space)
 * defines possible interfaces and interactions, the Carrier holds the real data.
 *
 * ## The Action: Loose(I) ⊛ Car(S) → Car(S)
 *
 * In DOTS, the **Action** is how interactions (from Target) act on systems (in Carrier)
 * to produce new systems. For CardCollection:
 * - PCard (Chart/Lens) defines the interaction pattern
 * - CardCollection.add() produces new MCard in the Carrier
 * - The result is a new Object in Car(S)
 *
 * ## Empty Schema Principle
 *
 * CardCollection embodies the Wordless Book principle:
 * - At t₀: Empty collection = "Wordless Book"
 * - At t_n: Billions of cards = "Infinite Library"
 * - Schema (structure) never changes; only data (content) grows
 *
 * ## CRD-Only Operations (No UPDATE)
 *
 * Following MCard design principles, this collection supports only:
 * - **C**reate: `add()`, `addWithHandle()`
 * - **R**ead: `get()`, `getByHandle()`, `getPage()`, `search*()`
 * - **D**elete: `delete()`, `clear()`
 *
 * There is NO `update()` method. Instead, to "update":
 * 1. Create a new MCard with new content
 * 2. Use `updateHandle()` to point the handle to the new hash
 * 3. The old MCard remains in the collection (immutable history)
 *
 * ## CRDT Foundation (G-Set)
 *
 * CardCollection implements **Grow-Only Set (G-Set) CRDT** semantics:
 * - **Commutative**: merge(A, B) = merge(B, A)
 * - **Associative**: merge(A, merge(B, C)) = merge(merge(A, B), C)
 * - **Idempotent**: merge(A, A) = A (same hash = same card)
 *
 * This enables **Strong Eventual Consistency** without coordination.
 *
 * ## Monadic API
 *
 * The `*M` methods (getM, getByHandleM, etc.) return Maybe<T> monads
 * for composable, null-safe operations following functional programming patterns.
 *
 * @see {@link MCard} for the individual Carrier objects
 * @see {@link DOTSRole.CARRIER} for DOTS vocabulary definition
 * @see docs/WorkingNotes/Permanent/Projects/PKC Kernel/MCard.md for full specification
 */
export declare class CardCollection {
    private engine;
    constructor(engine: StorageEngine);
    /**
     * Add a card to the collection
     * Handles duplicates (same content, same hash) and collisions (diff content, same hash)
     */
    add(card: MCard): Promise<string>;
    private areContentsEqual;
    /**
     * Get a card by hash
     */
    get(hash: string): Promise<MCard | null>;
    /**
     * Delete a card by hash
     */
    delete(hash: string): Promise<void>;
    /**
     * Get a page of cards
     */
    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
    /**
     * Count total cards
     */
    count(): Promise<number>;
    /**
     * Add a card and register a handle for it
     */
    addWithHandle(card: MCard, handle: string): Promise<string>;
    /**
     * Get card by handle
     */
    getByHandle(handle: string): Promise<MCard | null>;
    /**
     * Resolve handle to hash
     */
    resolveHandle(handle: string): Promise<string | null>;
    /**
     * Update handle to point to new card
     */
    updateHandle(handle: string, newCard: MCard): Promise<string>;
    /**
     * Get version history for a handle
     */
    getHandleHistory(handle: string): Promise<{
        previousHash: string;
        changedAt: string;
    }[]>;
    /**
     * Monadic get - returns Maybe<MCard>
     */
    getM(hash: string): Promise<Maybe<MCard>>;
    /**
     * Monadic getByHandle - returns Maybe<MCard>
     */
    getByHandleM(handle: string): Promise<Maybe<MCard>>;
    /**
     * Monadic resolveHandle - returns Maybe<string>
     */
    resolveHandleM(handle: string): Promise<Maybe<string>>;
    /**
     * Resolve handle and get card in one monadic operation
     */
    resolveAndGetM(handle: string): Promise<Maybe<MCard>>;
    /**
     * Prune version history for a handle.
     * @param handle The handle string.
     * @param options Options for pruning (olderThan date, or deleteAll).
     * @returns Number of deleted entries.
     */
    pruneHandleHistory(handle: string, options?: {
        olderThan?: string;
        deleteAll?: boolean;
    }): Promise<number>;
    clear(): Promise<void>;
    searchByString(query: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
    searchByContent(query: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
    searchByHash(hashPrefix: string): Promise<MCard[]>;
    getAllMCardsRaw(): Promise<MCard[]>;
    getAllCards(pageSize?: number, processCallback?: (card: MCard) => any): Promise<{
        cards: MCard[];
        total: number;
    }>;
    printAllCards(): Promise<void>;
}
//# sourceMappingURL=CardCollection.d.ts.map