From 755b1a6fc16522467d99fe87cae92832275645fe Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Thu, 19 Jun 2025 15:00:41 -0700
Subject: [PATCH] **feat: add browser-compatible exports and define BrainyData
 interface**

### Changes:
- Created `examples/browser_compatible_exports.ts`:
  - Introduced browser-friendly exports with polyfill for `Buffer` in browser environments.
  - Implemented shims for Node.js modules (`fs`, `util`, and `path`) to avoid compatibility issues.
  - Exported browser-compatible types and utilities: `BrainyData`, `NounType`, `VerbType`, graph types, core types, distance functions, embedding utilities, and storage adapters.
  - Explicitly excluded Node.js/CLI-specific parts to focus on browser compatibility.
- Added `src/types/brainyDataInterface.ts`:
  - Defined `BrainyDataInterface` to break the circular dependency between `brainyData.ts` and `serverSearchAugmentations.ts`.
  - Provided methods for managing nodes, relationships, initialization, search, and adding vector data with metadata.

### Purpose:
- Enhanced the codebase to support browser environments by introducing browser-specific exports and avoiding Node.js dependencies.
- Established clearer separation of concerns and modularity by introducing the `BrainyDataInterface` for dependency management, improving maintainability and flexibility.
---
 examples/browser_compatible_exports.ts | 69 ++++++++++++++++++++++++++
 src/types/brainyDataInterface.ts       | 47 ++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 examples/browser_compatible_exports.ts
 create mode 100644 src/types/brainyDataInterface.ts

diff --git a/examples/browser_compatible_exports.ts b/examples/browser_compatible_exports.ts
new file mode 100644
index 00000000..92200118
--- /dev/null
+++ b/examples/browser_compatible_exports.ts
@@ -0,0 +1,69 @@
+// Import and provide Buffer polyfill for browser environment
+import { Buffer } from 'buffer'
+// Make Buffer available globally
+globalThis.Buffer = Buffer
+
+// Explicitly avoid importing Node.js modules like 'fs' and 'util'
+// by using a dynamic import with a shim for Node.js modules
+if (typeof window !== 'undefined') {
+  // Browser environment - create empty shims for Node.js modules
+  // Add missing properties to match the Node.js Require interface
+  const browserRequire = function(module: string) {
+    if (module === 'fs' || module === 'util' || module === 'path') {
+      console.warn(`Module '${module}' is not available in browser environments.`)
+      return {}
+    }
+    throw new Error(`Cannot require module '${module}' in browser environment.`)
+  }
+
+  // Add the missing properties from the Node.js Require interface
+  browserRequire.cache = {}
+  browserRequire.extensions = {}
+  browserRequire.main = { exports: {} }
+  browserRequire.resolve = (id: string) => id
+
+  // Assign to window
+  window.require = browserRequire as any
+}
+
+// Export only browser-compatible parts
+export { BrainyData } from '../src/brainyData.js'
+export type { BrainyDataConfig } from '../src/brainyData.js'
+export { NounType, VerbType } from '../src/types/graphTypes.js'
+export type { GraphNoun } from '../src/types/graphTypes.js'
+
+// Export core types
+export type {
+  Vector,
+  VectorDocument,
+  SearchResult,
+  DistanceFunction,
+  EmbeddingFunction,
+  HNSWConfig,
+  StorageAdapter
+} from '../src/coreTypes.js'
+
+// Export distance functions for convenience
+export {
+  euclideanDistance,
+  cosineDistance,
+  manhattanDistance,
+  dotProductDistance
+} from '../src/utils/index.js'
+
+// Export embedding functionality
+export {
+  UniversalSentenceEncoder,
+  createEmbeddingFunction,
+  createTensorFlowEmbeddingFunction,
+  defaultEmbeddingFunction
+} from '../src/utils/embedding.js'
+
+// Export storage adapters (only browser-compatible ones)
+export {
+  OPFSStorage,
+  MemoryStorage,
+  createStorage
+} from '../src/storage/opfsStorage.js'
+
+// Note: Exclude CLI and Node.js specific parts
diff --git a/src/types/brainyDataInterface.ts b/src/types/brainyDataInterface.ts
new file mode 100644
index 00000000..ef35d5df
--- /dev/null
+++ b/src/types/brainyDataInterface.ts
@@ -0,0 +1,47 @@
+/**
+ * BrainyDataInterface
+ * 
+ * This interface defines the methods from BrainyData that are used by serverSearchAugmentations.ts.
+ * It's used to break the circular dependency between brainyData.ts and serverSearchAugmentations.ts.
+ */
+
+import { Vector } from '../coreTypes.js'
+
+export interface BrainyDataInterface<T = unknown> {
+  /**
+   * Initialize the database
+   */
+  init(): Promise<void>
+
+  /**
+   * Get a noun by ID
+   * @param id The ID of the noun to get
+   */
+  get(id: string): Promise<unknown>
+
+  /**
+   * Add a vector or data to the database
+   * @param vectorOrData Vector or data to add
+   * @param metadata Optional metadata to associate with the vector
+   * @returns The ID of the added vector
+   */
+  add(vectorOrData: Vector | unknown, metadata?: T): Promise<string>
+
+  /**
+   * Search for text in the database
+   * @param text The text to search for
+   * @param limit Maximum number of results to return
+   * @returns Search results
+   */
+  searchText(text: string, limit?: number): Promise<unknown[]>
+
+  /**
+   * Create a relationship between two entities
+   * @param sourceId The ID of the source entity
+   * @param targetId The ID of the target entity
+   * @param relationType The type of relationship
+   * @param metadata Optional metadata about the relationship
+   * @returns The ID of the created relationship
+   */
+  relate(sourceId: string, targetId: string, relationType: string, metadata?: unknown): Promise<string>
+}