docs(api): complete JSDoc coverage and export publicly-referenced types

Driven by the JSR score report, verified locally with deno doc --lint
(the same tool JSR scores with) down to zero findings:

- both entrypoints carry an explicit @module doc (the score's
  missing-module-docs item keyed on the tag, not the comment)
- every exported symbol member gets JSDoc: LibreDbError.code and
  constructor, OpenOptions.path, Entry.key/value, KvEntry, DocEntry,
  TableSchema, CatalogEntry, WriteResult.changed, Store.transact
- types referenced by public signatures are exported instead of
  reachable-but-unnamed: Transaction/Entry/Key/Value/Open/Store from
  the main entry, the browser equivalents from the browser entry
  (fixes deno doc private-type-ref findings)
- index.ts open gains an explicit parameter/return annotation

Changeset: minor (new type exports).

Author: cevheri

.changeset/jsr-doc-completeness.md

@@ -0,0 +1,7 @@
+---
+"@libredb/libredb": minor
+---
+
+Complete the API documentation surface and export the types it references.
+
+Every exported symbol — including interface and class members — now carries JSDoc, and both entrypoints carry an explicit module doc, so generated documentation (JSR, editors) is complete. Types that public signatures reference are now exported instead of being reachable-but-unnamed: `Transaction`, `Entry`, `Key`, `Value`, `Open`, and the lens seam `Store` from the main entry; `Transaction`, `Entry`, `Key`, `Value`, and `Store` from the browser entry. No runtime behavior changes.

src/adapter/store.ts

@@ -28,5 +28,8 @@ import type { Transaction } from "../core.ts";
  * {@link import("../core.ts").Database.transact}.
  */
 export interface Store {
+  /** Run `run` inside a transaction, applying its writes atomically — the
+   * same contract as {@link Database.transact}, which is the seam's one
+   * requirement of an implementer. */
   transact<T>(run: (tx: Transaction) => T): T;
 }

src/browser.ts

@@ -10,11 +10,14 @@
  * given, so misuse is a compile error rather than a runtime throw. The point of
  * this entry is the import graph: it reaches nothing in `node:`, so a bundler
  * can ship it to a browser. The node:fs adapter lives behind Node only.
+ *
+ * @module
  */
 import { open as openKernel, type Database, type FileSystem, type RecoveryInfo } from "./core.ts";
 
 export { version, LibreDbError } from "./core.ts";
-export type { ErrorCode, RecoveryInfo } from "./core.ts";
+export type { Entry, ErrorCode, Key, RecoveryInfo, Transaction, Value } from "./core.ts";
+export type { Store } from "./adapter/store.ts";
 // OpenOptions (the kernel's permissive type, fs optional) is intentionally NOT
 // re-exported here: the browser `open` is typed with BrowserOpenOptions, where fs
 // is required alongside a path, so exposing OpenOptions would advertise a

src/core.ts

@@ -60,8 +60,12 @@ export type ErrorCode =
  * humans and may change between releases.
  */
 export class LibreDbError extends Error {
+  /** The stable failure code — the part of the error a caller may branch on.
+   * See {@link ErrorCode} for the meaning of each value. */
   readonly code: ErrorCode;
 
+  /** Build a kernel error: `message` is prefixed with `libredb: `, and the
+   * adapter error that caused the failure (if any) rides along as `cause`. */
   constructor(code: ErrorCode, message: string, options?: { cause?: unknown }) {
     super(`libredb: ${message}`, options);
     this.name = "LibreDbError";
@@ -86,7 +90,10 @@ export type Value = Uint8Array;
 
 /** One key/value pair yielded by an ordered range scan. */
 export interface Entry {
+  /** The entry's key. A copy owned by the caller — mutating it cannot touch
+   * the committed store. */
   readonly key: Key;
+  /** The value stored under {@link key}. Also a caller-owned copy. */
   readonly value: Value;
 }
 
@@ -229,6 +236,8 @@ export interface RecoveryInfo {
  * kernel is purely in-memory — the natural fit for tests and ephemeral use.
  */
 export interface OpenOptions {
+  /** The file the write-ahead log lives at. Omit it for a purely in-memory
+   * database (the natural fit for tests and ephemeral use). */
   readonly path?: string;
   /**
    * The filesystem the write-ahead log runs on. Optional at the type level, but a

src/index.ts

@@ -9,12 +9,27 @@
  * namespaces a database holds, so a tool can render faithful per-kind views;
  * {@link isReservedKey} (with {@link RESERVED_MARKER} / {@link CATALOG_PREFIX})
  * lets a raw-KV tool hide engine-internal keys instead of hardcoding the layout.
+ *
+ * @module
  */
-import { open as openKernel, type Open } from "./core.ts";
+import { open as openKernel, type Database, type OpenOptions } from "./core.ts";
 import { nodeFileSystem } from "./adapter/node-fs.ts";
 
 export { version, LibreDbError } from "./core.ts";
-export type { Database, ErrorCode, FileSystem, OpenOptions, RecoveryInfo, WalFile } from "./core.ts";
+export type {
+  Database,
+  Entry,
+  ErrorCode,
+  FileSystem,
+  Key,
+  Open,
+  OpenOptions,
+  RecoveryInfo,
+  Transaction,
+  Value,
+  WalFile,
+} from "./core.ts";
+export type { Store } from "./adapter/store.ts";
 
 /**
  * Open a LibreDB database on Node or Bun. Identical to the kernel's
@@ -24,7 +39,7 @@ export type { Database, ErrorCode, FileSystem, OpenOptions, RecoveryInfo, WalFil
  * The browser entry (`@libredb/libredb/browser`) omits this default so it never
  * imports `node:fs`.
  */
-export const open: Open = (options) =>
+export const open = (options?: OpenOptions): Database =>
   options?.path !== undefined && options.fs === undefined
     ? openKernel({ ...options, fs: nodeFileSystem() })
     : openKernel(options);

src/lens/catalog.ts

@@ -154,7 +154,10 @@ export function isReservedKey(key: string): boolean {
  * layer); a `document` entry carries only `kind` (documents are schemaless).
  */
 export interface CatalogEntry {
+  /** Which lens the namespace belongs to — the interpretation a cold-opening
+   * tool needs to render a faithful view. */
   readonly kind: "kv" | "document" | "relational";
+  /** A relational table's declared schema; absent for the schemaless kinds. */
   readonly schema?: TableSchema;
 }
 

src/lens/document.ts

@@ -38,7 +38,10 @@ export type Doc = { [key: string]: JsonValue };
  * `Result<DocEntry>` (lens/types.ts), the same envelope the kv lens uses.
  */
 export interface DocEntry {
+  /** The document's id within its collection (the part of the kernel key
+   * after the `<collection>:` prefix). */
   readonly id: string;
+  /** The decoded document stored under {@link id}. */
   readonly doc: Doc;
 }
 

src/lens/kv.ts

@@ -29,7 +29,9 @@ import type { Store } from "../adapter/store.ts";
 /** One key/value pair from a range scan, decoded to strings. The kv-lens
  * counterpart of the kernel's byte-level {@link import("../core.ts").Entry}. */
 export interface KvEntry {
+  /** The entry's key, decoded from the kernel's UTF-8 bytes. */
   readonly key: string;
+  /** The value stored under {@link key}, decoded the same way. */
   readonly value: string;
 }
 

src/lens/relational.ts

@@ -43,7 +43,11 @@ export type ColumnType = "string" | "number" | "boolean" | "object";
  * handle is built.
  */
 export interface TableSchema {
+  /** The column whose value becomes the row's kernel key. Must name a
+   * declared `"string"` column. */
   readonly primaryKey: string;
+  /** The declared columns: every row must carry exactly these fields, each
+   * matching its {@link ColumnType}. */
   readonly columns: { readonly [name: string]: ColumnType };
 }
 

src/lens/types.ts

@@ -46,6 +46,7 @@ export interface Result<Row> extends Iterable<Row> {
  * write actually did.
  */
 export interface WriteResult {
+  /** How many stored entries the write created, overwrote, or removed. */
   readonly changed: number;
 }