synapse-db 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vesper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# 🗄️ synapse-db
+> **Universal Markdown-First & In-Memory Connectome Database for AI-Native Systems**  
+> Part of [Synapse Kit](https://github.com/minseokk77/synapse-kit) | Official Docs: [https://synapse.minseok.online](https://synapse.minseok.online)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Installation
+```bash
+bun add synapse-db
+# or
+npm install synapse-db
+```
+
+## Quick Start
+```typescript
+import { SynapseDB } from 'synapse-db';
+
+const db = new SynapseDB({
+  vaultDir: './vault',
+  autoWatch: true,
+});
+await db.init();
+
+const notes = db.collection<{ title: string; tags: string[] }>('notes');
+
+await notes.save({
+  id: 'arch-01',
+  data: { title: 'Synapse Architecture', tags: ['core', 'db'] },
+  body: '# Architecture\n\nConnected to [[notes/arch-02]].',
+});
+
+// O(1) lookup, bidirectional wikilink synapses, and Korean/English BM25 search
+const doc = notes.get('arch-01');
+const backlinks = notes.synapses('arch-02').incoming();
+const hits = notes.search('Architecture');
+
+// Export Connectome graph directly to Obsidian Canvas (.canvas)
+db.exportCanvas('./vault/connectome.canvas');
+```
+
+## Features
+- **Markdown-First Storage**: Lossless YAML Frontmatter + Markdown body persistence with atomic `.tmp` rename writes.
+- **In-Memory Connectome**: $O(1)$ hash lookup and automatic bidirectional `[[collection/id|alias]]` wikilink wiring with mathematically verified graph symmetry invariants.
+- **Korean 2-gram + English BM25 Search**: Zero-dependency inverted index with automatic ghost-token elimination on update/delete.
+- **Legacy Migrator**: Built-in `migrateFromSqlite` (with SQL injection identifier guard) and `migrateFromJsonArray`.
+- **Obsidian Canvas Exporter**: Generates interactive `.canvas` files for visual graph inspection in Obsidian.
+
+## License
+MIT

package/dist/canvasExporter.d.ts

@@ -0,0 +1,32 @@
+import type { SynapseConnectome } from "./connectome";
+export interface CanvasNode {
+    id: string;
+    type: "file" | "text";
+    file?: string;
+    text?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color?: string;
+}
+export interface CanvasEdge {
+    id: string;
+    fromNode: string;
+    toNode: string;
+    label?: string;
+    toEnd?: "arrow" | "none";
+}
+export interface CanvasData {
+    nodes: CanvasNode[];
+    edges: CanvasEdge[];
+}
+/**
+ * 시냅스 커넥톰을 옵시디언 .canvas 파일로 내보내기
+ */
+export declare function exportToObsidianCanvas(connectome: SynapseConnectome, targetFilePath: string, options?: {
+    nodeWidth?: number;
+    nodeHeight?: number;
+    horizontalGap?: number;
+    verticalGap?: number;
+}): CanvasData;

package/dist/collection.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 타입 세이프 컬렉션 인터페이스 (Synapse Collection)
+ * 개발자가 직관적으로 CRUD 및 시냅스 관계 탐색을 수행하는 퍼사드 계층
+ */
+import type { SynapseDocument, SynapseDocumentInput, SynapseQueryOptions, SynapseSearchResult } from "./types";
+import type { SynapseEngine } from "./engine";
+export declare class SynapseCollection<TData = Record<string, any>> {
+    readonly name: string;
+    private readonly engine;
+    constructor(name: string, engine: SynapseEngine);
+    /**
+     * 문서 저장 (메모리 커넥톰 즉각 반영 + 디스크 원자적 비동기 영속화)
+     */
+    save(input: SynapseDocumentInput<TData>): Promise<SynapseDocument<TData>>;
+    /**
+     * O(1) 단일 문서 조회
+     */
+    get(id: string): SynapseDocument<TData> | null;
+    /**
+     * 문서 존재 여부 확인
+     */
+    has(id: string): boolean;
+    /**
+     * 문서 삭제
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * 필터링, 정렬, 페이징 쿼리
+     */
+    query(options?: SynapseQueryOptions<TData>): SynapseDocument<TData>[];
+    /**
+     * 컬렉션 내 모든 문서 조회
+     */
+    all(): SynapseDocument<TData>[];
+    /**
+     * 컬렉션 내 문서 개수
+     */
+    count(): number;
+    /**
+     * 컬렉션 내 전문 검색 (BM25 랭킹)
+     */
+    search(queryText: string): SynapseSearchResult<TData>[];
+    /**
+     * 해당 문서의 시냅스 관계 순회 헬퍼
+     */
+    synapses(id: string): {
+        /** 이 문서에서 뻗어나가는 시냅스 연결 문서들 */
+        outgoing: (targetCollectionFilter?: string) => SynapseDocument[];
+        /** 이 문서를 참조하고 있는 시냅스 연결 문서들 */
+        incoming: (sourceCollectionFilter?: string) => SynapseDocument[];
+    };
+}

package/dist/connectome.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 범용 시냅스 커넥톰 (Universal Synapse Connectome)
+ * 인메모리 신경망 그래프, O(1) 해시 색인 및 초경량 한국어 전문 검색 엔진
+ */
+import type { SynapseDocument, SynapticEdge, SynapseQueryOptions, SynapseSearchResult, SynapseDBStats } from "./types";
+export declare class SynapseConnectome {
+    private readonly documents;
+    private readonly collectionDocIds;
+    private readonly outgoingEdges;
+    private readonly incomingEdges;
+    private readonly edgeMeta;
+    private readonly tokenInvertedIndex;
+    private readonly documentTokens;
+    constructor();
+    /**
+     * 고유 노드 ID 복합키 생성
+     */
+    static makeNodeId(collection: string, id: string): string;
+    /**
+     * 전체 메모리 상태 초기화
+     */
+    clear(): void;
+    /**
+     * 문서 적재 및 시냅스 간선/검색 색인 자동 결합 (Auto-Wiring)
+     */
+    putDocument(doc: SynapseDocument): void;
+    /**
+     * 문서 삭제
+     */
+    removeDocument(collection: string, id: string): boolean;
+    /**
+     * 해당 문서가 소유한 나가는 간선(Outgoing Edges)과 검색 역색인 토큰만 정리
+     */
+    private removeDocumentOwnedIndices;
+    /**
+     * O(1) 단일 문서 조회
+     */
+    getDocument<TData = any>(collection: string, id: string): SynapseDocument<TData> | null;
+    /**
+     * 해당 노드에서 뻗어나가는 시냅스 연결 노드 조회 (Outgoing Synapses)
+     */
+    getOutgoingDocuments(collection: string, id: string, targetCollectionFilter?: string): SynapseDocument[];
+    /**
+     * 해당 노드를 참조하고 있는 역방향 시냅스 연결 노드 조회 (Incoming Synapses)
+     */
+    getIncomingDocuments(collection: string, id: string, sourceCollectionFilter?: string): SynapseDocument[];
+    /**
+     * 그래프 양방향 대칭 불변식(Symmetry Invariant) 무결성 검증
+     * 모든 간선 (u -> v)에 대해 v in outgoing(u) <=> u in incoming(v) 성립 여부 확인
+     */
+    verifyGraphInvariants(): {
+        readonly ok: boolean;
+        readonly brokenOutgoing: string[];
+        readonly brokenIncoming: string[];
+        readonly ghostTokens: string[];
+    };
+    /**
+     * 모든 시냅스 간선 목록 반환 (시각화 및 캔버스 생성용)
+     */
+    getAllEdges(): SynapticEdge[];
+    /**
+     * 모든 등록된 문서 목록 반환
+     */
+    getAllDocuments(): SynapseDocument[];
+    /**
+     * 특정 컬렉션의 문서 목록 조회 (필터링, 정렬, 페이징 지원)
+     */
+    queryCollection<TData = any>(collection: string, options?: SynapseQueryOptions<TData>): SynapseDocument<TData>[];
+    /**
+     * 초경량 한국어/영어 전문 검색 (BM25 간이 스코어링)
+     */
+    search<TData = any>(query: string, collectionFilter?: string): SynapseSearchResult<TData>[];
+    /**
+     * 한국어 N-gram 및 영문/숫자 단어 토크나이저
+     */
+    private tokenize;
+    /**
+     * 문서 본문 및 메타데이터 색인 생성
+     */
+    private indexDocumentText;
+    /**
+     * 전체 통계 요약
+     */
+    getStats(): SynapseDBStats;
+}

package/dist/engine.d.ts

@@ -0,0 +1,59 @@
+import { SynapseConnectome } from "./connectome";
+import type { SynapseDBConfig, SynapseDocument, SynapseDocumentInput, SynapseDBStats } from "./types";
+export declare class SynapseEngine {
+    readonly vaultDir: string;
+    readonly connectome: SynapseConnectome;
+    readonly config: SynapseDBConfig;
+    private isInitialized;
+    private pendingWriteQueue;
+    private writeTimer;
+    private watcherDebounceTimer;
+    private internalWriteResetTimer;
+    private fileWatcher;
+    private isWritingInternally;
+    constructor(config: SynapseDBConfig);
+    /**
+     * 볼트 디렉터리 초기화 및 기존 마크다운 파일 전체 로드
+     */
+    init(): Promise<void>;
+    /**
+     * 볼트 내 모든 컬렉션과 마크다운 파일을 재스캔하여 커넥톰 구축
+     */
+    reloadVault(): void;
+    /**
+     * 단일 컬렉션 디렉터리 내 .md 파일들을 순회 로드
+     */
+    private loadCollectionDir;
+    /**
+     * 문서 저장 (인메모리 즉시 반영 + 디바운스 원자적 디스크 쓰기)
+     */
+    saveDocument<TData = Record<string, any>>(collection: string, input: SynapseDocumentInput<TData>): Promise<SynapseDocument<TData>>;
+    /**
+     * 내부 디스크 쓰기 플래그 설정 (워처 루프백 방지)
+     */
+    private markInternalWrite;
+    /**
+     * 문서 삭제
+     */
+    deleteDocument(collection: string, id: string): Promise<boolean>;
+    /**
+     * 비동기 디바운스 디스크 쓰기 예약
+     */
+    private scheduleWrite;
+    /**
+     * 대기 중인 모든 디스크 쓰기 일괄 실행
+     */
+    flushPendingWrites(): void;
+    /**
+     * 외부 마크다운 파일 수정 감시 (옵시디언 핫 리로드, 단일 디바운스 보장)
+     */
+    private startWatcher;
+    /**
+     * 전체 데이터베이스 상태 통계
+     */
+    getStats(): SynapseDBStats;
+    /**
+     * 자원 정리
+     */
+    close(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Synapse-DB 메인 진입점 (Universal Markdown-First & In-Memory Connectome Database)
+ * Part of Synapse Kit | AI-Native Unified Framework
+ */
+import { SynapseEngine } from "./engine";
+import { SynapseCollection } from "./collection";
+import { SynapseMigrator } from "./migrator";
+import { exportToObsidianCanvas, type CanvasData } from "./canvasExporter";
+import type { SynapseDBConfig, SynapseDBStats } from "./types";
+export declare class SynapseDB {
+    readonly engine: SynapseEngine;
+    private readonly collections;
+    constructor(config: SynapseDBConfig);
+    /**
+     * 데이터베이스 초기화 (볼트 스캔 및 인메모리 커넥톰 적재)
+     */
+    init(): Promise<void>;
+    /**
+     * 특정 컬렉션 획득 (타입 세이프)
+     */
+    collection<TData = Record<string, any>>(name: string): SynapseCollection<TData>;
+    /**
+     * 전체 시냅스 망을 옵시디언 캔버스(.canvas) 파일로 내보내기
+     */
+    exportCanvas(targetFilePath: string, options?: Parameters<typeof exportToObsidianCanvas>[2]): CanvasData;
+    /**
+     * SQLite / JSON 변환 마이그레이터 도구 인스턴스 생성
+     */
+    createMigrator(): SynapseMigrator;
+    /**
+     * 전체 데이터베이스 통계 요약
+     */
+    stats(): SynapseDBStats;
+    /**
+     * 대기 중인 모든 디스크 I/O 플러시
+     */
+    flush(): void;
+    /**
+     * 데이터베이스 종료 및 워처 해제
+     */
+    close(): void;
+}
+export * from "./types";
+export * from "./collection";
+export * from "./connectome";
+export * from "./serializer";
+export * from "./engine";
+export * from "./migrator";
+export * from "./canvasExporter";