{"_id":"@alexbruf/turso-level","name":"@alexbruf/turso-level","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alexbruf/turso-level","version":"0.1.0","description":"An abstract-level database backed by Turso / libSQL","type":"module","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"dependencies":{"@libsql/client":"^0.14.0","abstract-level":"^1.0.4"},"devDependencies":{"typescript":"^5.4.0","vitest":"^3.2.4"},"publishConfig":{"access":"public"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/alexbruf/turso-level.git"},"homepage":"https://github.com/alexbruf/turso-level#readme","bugs":{"url":"https://github.com/alexbruf/turso-level/issues"},"keywords":["abstract-level","leveldb","turso","libsql","sqlite","serverless"],"_id":"@alexbruf/turso-level@0.1.0","gitHead":"57dc8ad0ce6d215913abac89ffb8edad53dd4838","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Wd4274JmydJuoN47BNtEpC7dZQht4rNMEkE52VTMuxJCIKcVwtzVa/Fr1DCNS9RDkfuKfJjfOsABzUb2nv9jeg==","shasum":"234ef44e70e0182cc191c8262c2197bef87833af","tarball":"https://registry.npmjs.org/@alexbruf/turso-level/-/turso-level-0.1.0.tgz","fileCount":18,"unpackedSize":43073,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alexbruf%2fturso-level@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD626eTZzE5BUvgsacGCQ6v4wCvbSsDLF22BT4g/k6SdAIgFduUh1vqDFO02KqcbSvt1RMaohmkFkfdyao8BPOMQUo="}]},"_npmUser":{"name":"alexbruf","email":"alex@brufsky.org"},"directories":{},"maintainers":[{"name":"alexbruf","email":"alex@brufsky.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/turso-level_0.1.0_1774546265579_0.6951561609039216"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-26T17:31:05.456Z","0.1.0":"2026-03-26T17:31:05.758Z","modified":"2026-03-26T17:31:06.168Z"},"maintainers":[{"name":"alexbruf","email":"alex@brufsky.org"}],"description":"An abstract-level database backed by Turso / libSQL","homepage":"https://github.com/alexbruf/turso-level#readme","keywords":["abstract-level","leveldb","turso","libsql","sqlite","serverless"],"repository":{"type":"git","url":"git+https://github.com/alexbruf/turso-level.git"},"bugs":{"url":"https://github.com/alexbruf/turso-level/issues"},"license":"Apache-2.0","readme":"# turso-level\n\nAn [`abstract-level`](https://github.com/Level/abstract-level) database backed by [Turso](https://turso.tech/) / [libSQL](https://github.com/tursodatabase/libsql).\n\nUse any library from the [`level`](https://github.com/Level/community) ecosystem on any serverless platform — Vercel, Netlify, Cloudflare Workers, Fly.io, Railway, or your own server.\n\n> 📌 New to `abstract-level`? Head over to the [Level FAQ](https://github.com/Level/community#faq).\n\n[![Tests](https://img.shields.io/badge/tests-876%20passing-brightgreen)](#tests)\n[![abstract-level](https://img.shields.io/badge/abstract--level-compliant-blue)](https://github.com/Level/abstract-level)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n\n## Install\n\n**Node.js:**\n```sh\nnpm install @alexbruf/turso-level @libsql/client\n```\n\n**Edge runtimes** (Cloudflare Workers, Vercel Edge, Netlify Edge):\n```sh\nnpm install @alexbruf/turso-level @tursodatabase/serverless\n```\n\n## Usage\n\n### Node.js\n\n```typescript\nimport { TursoLevel } from '@alexbruf/turso-level'\nimport { createClient } from '@libsql/client'\n\nconst client = createClient({\n  url: process.env.TURSO_DATABASE_URL,\n  authToken: process.env.TURSO_AUTH_TOKEN,\n})\n\nconst db = new TursoLevel({ client })\n\nawait db.put('hello', 'world')\nconst value = await db.get('hello') // 'world'\n\nfor await (const [key, value] of db.iterator({ gte: 'a', lte: 'z' })) {\n  console.log(key, value)\n}\n```\n\n### Edge runtimes (Cloudflare Workers, Vercel Edge, etc.)\n\n```typescript\nimport { TursoLevel } from '@alexbruf/turso-level'\nimport { createClient } from '@tursodatabase/serverless/compat'\n\nconst client = createClient({\n  url: process.env.TURSO_DATABASE_URL,\n  authToken: process.env.TURSO_AUTH_TOKEN,\n})\n\nconst db = new TursoLevel({ client })\n```\n\n### Local development (SQLite file)\n\n```typescript\nimport { TursoLevel } from '@alexbruf/turso-level'\nimport { createClient } from '@libsql/client'\n\nconst client = createClient({ url: 'file:local.db' })\nconst db = new TursoLevel({ client })\n```\n\n### Embedded replicas (Node.js — Fly.io, Railway, VPS)\n\nReads are local (microseconds). Writes go to the remote primary and sync back.\n\n```typescript\nimport { TursoLevel } from '@alexbruf/turso-level'\nimport { createClient } from '@libsql/client'\n\nconst client = createClient({\n  url: 'file:replica.db',\n  syncUrl: process.env.TURSO_DATABASE_URL,\n  authToken: process.env.TURSO_AUTH_TOKEN,\n  syncInterval: 60,\n})\n\nconst db = new TursoLevel({ client })\n```\n\n### With TinaCMS\n\n```typescript\n// tina/database.ts — Node.js / serverless (Vercel, Netlify, etc.)\nimport { TursoLevel } from '@alexbruf/turso-level'\nimport { createClient } from '@libsql/client'\nimport { createDatabase } from '@tinacms/datalayer'\nimport { GitHubProvider } from 'tinacms-gitprovider-github'\n\nconst client = createClient({\n  url: process.env.TURSO_DATABASE_URL,\n  authToken: process.env.TURSO_AUTH_TOKEN,\n})\n\nexport const database = createDatabase({\n  level: new TursoLevel({ client }),\n  gitProvider: new GitHubProvider({\n    owner: process.env.GITHUB_OWNER,\n    repo: process.env.GITHUB_REPO,\n    token: process.env.GITHUB_PERSONAL_ACCESS_TOKEN,\n    branch: process.env.GITHUB_BRANCH,\n  }),\n})\n```\n\n## Setup\n\n### Creating a Turso database\n\n```sh\n# Install CLI\nbrew install tursodatabase/tap/turso\n\n# Auth\nturso auth login\n\n# Create database\nturso db create my-db\n\n# Get connection details\nturso db show my-db --url\nturso db tokens create my-db\n```\n\nSet environment variables:\n\n```sh\nTURSO_DATABASE_URL=libsql://my-db-yourorg.turso.io\nTURSO_AUTH_TOKEN=eyJ...\n```\n\n### Table creation\n\nThe default `createTable: true` runs `CREATE TABLE IF NOT EXISTS` on open — no migrations needed for development.\n\nFor production, create the table explicitly:\n\n```sh\nturso db shell MY_DB \\\n  \"CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL) WITHOUT ROWID;\"\n```\n\nThen pass `createTable: false`:\n\n```typescript\nconst db = new TursoLevel({ client, createTable: false })\n```\n\n### Namespace (shared databases)\n\nUse `namespace` to isolate this adapter's table when sharing a database:\n\n```typescript\nconst db = new TursoLevel({ client, namespace: 'tina' })\n// → uses table \"tina_kv\" instead of \"kv\"\n```\n\n### Which package to use?\n\n| Runtime | Package | Import |\n|---------|---------|--------|\n| Node.js, Bun, Deno | `@libsql/client` | `@libsql/client` |\n| Cloudflare Workers, Vercel Edge, Netlify Edge | `@tursodatabase/serverless` | `@tursodatabase/serverless/compat` |\n\nBoth expose the same `createClient()` API — the adapter works identically with either.\n\n## API\n\n### `new TursoLevel(options)`\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `client` | `Client` | **required** | A `@libsql/client` instance from `createClient()` |\n| `namespace` | `string` | `''` | Table name prefix. `''` → table `kv`; `'tina'` → table `tina_kv` |\n| `createTable` | `boolean` | `true` | Run `CREATE TABLE IF NOT EXISTS` on open |\n\nAll other options are forwarded to [`abstract-level`](https://github.com/Level/abstract-level#db--new-abstractlevelmanifest-options).\n\n`TursoLevel` inherits the full `abstract-level` API: `put`, `get`, `del`, `getMany`, `batch`, `iterator`, `keys`, `values`, `clear`, `sublevel`, and more.\n\n## How it works\n\nTurso is libSQL (a SQLite fork) as a managed service. Entries are stored in a two-column table:\n\n```sql\nCREATE TABLE kv (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n) WITHOUT ROWID;\n```\n\n`WITHOUT ROWID` keeps the B-tree compact — the primary key IS the data, so there's no rowid indirection overhead.\n\n**Iteration** uses cursor-based pagination. Since libSQL's HTTP protocol is stateless, there's no persistent server-side cursor. The iterator fetches rows in pages of 100, using `WHERE key > lastKey` to advance between pages.\n\n**Batches** use libSQL's `client.batch()` with `'write'` mode, which executes all statements as a single atomic transaction.\n\n### Limitations\n\n- **No snapshot isolation** — iterators read live data. Declared via `supports.snapshots = false`.\n- **No `seek()`** — repositioning an open iterator is not implemented.\n- **UTF-8 keys and values only** — libSQL TEXT columns only.\n\n## Tests\n\n876 tests pass — the full [abstract-level compliance suite](https://github.com/Level/abstract-level/tree/main/test) runs against an in-memory libSQL database (no Turso account needed to run tests).\n\n```sh\nbun test\n```\n\n## License\n\n[Apache-2.0](LICENSE)\n","readmeFilename":"README.md","_rev":"1-290bc62ff1d6fcff8665ee2382b8fa5c"}