soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

docs: add deprecation warnings for addNoun and addVerb methods

Browse source 
- Add @deprecated JSDoc tags to TypeScript definitions
- Update all documentation examples to use modern add() and relate() API
- Preserve batch operations (addNouns, addVerbs) as they remain current
- Mark deprecated methods in both source and compiled definitions

Migration guide:
- addNoun(data, type, metadata) → add(data, { nounType: type, ...metadata })
- addVerb(source, target, type, metadata) → relate(source, target, type, metadata)
This commit is contained in:
David Snelling 2025-09-17 10:48:41 -07:00
parent 20a54fbb7e
commit 2128ef5607
21 changed files with 343 additions and 331 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/api/COMPREHENSIVE_API_OVERVIEW.md
View file

@ -19,13 +19,13 @@ const brain = new BrainyData({ storage: { path: './my-data' } })
#### **2. Data Operations (CRUD)**
```typescript
// ✅ CONSISTENT: Always (data, type, metadata) pattern
await brain.addNoun(content, NounType.Person, { role: 'Engineer' })
await brain.addNoun(content, NounType.Document, { title: 'API Guide' })
// ✅ CONSISTENT: Always (data, metadata) pattern with nounType in metadata
await brain.add(content, { nounType: NounType.Person, role: 'Engineer' })
await brain.add(content, { nounType: NounType.Document, title: 'API Guide' })
// ✅ CONSISTENT: Always (source, target, type, metadata) pattern
await brain.addVerb(sourceId, targetId, VerbType.RelatedTo, { strength: 0.8 })
await brain.addVerb(sourceId, targetId, VerbType.Contains, { confidence: 0.9 })
// ✅ CONSISTENT: Always (source, target, type, metadata) pattern
await brain.relate(sourceId, targetId, VerbType.RelatedTo, { strength: 0.8 })
await brain.relate(sourceId, targetId, VerbType.Contains, { confidence: 0.9 })
// ✅ CONSISTENT: Batch versions take arrays
await brain.addNouns([...]) // Array of noun objects
@ -58,10 +58,10 @@ await brain.related(id, limit?) // Returns simple array
#### **Main Data Operations** (Direct on `brain`)
```typescript
// Core CRUD - most common operations
brain.addNoun(content, type, metadata?)
brain.addNouns(items[])
brain.addVerb(source, target, type, metadata?)
brain.addVerbs(items[])
brain.add(content, metadata)
brain.addNouns(items[]) // Batch operation - unchanged
brain.relate(source, target, type, metadata?)
brain.addVerbs(items[]) // Batch operation - unchanged
brain.search(query, options?)
brain.find(naturalLanguageQuery, options?) // Triple Intelligence
@ -138,7 +138,7 @@ brain.storage.vacuum()
const brain = new BrainyData()
await brain.init()
await brain.addNoun('My first document', NounType.Document)
await brain.add('My first document', { nounType: NounType.Document })
const results = await brain.search('document')
const similar = await brain.similar('text1', 'text2')
const groups = await brain.clusters()
@ -193,9 +193,9 @@ for await (const batch of brain.neural.clusterStream({ batchSize: 50 })) {
#### **1. Data-First Pattern**
```typescript
// Always: (data, type/config, optional_metadata)
brain.addNoun(content, NounType.Document, metadata?)
brain.addVerb(source, target, VerbType.RelatedTo, metadata?)
// Always: (data, config/metadata, optional_params)
brain.add(content, metadata) // nounType now in metadata
brain.relate(source, target, VerbType.RelatedTo, metadata?)
brain.search(query, options?)
brain.similar(a, b, options?)
```
@ -270,8 +270,8 @@ try {
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
const brain = new BrainyData()
await brain.addNoun('content', NounType.Document, { title: 'My Doc' })
// ^^^^^^^^^^^^^^^^ // IDE autocomplete!
await brain.add('content', { nounType: NounType.Document, title: 'My Doc' })
// ^^^^^^^^^^^^^^^^ // IDE autocomplete!
```
### **✅ 5. Flexible Configuration**
@ -306,7 +306,7 @@ const brain = new BrainyData({
* @param type - Relationship type (VerbType enum)
* @param metadata - Optional relationship metadata
*/
brain.addVerb(source, target, type, metadata?)
brain.relate(source, target, type, metadata?)
```
### **2. Error Context Enhancement**

16
docs/api/README.md
View file

@ -12,7 +12,7 @@ const brain = new BrainyData() // Zero config!
await brain.init()
// Add data (text auto-embeds!)
await brain.addNoun('The future of AI is here', 'content')
await brain.add('The future of AI is here', { nounType: 'content' })
// Search with Triple Intelligence
const results = await brain.find({
@ -295,7 +295,7 @@ Brainy uses its own clean, readable operators:
### Basic Usage
```typescript
// Add data
const id = await brain.addNoun('Quantum computing breakthrough', {
const id = await brain.add('Quantum computing breakthrough', {
category: 'technology',
year: 2024,
importance: 'high'
@ -322,14 +322,14 @@ const articles = await brain.find({
### Creating Knowledge Graphs
```typescript
// Add entities
const ai = await brain.addNoun('Artificial Intelligence', 'concept')
const ml = await brain.addNoun('Machine Learning', 'concept')
const dl = await brain.addNoun('Deep Learning', 'concept')
const ai = await brain.add('Artificial Intelligence', { nounType: 'concept' })
const ml = await brain.add('Machine Learning', { nounType: 'concept' })
const dl = await brain.add('Deep Learning', { nounType: 'concept' })
// Create relationships
await brain.addVerb(ml, ai, 'subset_of')
await brain.addVerb(dl, ml, 'subset_of')
await brain.addVerb(dl, ai, 'enables')
await brain.relate(ml, ai, 'subset_of')
await brain.relate(dl, ml, 'subset_of')
await brain.relate(dl, ai, 'enables')
// Traverse the graph
const aiEcosystem = await brain.find({