json-fs-query 3.3.0 → 3.4.0

package/README.md

@@ -137,7 +137,7 @@ that aren't nullable reject it.
 
 `useDefault: true, defaultValue: …` fills in a field that is left out. `create()` checks the default against the
 field's type (a `null` default needs `nullable: true`) and throws if it doesn't fit. Primary key fields can't be
-nullable. Each key needs a non-empty `fields` list naming defined fields, and unknown key properties are rejected.
+nullable, or optional unless they're `auto` (a row has to have its key: its file is named by it). Each key needs a non-empty `fields` list naming defined fields, and unknown key properties are rejected.
 As in SQL, a `null` is never a duplicate in a unique key (any number of rows can hold it), and
 a `null` foreign key isn't checked against the record it references.
 
@@ -457,7 +457,7 @@ A field is `<name> <type>`, then any of these, in any order:
 |---|---|
 | `optional` | may be left out (see "Fields" above) |
 | `null` / `not null` | may hold `null` / may not (the default) |
-| `auto` | a UUID is generated on insert; the type must be `string` |
+| `auto` | a UUID is generated on insert for a row that leaves the field out (or gives `null`); a value given for it is kept, as MySQL keeps an explicit `AUTO_INCREMENT` value, and still has to be unique when the field is a key. The type must be `string` |
 | `default <value>` | used when the field is left out: a string, a number, an array, `null`, `true` or `false` (so an `object` field can only default to `null` here; `create()` takes any default) |
 
 The types are `string`, `int`, `boolean`, `object` and `array`; any other is an error.
@@ -591,6 +591,12 @@ Queries that worked in 2.x can be errors now (each error names the problem), and
   can't be read`), as `drop` and `describe` already said, instead of `Could not read <name>.json`. A join written
   without the record to join (`read workouts on ...`) says so, instead of `Could not read .json`.
 
+### Upgrading from 3.3
+
+- An `auto` field keeps a value given for it on insert. Before 3.3.1, `insert foo values _id = 'mine', ...` stored the row
+  under a new UUID without a word, so copying rows with their ids (or migrating data whose other records point at those
+  ids) lost them. A row that leaves the field out, or gives `null`, still gets a new UUID.
+
 ## Configuration
 
 `configure()` sets where this package's data lives and how strictly it enforces foreign keys - call it once,
@@ -607,7 +613,8 @@ configure({
   format: 'compact',           // how files are written: 'compact' or 'pretty' (default 'compact')
   packedReads: undefined,      // use packed files (see packDatabase); default true in a browser, false in Node
   databasesPath: undefined,    // a folder holding several databases (see Several databases)
-  database: undefined          // the one of them in use
+  database: undefined,         // the one of them in use
+  fetchOptions: undefined      // passed to every fetch() in a browser, such as { cache: 'no-cache' }
 })
 ```
 
@@ -618,6 +625,11 @@ Reads fetch several entry files at once, `readConcurrency` at a time, and keep t
 file is one request: 16 suits HTTP/2 static hosts (such as GitHub Pages), while over HTTP/1.1 a browser only opens about
 6 connections per host anyway. `readConcurrency: 1` reads one file at a time, as every read did before this setting.
 
+`fetchOptions` is given to every `fetch()` a browser read makes, as its second argument. By default reads use the
+browser's normal HTTP cache, which suits data that only changes when the site is deployed. When something writes the
+files while the page is in use (a local server, say), `{ cache: 'no-cache' }` makes the browser check every file with the
+server before using its cached copy: an unchanged file comes back as a short "not modified", a changed one is read again.
+
 ### Several databases: `databasesPath`, `use`
 
 One program can keep several databases (say, real data and a test copy) in one folder and switch between them: