{"id":32103012,"url":"https://github.com/oxdev03/node-tantivy-binding","last_synced_at":"2025-10-20T03:37:52.055Z","repository":{"id":309975914,"uuid":"1037605110","full_name":"oxdev03/node-tantivy-binding","owner":"oxdev03","description":"Node.js bindings for Tantivy. Provides indexing, querying, and advanced search features with TypeScript support.","archived":false,"fork":false,"pushed_at":"2025-10-14T05:55:13.000Z","size":2837,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T04:11:28.360Z","etag":null,"topics":["document-search","indexing","lucene","napi-rs","nodejs","search","tantivy","typescript"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxdev03.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-13T20:43:06.000Z","updated_at":"2025-09-07T02:46:21.000Z","dependencies_parsed_at":"2025-08-31T22:13:14.889Z","dependency_job_id":"8027e95b-7c4e-4f41-b5da-c95dc31a52aa","html_url":"https://github.com/oxdev03/node-tantivy-binding","commit_stats":null,"previous_names":["oxdev03/node-tantivy-binding"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/oxdev03/node-tantivy-binding","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxdev03%2Fnode-tantivy-binding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxdev03%2Fnode-tantivy-binding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxdev03%2Fnode-tantivy-binding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxdev03%2Fnode-tantivy-binding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxdev03","download_url":"https://codeload.github.com/oxdev03/node-tantivy-binding/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxdev03%2Fnode-tantivy-binding/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279664278,"owners_count":26207466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-18T02:00:06.492Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-search","indexing","lucene","napi-rs","nodejs","search","tantivy","typescript"],"created_at":"2025-10-20T03:37:51.367Z","updated_at":"2025-10-20T03:37:52.048Z","avatar_url":"https://github.com/oxdev03.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-tantivy-binding\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nNode.js bindings for [Tantivy](https://github.com/quickwit-oss/tantivy), the full-text search engine library written in Rust.\n\nThis project is a Node.js port of [tantivy-py](https://github.com/quickwit-inc/tantivy-py), providing JavaScript/TypeScript bindings for the Tantivy search engine. The implementation closely follows the Python API to maintain consistency across language bindings.\n\n⚠️ **Note**: This is a first draft implementation ported from tantivy-py (see submodule hash). There may be unidentified bugs. The test suite is also based on tantivy-py. Furthermore not all future api changes will be reflected in this binding.\n\n# Installation\n\nThe bindings can be installed using npm:\n\n```bash\nnpm install @oxdev03-org/node-tantivy-binding\n```\n\nIf no binary is present for your operating system, the bindings will be built from source, which requires Rust to be installed.\n\n# Quick Start\n\nFor more detailed examples, see the [tutorials](./docs/tutorials.md).\n\n```javascript\nimport { SchemaBuilder, FieldType, Index, Document } from '@oxdev03-org/node-tantivy-binding'\n\n// Create a schema\nconst schema = new SchemaBuilder()\n  .addTextField('title', { stored: true })\n  .addTextField('body', { stored: true })\n  .build()\n\n// Create an index\nconst index = new Index(schema)\nconst writer = index.writer()\n\n// Add documents\nconst doc1 = new Document()\ndoc1.addText('title', 'The Old Man and the Sea')\ndoc1.addText('body', 'He was an old man who fished alone in a skiff in the Gulf Stream.')\nwriter.addDocument(doc1)\nwriter.commit()\n\n// Search\nconst searcher = index.searcher()\nconst query = index.parseQuery('sea', ['title', 'body'])\nconst results = searcher.search(query, 10)\n\nconsole.log('Found', results.hits.length, 'results')\n```\n\n# Features\n\nThis Node.js binding provides access to most of Tantivy's functionality:\n\n- **Full-text search** with BM25 scoring\n- **Structured queries** with boolean operations\n- **Faceted search** for filtering and aggregation\n- **Snippet generation** for search result highlighting\n- **Query explanation** for debugging relevance scoring\n- **Multiple field types**: text, integers, floats, dates, facets\n- **Flexible tokenization** and text analysis\n- **JSON document support**\n\n## API Compatibility\n\nThe API closely follows [tantivy-py](https://github.com/quickwit-inc/tantivy-py) to maintain consistency:\n\n- Same class names and method signatures where possible\n- Compatible document and query structures\n- Equivalent search result formats\n- Similar configuration options\n\n# Development\n\n## Requirements\n\n- Install the latest `Rust` (required for building from source)\n- Install `Node.js@22+` which fully supports `Node-API`\n- Install `yarn`\n\n## Building from Source\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd node-tantivy-binding-binding\n\n# Install dependencies\nnpm install\n\n# Build the native module\nnpm run build\n\n# Run tests\nnpm test\n```\n\n## Testing\n\nThe project includes a comprehensive test suite migrated from tantivy-py:\n\n```bash\nnpm test\n```\n\n## Project Status\n\nThis is a **first draft** port of tantivy-py to Node.js. While the core functionality works, please be aware:\n\n- ⚠️ **Potential bugs**: Some edge cases may not be handled correctly\n- 🔄 **API changes**: The API may evolve in future versions\n\n### Known Implementation Differences \u0026 TODOs\n\nThe Node.js implementation currently differs from the Python version in several ways. These are documented TODOs for future improvement:\n\n#### 🔴 Critical Validation Issues\n\n##### Numeric Field Validation (Too Lenient)\n\n**Current behavior**: Node.js version accepts invalid values that Python rejects\n**TODO**: Implement strict validation to match Python behavior\n\n```javascript\n// ❌ These currently PASS in Node.js but should FAIL:\nDocument.fromDict({ unsigned: -50 }, schema) // Should reject negative for unsigned\nDocument.fromDict({ signed: 50.4 }, schema) // Should reject float for integer\nDocument.fromDict({ unsigned: [1000, -50] }, schema) // Should reject arrays for single fields\n```\n\n##### Bytes Field Validation (Too Restrictive)\n\n**Current behavior**: Only accepts Buffer objects\n**TODO**: Support byte arrays like Python version\n\n```javascript\n// ❌ These currently FAIL in Node.js but should PASS:\nDocument.fromDict({ bytes: [1, 2, 3] }, schema) // Should accept byte arrays\nDocument.fromDict(\n  {\n    bytes: [\n      [1, 2, 3],\n      [4, 5, 6],\n    ],\n  },\n  schema,\n) // Should accept nested arrays\n```\n\n##### JSON Field Validation (Too Lenient)\n\n**Current behavior**: Accepts primitive types for JSON fields  \n**TODO**: Restrict to objects/arrays only\n\n```javascript\n// ❌ These currently PASS in Node.js but should FAIL:\nDocument.fromDict({ json: 123 }, schema) // Should reject numbers\nDocument.fromDict({ json: 'hello' }, schema) // Should reject strings\n```\n\n#### 🟠 Error Handling Differences\n\n##### Fast Field Configuration\n\n**Current**: Throws exception when field not configured as fast\n**Python**: Returns empty results\n**TODO**: Decide on consistent error handling approach\n\n##### Query Parser Errors\n\n**Current**: Different error message formats\n**TODO**: Align error messages with Python version\n\n#### 🔵 Type System Differences\n\n##### Date Handling\n\n**Current**: Uses getTime() timestamps\n**Python**: Uses datetime objects\n**TODO**: Consider more intuitive date API\n\n## Architecture\n\nBuilt with:\n\n- **[napi-rs](https://napi.rs/)**: For Node.js ↔ Rust bindings\n- **[Tantivy](https://github.com/quickwit-oss/tantivy)**: The underlying search engine\n- **TypeScript**: Full type definitions included\n- **Vitest**: For testing\n\n## Acknowledgments\n\nThis project is heavily inspired by and based on:\n\n- [tantivy-py](https://github.com/quickwit-inc/tantivy-py) - Python bindings for Tantivy\n- [Tantivy](https://github.com/quickwit-oss/tantivy) - The core search engine library\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxdev03%2Fnode-tantivy-binding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxdev03%2Fnode-tantivy-binding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxdev03%2Fnode-tantivy-binding/lists"}