lucivy 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-2026 Luciform Research
+
+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

@@ -0,0 +1,147 @@
+# lucivy
+
+Fast BM25 full-text search for Node.js — with substring matching, fuzzy search, regex, and highlights. Powered by Rust via napi-rs.
+
+## Install
+
+```bash
+npm install lucivy
+```
+
+## Quick start
+
+```javascript
+const { Index } = require('lucivy');
+
+const index = Index.create('./my_index', [
+    { name: 'title', type: 'text' },
+    { name: 'body', type: 'text' },
+]);
+
+index.add(1, { title: 'Rust Programming', body: 'Systems programming with memory safety' });
+index.add(2, { title: 'Python Guide', body: 'Data science and web development' });
+index.commit();
+
+let results = index.search('programming', { highlights: true });
+for (const r of results) {
+    console.log(r.docId, r.score, r.highlights);
+}
+```
+
+## API
+
+### Create / open
+
+```javascript
+const index = Index.create('./my_index', [
+    { name: 'title', type: 'text' },
+    { name: 'body',  type: 'text' },
+    { name: 'tag',   type: 'keyword' },
+    { name: 'year',  type: 'i64', indexed: true, fast: true },
+]);
+
+const index2 = Index.open('./my_index');
+```
+
+### Add / update / delete
+
+```javascript
+index.add(1, { title: 'Hello', body: 'World' });
+index.addMany([
+    { docId: 2, title: 'Foo', body: 'Bar' },
+    { docId: 3, title: 'Baz', body: 'Qux' },
+]);
+index.update(1, { title: 'Updated', body: 'Content' });
+index.delete(2);
+index.commit();
+```
+
+### Search
+
+```javascript
+// String query — each word searched across all text fields (contains_split)
+let results = index.search('rust async programming');
+
+// Options
+results = index.search('rust', { limit: 20, highlights: true, allowedIds: [1, 3] });
+```
+
+#### contains — substring, fuzzy, regex (cross-token)
+
+Searches **stored text**, not individual tokens. Handles multi-word phrases, substrings, typos, and regex across token boundaries.
+
+```javascript
+// Substring — matches "programming", "programmer", etc.
+index.search({ type: 'contains', field: 'body', value: 'program' });
+
+// Multi-word phrase
+index.search({ type: 'contains', field: 'body', value: 'memory safety' });
+
+// Fuzzy (catches typos, distance=1 by default)
+index.search({ type: 'contains', field: 'body', value: 'programing languag', distance: 1 });
+
+// Regex on stored text
+index.search({ type: 'contains', field: 'body', value: 'program.*language', regex: true });
+```
+
+#### contains_split — one word = one contains query, OR'd together
+
+```javascript
+// "rust safety" → contains("rust") OR contains("safety") on body
+index.search({ type: 'contains_split', field: 'body', value: 'rust safety' });
+```
+
+#### boolean — combine queries with must / should / must_not
+
+```javascript
+index.search({
+    type: 'boolean',
+    must: [
+        { type: 'contains', field: 'body', value: 'rust' },
+    ],
+    should: [
+        { type: 'contains', field: 'title', value: 'guide' },
+    ],
+    must_not: [
+        { type: 'contains', field: 'body', value: 'deprecated' },
+    ],
+});
+```
+
+#### keyword / range — for non-text fields
+
+```javascript
+index.search({ type: 'keyword', field: 'tag', value: 'rust' });
+index.search({
+    type: 'contains', field: 'body', value: 'programming',
+    filters: [{ field: 'year', op: 'gte', value: 2023 }],
+});
+```
+
+### Snapshots (export / import)
+
+```javascript
+// Export to file
+index.exportSnapshotTo('./backup.luce');
+
+// Export to Buffer
+const buf = index.exportSnapshot();
+
+// Import from file
+const restored = Index.importSnapshotFrom('./backup.luce', './restored_index');
+
+// Import from Buffer
+const restored2 = Index.importSnapshot(buf, './restored_index');
+```
+
+### Properties
+
+```javascript
+index.numDocs   // number of documents
+index.path      // index directory path
+index.schema    // array of field definitions
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,68 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface SearchResult {
+  docId: number
+  score: number
+  highlights?: Record<string, Array<Array<number>>>
+}
+export interface FieldDef {
+  name: string
+  type: 'text' | 'string' | 'u64' | 'i64' | 'f64'
+  stored?: boolean
+  indexed?: boolean
+  fast?: boolean
+}
+export interface SearchOptions {
+  limit?: number
+  highlights?: boolean
+  allowedIds?: Array<number>
+}
+export declare class Index {
+  /** Create a new index at the given path. */
+  static create(path: string, fields: Array<FieldDef>, stemmer?: string | undefined | null): Index
+  /** Open an existing index at the given path. */
+  static open(path: string): Index
+  /** Add a document. `fields` is an object with field names as keys. */
+  add(docId: number, fields: Record<string, any>): void
+  /**
+   * Add multiple documents at once.
+   * Each element must have a `docId` key and field values.
+   */
+  addMany(docs: Array<Record<string, any>>): void
+  /** Delete a document by doc_id. */
+  delete(docId: number): void
+  /** Update a document (delete + re-add). */
+  update(docId: number, fields: Record<string, any>): void
+  /** Commit pending changes (makes added/deleted docs visible to searches). */
+  commit(): void
+  /** Rollback pending changes. */
+  rollback(): void
+  /**
+   * Search the index.
+   * `query` can be a string (contains_split on all text fields) or an object (QueryConfig).
+   */
+  search(query: any, options?: SearchOptions | undefined | null): Array<SearchResult>
+  /** Number of documents in the index. */
+  get numDocs(): number
+  /** Index path. */
+  get path(): string
+  /**
+   * Export this index as a LUCE snapshot (Buffer).
+   * Throws if there are uncommitted changes.
+   */
+  exportSnapshot(): Buffer
+  /** Export this index as a LUCE snapshot to a file. */
+  exportSnapshotTo(path: string): void
+  /**
+   * Import an index from a LUCE snapshot (Buffer).
+   * The snapshot must contain exactly one index.
+   */
+  static importSnapshot(data: Buffer, destPath?: string | undefined | null): Index
+  /** Import an index from a LUCE snapshot file. */
+  static importSnapshotFrom(path: string, destPath?: string | undefined | null): Index
+  /** Schema as a list of field definitions. */
+  get schema(): Array<FieldDef>
+}

package/index.js

@@ -0,0 +1,3 @@
+const { Index } = require('./lucivy.node');
+
+module.exports = { Index };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "lucivy",
+  "version": "0.1.0",
+  "description": "Fast BM25 full-text search with substring matching, fuzzy search, and regex — powered by Rust",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "Luciform Research",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/L-Defraiteur/lucivy"
+  },
+  "keywords": [
+    "search",
+    "full-text",
+    "bm25",
+    "fuzzy",
+    "substring",
+    "fts",
+    "tantivy",
+    "rust"
+  ],
+  "napi": {
+    "name": "lucivy",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lucivy.node",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0"
+  },
+  "scripts": {
+    "build": "napi build --release",
+    "build:debug": "napi build"
+  }
+}