https://github.com/powersync-ja/sqlite-js
https://github.com/powersync-ja/sqlite-js
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/powersync-ja/sqlite-js
- Owner: powersync-ja
- Created: 2024-04-16T09:01:14.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-21T23:57:01.000Z (8 months ago)
- Last Synced: 2025-10-22T01:24:47.096Z (8 months ago)
- Language: TypeScript
- Size: 366 KB
- Stars: 3
- Watchers: 8
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# sqlite-js
Universal SQLite APIs for JavaScript.
The project provides two primary APIs:
1. The driver API. This aims to expose a minimum API for drivers to implement, while supporting a rich set of functionality. This should have as little as possible performance overhead, while still supporting asynchronous implementations.
2. The end-user API. This is a library built on top of the driver API, that exposes higher-level functionality such as transactions, convenience methods, template strings (later), pipelining.
## @sqlite-js/driver
This is a universal driver API and utilities for implementing drivers.
The APIs here are low-level. These are intended to be implemented by drivers, and used by higher-level libraries.
See [DRIVER-API.md](./DRIVER-API.md) for details on the design.
### @sqlite-js/driver/node
This is a driver implementation for NodeJS based on the experimental `node:sqlite` package.
## @sqlite-js/better-sqlite3-driver
This is a driver implementation for NodeJS implementation based `better-sqlite3`.
## @sqlite-js/api
This contains a higher-level API, with simple methods to execute queries, and supports transactions and pipelining.
This is largely a proof-of-concept to validate and test the underlying driver APIs, rather than having a fixed design.
The current iteration of the APIs is visible at [packages/api/src/api.ts](packages/api/src/api.ts).
# Why split the APIs?
A previous iteration used a single API for both the end-user API and the driver API. This had serveral disadvantages:
1. The implementation per driver requires a lot more effort.
2. Iterating on the API becomes much more difficult.
1. Implementing minor quality-of-life improvements for the end user becomes a required change in every driver.
3. Optimizing the end-user API for performance is difficult. To cover all the different use cases, it requires implementing many different features such as prepared statements, batching, pipelining. This becomes a very large API for drivers to implement.
4. The goals for the end-user API is different from the driver API:
1. End-users want a rich but simple-to-use API to access the database.
2. Drivers want a small surface area, that doesn't change often.
Splitting out a separate driver API, and implementing the end-user API as a separate library, avoids all the above issues.