json-fs-query 0.1.1 → 1.0.0

package/README.md

@@ -3,10 +3,12 @@
 Read and manage data with JSON files - a small query engine that treats a folder of JSON files as a database, with
 a SQL-like query string (`read workouts where date = '2024-06-02'`) instead of a query builder API.
 
-> **Pre-release.** The core engine (schema management plus a full read/insert/update/delete query language) is
-> implemented and tested. Still open: multi-field keys, a browser-safe build, and referential integrity on
-> delete/update (see the repository's issue tracker for details). Expect the public API below to stay stable, but
-> breaking changes are possible before a 1.0 release.
+The core engine (schema management, a full read/insert/update/delete query language, single- and multi-field key
+support, and referential integrity) is implemented and tested. Still open, tracked for whenever they're actually
+needed: multi-field *foreign* keys specifically (single-field ones work; composite primary/unique/index keys work
+too), and CASCADE/SET NULL modes for referential integrity (deleting/updating a referenced record is RESTRICTed -
+blocked outright - rather than cascading or nulling out the dependents; see `configure()` below to turn that
+enforcement off entirely if it doesn't fit your workflow).
 
 ## Install
 
@@ -35,8 +37,41 @@ await query("delete workouts where date = '2024-06-02'")
 await drop('workouts')
 ```
 
-This is a Node-only admin API today - `create`/`drop`/`query` all read and write real files on disk. A
-browser-safe read-only build is planned but not yet built (see the pre-release note above).
+## Configuration
+
+`configure()` sets where this package's data lives and how strictly it enforces foreign keys - call it once,
+before anything else:
+
+```js
+const { configure } = require('json-fs-query')
+
+configure({
+  databasePath: 'database/',   // where the JSON files live (default 'database/')
+  relativePath: '',            // URL prefix prepended to databasePath when reading via fetch() in a browser
+  enforceForeignKeys: true     // RESTRICT delete/update of a record other entities still reference (default true)
+})
+```
+
+Turning `enforceForeignKeys` off restores the pre-1.0 behavior (no referential integrity checks at all) - useful if
+it doesn't fit a particular workflow, mirroring MySQL's own toggleable `foreign_key_checks`.
+
+## In the browser
+
+A pre-built bundle is included (`browser/jsonFsQuery.js`, `.min.js` - also served directly via
+[unpkg](https://unpkg.com/json-fs-query) or [jsDelivr](https://cdn.jsdelivr.net/npm/json-fs-query)) and exposes the
+same functions as a global:
+
+```html
+<script src="https://unpkg.com/json-fs-query"></script>
+<script>
+  jsonFsQuery.configure({ databasePath: 'database/', relativePath: 'https://example.com/' })
+  jsonFsQuery.query("read workouts where date = '2024-06-02'").then(console.log)
+</script>
+```
+
+Reads work in the browser via `fetch()` - `create`/`drop`, and any write through `query()` (`insert`/`update`/
+`delete`), need real filesystem access and only work in Node. They're still present in the browser build (same
+public API either way), but throw if actually called there, rather than being silently unavailable.
 
 ## Documentation