qvdjs 2.0.6 → 2.2.0

package/README.md

@@ -67,11 +67,11 @@ when it loads a file. QVD is also QlikView's format, but QlikView is not part of
 
 → [Checked against Qlik Sense](https://qvdjs.ptarmiganlabs.com/v2.0/overview/checked-against-qlik-sense/)
 
-## Four ways to open a file
+## Six ways to open a file
 
 `fromQvd` is the general one, and often not the one you want. A QVD is an XML header, then a symbol
 table holding every distinct value, then a bit-packed index table of one code per cell. Two things
-separate the four calls: how far into the file a read has to go, and how much of it the read then
+separate these calls: how far into the file a read has to go, and how much of it the read then
 holds.
 
 | You want                                 | Call                                      | How far it reads, and what it holds                                  |
@@ -80,6 +80,8 @@ holds.
 | Rows from a file too large to hold       | `QvdDataFrame.iterate(path, {chunkSize})` | Everything, but holds two chunks — a 96 MB heap against 512 MB       |
 | A few columns of a large file            | `QvdColumnTable.fromQvd(path)`            | Everything, but stops before building rows — 141 MiB against 385 MiB |
 | Only the schema: names, row count, types | `QvdDataFrame.readMetadata(path)`         | The header alone. Constant cost, whatever the file's size            |
+| To know whether a read will fit first    | `QvdDataFrame.checkRead(path, options)`   | The header alone. Answers rather than reads; a read it approves is not refused for memory |
+| Pages, by position and in any order      | `QvdDataFrame.open(path, options)`        | The header once, then a page per call — `rows()`, `columns()`, a free `check()`, `close()` |
 
 ```javascript
 import {QvdDataFrame, QvdColumnTable} from 'qvdjs';
@@ -87,6 +89,14 @@ import {QvdDataFrame, QvdColumnTable} from 'qvdjs';
 // What is in this file? Costs the same whether it is 20 KB or 20 GB.
 const {columns, rowCount} = await QvdDataFrame.readMetadata('sales.qvd');
 
+// Will reading it fit? Also the header alone, and every suggestion it gives has been checked.
+const {fits, suggestions} = await QvdDataFrame.checkRead('sales.qvd');
+
+// Paging: the header is read once, and a page can be asked for by position, forwards or back.
+const qvd = await QvdDataFrame.open('sales.qvd');
+const page = await qvd.rows({offset: 5_000_000, limit: 100});
+await qvd.close();
+
 // Sum one column without ever building a row.
 const table = await QvdColumnTable.fromQvd('sales.qvd');
 let total = 0;
@@ -103,7 +113,7 @@ for await (const chunk of QvdDataFrame.iterate('sales.qvd', {chunkSize: 50_000})
 const df = await QvdDataFrame.fromQvd('sales.qvd');
 ```
 
-Reaching for `fromQvd` when you wanted one of the other three is the common mistake, and
+Reaching for `fromQvd` when you wanted one of the others is the common mistake, and
 `fromQvd(path, {maxRows: 0})` is **not** a substitute for `readMetadata`: it loads no rows but still
 parses the whole symbol table, which grows with the data.