Interface LearningStore

A learning store: the operations above, a transaction, and its end.

interface LearningStore {
    insertLedgerRow(row): Promise<void>;
    ledgerRow(id): Promise<undefined | StoredLedgerRow>;
    chainRows(chainKey): Promise<StoredLedgerRow[]>;
    chainWithHead(chainKey): Promise<{
        rows: StoredLedgerRow[];
        head: undefined | ChainHead;
    }>;
    candidateRows(candidateId): Promise<StoredLedgerRow[]>;
    learnerLedgerRows(namespace, agentKey, userId): Promise<StoredLedgerRow[]>;
    agentPendingRows(namespace, agentKey, createdBefore): Promise<StoredLedgerRow[]>;
    head(chainKey): Promise<undefined | ChainHead>;
    insertHead(head): Promise<boolean>;
    advanceHead(chainKey, expectedSeq, next): Promise<boolean>;
    markHeadsForgotten(namespace, userId): Promise<number>;
    traitRow(namespace, agentKey, userId): Promise<undefined | StoredTraitRow>;
    insertTraitRow(row): Promise<boolean>;
    updateTraitRow(row, expectedVersion): Promise<boolean>;
    freezeRows(): Promise<FreezeRow[]>;
    insertFreeze(row): Promise<void>;
    deleteFreeze(scopeKey, mode): Promise<boolean>;
    sessionRow(namespace, agentKey, sessionId, userId, kind): Promise<undefined | SessionRow>;
    putSessionRow(row, expectedVersion?): Promise<void>;
    sessionRowsOf(namespace, userId): Promise<SessionRow[]>;
    sessionRowsIn?(namespace, agentKey, sessionId): Promise<SessionRow[]>;
    isForgotten(hash): Promise<boolean>;
    insertForgotten(hash, forgottenAt): Promise<void>;
    learnerDocs(table, namespace, agentKey, userId): Promise<LearnerDocRow[]>;
    deleteUserRows(namespace, userId): Promise<Record<string, number>>;
    kind: "memory" | "sql";
    transaction<T>(fn): Promise<T>;
    close(): Promise<void>;
}

Hierarchy

  • LearningStoreTx
    • LearningStore

Methods

insertLedgerRow ledgerRow chainRows chainWithHead candidateRows learnerLedgerRows agentPendingRows head insertHead advanceHead markHeadsForgotten traitRow insertTraitRow updateTraitRow freezeRows insertFreeze deleteFreeze sessionRow putSessionRow sessionRowsOf sessionRowsIn? isForgotten insertForgotten learnerDocs deleteUserRows transaction close

Properties

kind

Methods

insertLedgerRow

  • insertLedgerRow(row): Promise<void>

  • Appends a row; throws when a row has its id, or its chain has a row at its seq.

    Parameters

    • row: StoredLedgerRow

    Returns Promise<void>

ledgerRow

chainRows

chainWithHead

  • chainWithHead(chainKey): Promise<{
        rows: StoredLedgerRow[];
        head: undefined | ChainHead;
    }>

  • A chain's rows in sequence order and its head, read at one moment: an append that commits meanwhile is in both or in neither, also on a database that gives each statement of a transaction its own snapshot (Postgres at Read Committed), where the SQL store reads both in one statement.

    Parameters

    • chainKey: string

    Returns Promise<{
        rows: StoredLedgerRow[];
        head: undefined | ChainHead;
    }>

candidateRows

  • candidateRows(candidateId): Promise<StoredLedgerRow[]>

  • A candidate and its verdicts, in sequence order.

    Parameters

    • candidateId: string

    Returns Promise<StoredLedgerRow[]>

learnerLedgerRows

  • learnerLedgerRows(namespace, agentKey, userId): Promise<StoredLedgerRow[]>

  • The rows keyed to one learner (by namespace, agent and userId), ordered by chain key and sequence.

    Parameters

    • namespace: string
    • agentKey: string
    • userId: string

    Returns Promise<StoredLedgerRow[]>

agentPendingRows

  • agentPendingRows(namespace, agentKey, createdBefore): Promise<StoredLedgerRow[]>

  • The candidates that have no verdict row on one agent's chains with no learner in one namespace (the agent's own chain and each second user's), created at or before createdBefore (an ISO time), ordered by chain key and sequence: what a crash left pending there.

    Parameters

    • namespace: string
    • agentKey: string
    • createdBefore: string

    Returns Promise<StoredLedgerRow[]>

head

insertHead

advanceHead

  • advanceHead(chainKey, expectedSeq, next): Promise<boolean>

  • Moves a head from expectedSeq to next, whose lastId, lastHash and seq alone it writes; false when the chain has no head, the head moved on, or it is marked forgotten.

    Parameters

    • chainKey: string
    • expectedSeq: number
    • next: {
          lastId: string;
          lastHash: string;
          seq: number;
      }
      • lastId: string
      • lastHash: string
      • seq: number

    Returns Promise<boolean>

markHeadsForgotten

  • markHeadsForgotten(namespace, userId): Promise<number>

  • Marks every head of one user in one namespace forgotten; returns how many.

    Parameters

    • namespace: string
    • userId: string

    Returns Promise<number>

traitRow

  • traitRow(namespace, agentKey, userId): Promise<undefined | StoredTraitRow>

  • Parameters

    • namespace: string
    • agentKey: string
    • userId: string

    Returns Promise<undefined | StoredTraitRow>

insertTraitRow

updateTraitRow

  • updateTraitRow(row, expectedVersion): Promise<boolean>

  • Writes row over the row at expectedVersion; false when another write moved it on, or there is none.

    Parameters

    • row: StoredTraitRow
    • expectedVersion: number

    Returns Promise<boolean>

freezeRows

insertFreeze

deleteFreeze

sessionRow

  • sessionRow(namespace, agentKey, sessionId, userId, kind): Promise<undefined | SessionRow>

  • Parameters

    • namespace: string
    • agentKey: string
    • sessionId: string
    • userId: string
    • kind: "learner" | "visitor"

    Returns Promise<undefined | SessionRow>

putSessionRow

  • putSessionRow(row, expectedVersion?): Promise<void>

  • Inserts the row, or writes it over the row of the same learner, session and kind, keeping that row's startedAt. With expectedVersion, the version its writer read, it writes over the row only at that version, and inserts it only where there is none for 0: a row another writer moved on since is left as it is, which a read of the row shows, so two writers that read one row never drop each other's ids.

    Parameters

    • row: SessionRow
    • Optional expectedVersion: number

    Returns Promise<void>

sessionRowsOf

  • sessionRowsOf(namespace, userId): Promise<SessionRow[]>

  • One user's session rows of both kinds in one namespace, every agent's, ordered by session id and kind.

    Parameters

    • namespace: string
    • userId: string

    Returns Promise<SessionRow[]>

Optional sessionRowsIn

  • sessionRowsIn(namespace, agentKey, sessionId): Promise<SessionRow[]>

  • One session's rows of every user and both kinds, ordered by user id and kind: forgetUser reads the learner of a session the user spoke on as a second user, whose own scopes can hold a summary of the user's words. Optional, so a host's own store written against an earlier release still opens; forgetUser names those scopes unreached on it.

    Parameters

    • namespace: string
    • agentKey: string
    • sessionId: string

    Returns Promise<SessionRow[]>

isForgotten

insertForgotten

learnerDocs

  • learnerDocs(table, namespace, agentKey, userId): Promise<LearnerDocRow[]>

  • One learner's rows of a learner document table, ordered by createdAt and id.

    Parameters

    • table: LearnerDocTable
    • namespace: string
    • agentKey: string
    • userId: string

    Returns Promise<LearnerDocRow[]>

deleteUserRows

  • deleteUserRows(namespace, userId): Promise<Record<string, number>>

  • Deletes every row of one user in one namespace: ledger rows whose userId or turnUserId is the user, the user's heads, trait rows, outcomes, lessons, skills, session rows of both kinds, and freezes keyed to the user's learners. Never the tombstone, which every later write for the user checks.

    Parameters

    • namespace: string
    • userId: string

    Returns Promise<Record<string, number>>

    The rows deleted, per table: ledger, heads, traits, outcomes, lessons, skills, sessions and freezes.

transaction

  • transaction<T>(fn): Promise<T>

  • Runs fn in one transaction: every write it makes through tx commits together, or none does when it throws. fn makes every call through tx, never through the store: a call on the store runs outside the transaction, and a store that runs one call at a time holds it until the transaction ends, so a transaction that waits for it never ends.

    Type Parameters

    • T

    Parameters

    • fn: ((tx) => Promise<T>)
        • (tx): Promise<T>

        • Parameters

          • tx: LearningStoreTx

          Returns Promise<T>

    Returns Promise<T>

close

Properties

Readonly kind

kind: "memory" | "sql"

sql for a store over a storage adapter; memory for one that ends with the process.

Settings

Member Visibility

Theme

On This Page

insertLedgerRowledgerRowchainRowschainWithHeadcandidateRowslearnerLedgerRowsagentPendingRowsheadinsertHeadadvanceHeadmarkHeadsForgottentraitRowinsertTraitRowupdateTraitRowfreezeRowsinsertFreezedeleteFreezesessionRowputSessionRowsessionRowsOfsessionRowsInisForgotteninsertForgottenlearnerDocsdeleteUserRowstransactionclosekind