quiverdb 0.13.1 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/sandbox-api.ts

@@ -104,12 +104,13 @@ midnight.
   binary chunk is refused). Integer division is the Lua 5.4 \`//\` operator — a language operator,
   unrelated to \`math\`. No \`io\` does **not** mean
   a data file on disk is out of reach: use \`db:read_csv\` / \`db:read_csv_stream\` for CSV or
-  \`db:read_xlsx\` / \`db:read_xlsx_stream\` for XLSX (see the file reading sections below).
+  \`db:read_xlsx\` / \`db:read_xlsx_stream\` for XLSX, and \`db:read_json\` for JSON
+  (see the file reading sections below).
   Never copy, paste, or re-type a data file's contents into
   the script as literals — read the file.
 - **Filesystem sandbox.** Every file-touching operation (\`db:export_csv\`, \`db:import_csv\`,
   \`db:open_file\`, \`db:bin_to_csv\`, \`db:csv_to_bin\`, \`db:validate_migrations\`, \`db:read_csv\`,
-  \`db:read_csv_stream\`, \`db:write_csv\`, \`db:read_xlsx\`, \`db:read_xlsx_stream\`,
+  \`db:read_csv_stream\`, \`db:write_csv\`, \`db:read_xlsx\`, \`db:read_xlsx_stream\`, \`db:read_json\`,
   \`save\` on a file or an expression) resolves
   relative paths against the directory containing the database file and rejects anything outside it
   (subdirectories are fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
@@ -327,10 +328,11 @@ Notes:
   \`{ x = nil }\` is identical to \`{}\`; an update/create table that ends up with no attributes
   **throws** (\`...must have at least one scalar attribute\` on create, \`...at least one attribute
   to update\` on update). To leave a column unchanged, omit the key — you cannot set a scalar to
-  NULL via the element table. (\`nil\` → NULL is accepted by \`update_relation\` and in query params
-  (not a trailing one), and as a cell in the group writers; \`upsert_time_series_row\` and
-  \`update_time_series_files\` replace the whole row, so a column you leave out (or set to \`nil\`,
-  the same thing) is cleared — see Time series and Time series files.)
+  NULL via the element table — nor via \`update_time_series_files\`, keyed by column name too,
+  where an omitted column keeps its current value. (\`nil\` → NULL is accepted by
+  \`update_relation\` and in query params (not a trailing one), and as a cell in the group writers;
+  \`upsert_time_series_row\` replaces the whole row, so a column you leave out (or set to \`nil\`,
+  the same thing) is cleared — see Time series.)
 - **\`update_relation\` points one scalar foreign-key relation at another element**, named by the
   target's label. The column is derived from the naming convention —
   \`lowercase(collection_to) .. "_" .. relation_type\`, so
@@ -559,15 +561,12 @@ singleton table):
 db:has_time_series_files(collection)              -- boolean
 db:list_time_series_files_columns(collection)     -- { "data_file", "metadata_file", ... }
 db:read_time_series_files(collection)             -- { data_file = "path", metadata_file = nil, ... }
-db:update_time_series_files(collection, { data_file = "path/to/data.bin" })  -- metadata_file is cleared
+db:update_time_series_files(collection, { data_file = "path/to/data.bin" })
 \`\`\`
 
-\`update_time_series_files\` **replaces the whole row**: every column you do not give a string is
-set to NULL (or to its DEFAULT, if the schema declares one), and in Lua a \`nil\` value and a
-missing key are the same thing. A table with no string values (\`{}\`, or only \`nil\` values)
-changes nothing and clears nothing. A value that is not a string throws. To change one path, read
-the row with \`db:read_time_series_files(collection)\`, change that one entry, and pass the whole
-table back.
+Only the columns you name are written, so the call above leaves \`metadata_file\` alone. A column
+cannot be cleared from Lua here: \`{ metadata_file = nil }\` is \`{}\`, which names nothing — so
+feeding a \`read_time_series_files\` result straight back in is a no-op.
 
 ---
 
@@ -791,6 +790,34 @@ end
 
 ---
 
+## JSON file reading
+
+Read one complete JSON document through the same filesystem sandbox as CSV/XLSX:
+
+\`\`\`lua
+local data = db:read_json("input.json")
+\`\`\`
+
+The root may be an object, array, string, number, boolean or null. Objects become tables with
+string keys; arrays use 1-based indices. Strings and booleans retain their native Lua types.
+Integers fitting signed 64-bit stay Lua integers; other finite numbers use Lua doubles, which
+can round large integers. Text must be UTF-8 (an initial UTF-8 BOM is accepted); there is no
+Latin-1 fallback. Standard strict JSON syntax applies: comments, trailing commas, extra roots,
+invalid Unicode and non-finite numbers are rejected. Duplicate object keys keep the last value.
+
+JSON null becomes \`nil\`. Null object fields disappear, and null array entries leave holes at
+their original indices; later entries are not shifted. Neither \`#\` nor \`ipairs\` supplies a
+reliable count for such arrays, and trailing null entries are invisible. Empty objects and
+arrays both become empty Lua tables. Returning these values uses the existing encoder: an
+empty table emits \`[]\`, and a sparse array emits an object such as \`{"2":10,"4":30}\`.
+
+The reader loads the whole document, with at most 64 MiB of input and nesting depth 32 (root
+depth 0). File, parse and limit failures carry \`Cannot read_json:\` and the requested path;
+parse failures include location information when available. The file is closed on success and
+failure. This reads values only; it does not import database rows or write the file.
+
+---
+
 ## XLSX file reading
 
 Read one worksheet of an XLSX workbook through the same filesystem sandbox as CSV. XLSX only: