Library

import { open } from 'langonrock';

const knowledge = open('okf:///var/data?tenant=acme');

const manifest = await knowledge.manifest('sales');
const hits = await knowledge.search('order grain', { k: 5 });
const concepts = await knowledge.get(['orders', 'customers'], { section: 'schema' });
const passage = await knowledge.get(['pride_3'], { find: 'ten thousand a year' });

await knowledge.close();

interface Connection {
  readonly transport: Transport;
  snapshot: () => Promise<string>;
  manifest: (bundle?: string) => Promise<string>;
  get: (ids: string[], options?: GetOptions) => Promise<Map<string, ConceptSlice>>;
  search: (query: string, options?: SearchOptions) => Promise<string>;
  listSource: () => Promise<SourceEntry[]>;
  readSource: (bundle: string, path: string) => Promise<SourceFile | undefined>;
  writeSource: (bundle: string, path: string, content: string, replaces?: string) => Promise<string>;
  deleteSource: (bundle: string, path: string, replaces: string) => Promise<void>;
  deleteBundle: (bundle: string) => Promise<void>;
  sync: () => Promise<SyncResult>;
  close: () => Promise<void>;
}

interface DatabaseConnection extends Connection {
  transact: (request: TransactionRequest) => Promise<RevisionResult>;
  history: (options?: HistoryOptions) => Promise<RevisionPage>;
  restore: (request: RestoreRequest) => Promise<RevisionResult>;
}

interface GetOptions {
  section?: string; // a named section instead of the whole document
  offset?: number;  // character offset into the addressed text
  limit?: number;   // maximum characters returned; absent means all of it
  find?: string;    // literal, case-insensitive phrase; overrides offset
}

interface ConceptSlice {
  text: string;
  start: number;
  end: number;
  total: number;
  matches?: number[];   // offsets of find occurrences, capped at 20
  matchCount?: number;  // full occurrence count, uncapped
}

interface SearchOptions {
  k?: number;      // ranked matches before expansion, default 8
  expand?: boolean; // one-hop link expansion, default true
  bundle?: string;  // rank and expand within one bundle
}

interface SourceEntry {
  bundle: string;
  path: string;
  bytes: number;
  hash: string;
  id?: string; // absent only for navigation files like index.md
}

interface SyncResult {
  snapshot: string;
  concepts: number;
  bundles: string[];
  diagnostics: Diagnostic[];
}

type DocumentChange =
  | { operation: 'write'; bundle: string; path: string; content: string; replaces?: string }
  | { operation: 'delete'; bundle: string; path: string; replaces: string };

interface TransactionRequest {
  changes: DocumentChange[]; // 1 to 1,000, at most 16 MiB of source text
  expectedRevision?: string;
}

interface RevisionResult extends SyncResult {
  revision: string;
}

const first = await knowledge.transact({
  changes: [
    {
      operation: 'write',
      bundle: 'notes',
      path: 'intro.md',
      content: '---\ntype: concept\n---\n# Introduction\nSaved atomically.\n',
    },
  ],
});

const previous = await knowledge.readSource('notes', 'intro.md');

if (previous !== undefined) {
  await knowledge.transact({
    expectedRevision: first.revision,
    changes: [
      {
        operation: 'write',
        bundle: 'notes',
        path: 'intro.md',
        replaces: previous.hash,
        content: `${previous.content}\nUpdated.\n`,
      },
      { operation: 'write', bundle: 'notes', path: 'second.md', content: '# Second document\n' },
    ],
  });
}

interface RevisionInfo {
  revision: string;
  parent: string | null;
  snapshot: string;
  created: string;
  concepts: number;
  bundles: string[];
}

interface HistoryOptions {
  before?: string; // the `next` cursor of the previous page
  limit?: number;  // 1 to 100, default 20
}

interface RevisionPage {
  revisions: RevisionInfo[]; // newest first
  next?: string;
}

interface RestoreRequest {
  revision: string;
  expectedRevision: string;
}

import { openTenant } from 'langonrock';

const reader = await openTenant('/var/data', 'acme');

try {
  await reader.get(['orders'], { section: 'schema' });
} finally {
  reader.close?.();
}

import { connect } from 'langonrock/client';

const knowledge = connect('okf+http://127.0.0.1:7777?token=...');
const before = await knowledge.readSource('sales', 'tables/orders.md');

await knowledge.writeSource('sales', 'tables/orders.md', edited, before?.hash);

import {
  compileBundle,
  compileTenant,
  discoverBundles,
  splitSections,
  openTenant,
  transact,
  history,
  restore,
  importFolder,
  importFolders,
  exportFolder,
  migrate,
  verify,
  repair,
  putTenantRoot,
  watchTenant,
  buildTenantIndex,
  searchTenant,
  serve,
  collect,
  collectAll,
} from 'langonrock';

import { compileBundle } from 'langonrock';

const { tsv, concepts, diagnostics, bodies } = await compileBundle('sources/acme/sales', {
  bundle: 'sales',
  summaryWidth: 120,
});