okf-search-native 0.3.4 → 0.4.0

package/README.md

@@ -41,6 +41,7 @@ const document = {
 const validation = validateOkfDocument(document);
 const index = createOkfSearch([document]);
 const hits = index.search("memory", { limit: 10, fields: ["body"] });
+const stats = index.indexStats();
 
 const directoryIndex = await openOkf("./knowledge");
 directoryIndex.ingest({
@@ -66,6 +67,48 @@ highest-ranked matching section and includes the document path, heading path,
 line range, matched fields, and snippet. The handle also provides `listTypes()`
 and `listDegradedDocuments()` for inspecting the current collection.
 
+### Index statistics
+
+`indexStats()` returns a detached, recursively frozen snapshot:
+
+```ts
+{
+  logical: {
+    documents: {
+      total: number;
+      strict: number;
+      degraded: number;
+    };
+    types: readonly {
+      type: string;
+      documentCount: number;
+    }[];
+    statuses: {
+      draft: number;
+      stable: number;
+      deprecated: number;
+      unclassified: number;
+    };
+    trustTiers: {
+      unverified: number;
+      machineConfirmed: number;
+      humanReviewed: number;
+      unclassified: number;
+    };
+  };
+  storage: {
+    kind: "in-memory-index-files";
+    sizeInBytes: number;
+  };
+}
+```
+
+Logical values count documents, not sections, and change only after a successful
+`ingest` or `remove`. `types` preserves case and is sorted by type. Missing
+effective status or trust-tier metadata counts as `unclassified`.
+`sizeInBytes` samples the handle's Tantivy `RamDirectory`; it excludes other
+process memory and can change without a logical change.
+
 ### Validation
 
 `validateOkfDocument` checks one Markdown document without changing an index.
@@ -95,6 +138,7 @@ import { NativeOkfSearch } from "okf-search-native/prepared";
 
 const index = NativeOkfSearch.fromPrepared(preparedDocuments);
 const hits = index.search("memory", { limit: 10, fields: ["body"] });
+const stats = index.indexStats();
 index.ingestPrepared(preparedDocument);
 index.removeDocument("docs/old");
 ```
@@ -104,7 +148,8 @@ replaces every indexed section owned by one document, and `removeDocument`
 removes them together. `PreparedDocument` contains document-wide metadata once;
 each `PreparedSection` contains only its ID, heading path, text, and line
 bounds. The DTO declarations are exported from `okf-search-native/prepared`,
-not from the package root.
+not from the package root. Its `indexStats()` result has the shape above but is
+a mutable N-API DTO; the package-root adapter returns the frozen copy.
 
 ## Requirements and tested platforms
 

package/dist/index.cjs

@@ -15541,6 +15541,10 @@ function createOkfSearch(documents) {
     }
   };
   return {
+    indexStats() {
+      assertUsable();
+      return copyIndexStats(callNative("<index>", () => native.indexStats()));
+    },
     ingest(input) {
       assertUsable();
       let result;
@@ -15639,6 +15643,36 @@ function copyNonEmptyDiagnostics(diagnostics) {
   }
   return [first, ...rest];
 }
+function copyIndexStats(stats) {
+  const types = Object.freeze(
+    stats.logical.types.map(({ type, documentCount }) => Object.freeze({ type, documentCount })).sort((left, right) => compare(left.type, right.type))
+  );
+  const logical = Object.freeze({
+    documents: Object.freeze({
+      total: stats.logical.documents.total,
+      strict: stats.logical.documents.strict,
+      degraded: stats.logical.documents.degraded
+    }),
+    types,
+    statuses: Object.freeze({
+      draft: stats.logical.statuses.draft,
+      stable: stats.logical.statuses.stable,
+      deprecated: stats.logical.statuses.deprecated,
+      unclassified: stats.logical.statuses.unclassified
+    }),
+    trustTiers: Object.freeze({
+      unverified: stats.logical.trustTiers.unverified,
+      machineConfirmed: stats.logical.trustTiers.machineConfirmed,
+      humanReviewed: stats.logical.trustTiers.humanReviewed,
+      unclassified: stats.logical.trustTiers.unclassified
+    })
+  });
+  const storage = Object.freeze({
+    kind: "in-memory-index-files",
+    sizeInBytes: stats.storage.sizeInBytes
+  });
+  return Object.freeze({ logical, storage });
+}
 function copySearchHit(hit) {
   return {
     documentId: hit.documentId,

package/dist/index.d.cts

@@ -89,6 +89,41 @@ interface OkfDegradedDocument {
     readonly path: string;
     readonly diagnostics: readonly [OkfDiagnostic, ...OkfDiagnostic[]];
 }
+interface OkfLogicalIndexStats {
+    readonly documents: {
+        readonly total: number;
+        readonly strict: number;
+        readonly degraded: number;
+    };
+    readonly types: readonly {
+        readonly type: string;
+        readonly documentCount: number;
+    }[];
+    readonly statuses: {
+        readonly draft: number;
+        readonly stable: number;
+        readonly deprecated: number;
+        readonly unclassified: number;
+    };
+    readonly trustTiers: {
+        readonly unverified: number;
+        readonly machineConfirmed: number;
+        readonly humanReviewed: number;
+        readonly unclassified: number;
+    };
+}
+type OkfIndexStorageStats = {
+    readonly kind: "in-memory-index-files";
+    readonly sizeInBytes: number;
+} | {
+    readonly kind: "serialized-index";
+    readonly format: "minisearch-json-utf8";
+    readonly sizeInBytes: number;
+};
+interface OkfIndexStats {
+    readonly logical: OkfLogicalIndexStats;
+    readonly storage: OkfIndexStorageStats;
+}
 type OkfConformance = "strict" | "degraded";
 type OkfIngestResult = {
     readonly conformance: "strict";
@@ -127,6 +162,7 @@ interface OkfSearchHit {
     snippet: string;
 }
 interface OkfSearch {
+    indexStats(): OkfIndexStats;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -153,4 +189,4 @@ declare function openOkf(root: string): Promise<OkfSearch>;
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIngestResult, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.d.mts

@@ -89,6 +89,41 @@ interface OkfDegradedDocument {
     readonly path: string;
     readonly diagnostics: readonly [OkfDiagnostic, ...OkfDiagnostic[]];
 }
+interface OkfLogicalIndexStats {
+    readonly documents: {
+        readonly total: number;
+        readonly strict: number;
+        readonly degraded: number;
+    };
+    readonly types: readonly {
+        readonly type: string;
+        readonly documentCount: number;
+    }[];
+    readonly statuses: {
+        readonly draft: number;
+        readonly stable: number;
+        readonly deprecated: number;
+        readonly unclassified: number;
+    };
+    readonly trustTiers: {
+        readonly unverified: number;
+        readonly machineConfirmed: number;
+        readonly humanReviewed: number;
+        readonly unclassified: number;
+    };
+}
+type OkfIndexStorageStats = {
+    readonly kind: "in-memory-index-files";
+    readonly sizeInBytes: number;
+} | {
+    readonly kind: "serialized-index";
+    readonly format: "minisearch-json-utf8";
+    readonly sizeInBytes: number;
+};
+interface OkfIndexStats {
+    readonly logical: OkfLogicalIndexStats;
+    readonly storage: OkfIndexStorageStats;
+}
 type OkfConformance = "strict" | "degraded";
 type OkfIngestResult = {
     readonly conformance: "strict";
@@ -127,6 +162,7 @@ interface OkfSearchHit {
     snippet: string;
 }
 interface OkfSearch {
+    indexStats(): OkfIndexStats;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -153,4 +189,4 @@ declare function openOkf(root: string): Promise<OkfSearch>;
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIngestResult, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.d.ts

@@ -89,6 +89,41 @@ interface OkfDegradedDocument {
     readonly path: string;
     readonly diagnostics: readonly [OkfDiagnostic, ...OkfDiagnostic[]];
 }
+interface OkfLogicalIndexStats {
+    readonly documents: {
+        readonly total: number;
+        readonly strict: number;
+        readonly degraded: number;
+    };
+    readonly types: readonly {
+        readonly type: string;
+        readonly documentCount: number;
+    }[];
+    readonly statuses: {
+        readonly draft: number;
+        readonly stable: number;
+        readonly deprecated: number;
+        readonly unclassified: number;
+    };
+    readonly trustTiers: {
+        readonly unverified: number;
+        readonly machineConfirmed: number;
+        readonly humanReviewed: number;
+        readonly unclassified: number;
+    };
+}
+type OkfIndexStorageStats = {
+    readonly kind: "in-memory-index-files";
+    readonly sizeInBytes: number;
+} | {
+    readonly kind: "serialized-index";
+    readonly format: "minisearch-json-utf8";
+    readonly sizeInBytes: number;
+};
+interface OkfIndexStats {
+    readonly logical: OkfLogicalIndexStats;
+    readonly storage: OkfIndexStorageStats;
+}
 type OkfConformance = "strict" | "degraded";
 type OkfIngestResult = {
     readonly conformance: "strict";
@@ -127,6 +162,7 @@ interface OkfSearchHit {
     snippet: string;
 }
 interface OkfSearch {
+    indexStats(): OkfIndexStats;
     ingest(input: OkfDocumentInput): OkfIngestResult;
     listDegradedDocuments(): readonly OkfDegradedDocument[];
     listTypes(): readonly string[];
@@ -153,4 +189,4 @@ declare function openOkf(root: string): Promise<OkfSearch>;
 declare function validateOkfDocument(input: OkfDocumentInput): OkfValidationResult;
 
 export { OkfError, createOkfSearch, openOkf, validateOkfDocument };
-export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIngestResult, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };
+export type { IsoDateTime, OkfAttester, OkfConformance, OkfDegradedDocument, OkfDiagnostic, OkfDiagnosticCode, OkfDocument, OkfDocumentInput, OkfErrorCode, OkfExecutor, OkfGeneration, OkfIndexStats, OkfIndexStorageStats, OkfIngestResult, OkfLogicalIndexStats, OkfParameter, OkfSearch, OkfSearchField, OkfSearchHit, OkfSearchOptions, OkfSource, OkfStatus, OkfTimeWindow, OkfTrustTier, OkfValidationResult, OkfVerification };

package/dist/index.mjs

@@ -15537,6 +15537,10 @@ function createOkfSearch(documents) {
     }
   };
   return {
+    indexStats() {
+      assertUsable();
+      return copyIndexStats(callNative("<index>", () => native.indexStats()));
+    },
     ingest(input) {
       assertUsable();
       let result;
@@ -15635,6 +15639,36 @@ function copyNonEmptyDiagnostics(diagnostics) {
   }
   return [first, ...rest];
 }
+function copyIndexStats(stats) {
+  const types = Object.freeze(
+    stats.logical.types.map(({ type, documentCount }) => Object.freeze({ type, documentCount })).sort((left, right) => compare(left.type, right.type))
+  );
+  const logical = Object.freeze({
+    documents: Object.freeze({
+      total: stats.logical.documents.total,
+      strict: stats.logical.documents.strict,
+      degraded: stats.logical.documents.degraded
+    }),
+    types,
+    statuses: Object.freeze({
+      draft: stats.logical.statuses.draft,
+      stable: stats.logical.statuses.stable,
+      deprecated: stats.logical.statuses.deprecated,
+      unclassified: stats.logical.statuses.unclassified
+    }),
+    trustTiers: Object.freeze({
+      unverified: stats.logical.trustTiers.unverified,
+      machineConfirmed: stats.logical.trustTiers.machineConfirmed,
+      humanReviewed: stats.logical.trustTiers.humanReviewed,
+      unclassified: stats.logical.trustTiers.unclassified
+    })
+  });
+  const storage = Object.freeze({
+    kind: "in-memory-index-files",
+    sizeInBytes: stats.storage.sizeInBytes
+  });
+  return Object.freeze({ logical, storage });
+}
 function copySearchHit(hit) {
   return {
     documentId: hit.documentId,

package/native.d.cts

@@ -10,6 +10,7 @@ export declare class NativeOkfSearch {
   ingestPrepared(document: PreparedDocument): void
   removeDocument(documentId: string): boolean
   search(query: string, options?: SearchOptions | undefined | null): Array<SearchHit>
+  indexStats(): IndexStats
   listTypes(): Array<string>
   listDegradedDocuments(): Array<DegradedDocument>
   /**
@@ -34,6 +35,48 @@ export interface Diagnostic {
   path: string
 }
 
+export interface IndexDocumentStats {
+  total: number
+  strict: number
+  degraded: number
+}
+
+export interface IndexStats {
+  logical: LogicalIndexStats
+  storage: IndexStorageStats
+}
+
+export interface IndexStatusStats {
+  draft: number
+  stable: number
+  deprecated: number
+  unclassified: number
+}
+
+export interface IndexStorageStats {
+  kind: "in-memory-index-files"
+  sizeInBytes: number
+}
+
+export interface IndexTrustTierStats {
+  unverified: number
+  machineConfirmed: number
+  humanReviewed: number
+  unclassified: number
+}
+
+export interface IndexTypeStats {
+  type: string
+  documentCount: number
+}
+
+export interface LogicalIndexStats {
+  documents: IndexDocumentStats
+  types: Array<IndexTypeStats>
+  statuses: IndexStatusStats
+  trustTiers: IndexTrustTierStats
+}
+
 export interface PreparedDocument {
   documentId: string
   path: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okf-search-native",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Search Open Knowledge Format collections at native speed with a lean Rust and Tantivy engine.",
   "keywords": [
     "open-knowledge-format",
@@ -51,9 +51,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/robhowley/okf-minisearch.git",
+    "url": "git+https://github.com/robhowley/okf-search.git",
     "directory": "packages/okf-search-native"
   },
+  "homepage": "https://github.com/robhowley/okf-search/tree/main/packages/okf-search-native#readme",
   "publishConfig": {
     "access": "public"
   },