[objarr] Update guides

Author: jamesgpearce

site/guides/01_the_basics/3_writing_to_stores.md

@@ -15,8 +15,8 @@ hierarchical structure:
 Once you have created a Store, you can write data to it with one of its setter
 methods, according to the level of the hierarchy that you want to set.
 
-For example, you can set the data for the keyed value structure of Store with the setValues
-method:
+For example, you can set the data for the keyed value structure of Store with
+the setValues method:
 
 ```js
 import {createStore} from 'tinybase';
@@ -25,8 +25,8 @@ const store = createStore();
 store.setValues({employees: 3, open: true});
 ```
 
-Similarly, you can set the data for the tabular structure of Store with the setTables
-method:
+Similarly, you can set the data for the tabular structure of Store with the
+setTables method:
 
 ```js
 store.setTables({pets: {fido: {species: 'dog'}}});
@@ -66,7 +66,9 @@ console.log(store.getTables());
 // -> {pets: {fido: {species: 'dog', color: 'brown'}}, species: {dog: {price: 5}, cat: {price: 4}}}
 ```
 
-The data in a Value or a Cell can be a string, a number, or a boolean type.
+The data in a Value or a Cell can be a string, a number, a boolean, or `null`.
+You can also store richer data as plain JavaScript objects or arrays, which
+TinyBase encodes internally as JSON strings.
 
 It's worth mentioning here that there are two extra methods to manipulate Row
 objects. The addRow method is like the setRow method but automatically assigns

site/guides/01_the_basics/8_tinybase_and_typescript.md

@@ -7,17 +7,18 @@ use with TinyBase.
 
 Out of the box, TinyBase has complete type coverage for all of its modules. So
 for example, setting and getting tabular and key-value data will obey the
-system's constraints. A Cell or a Value can only be a number, string, or
-boolean, for example:
+system's constraints. A Cell or a Value can be a number, string, boolean,
+`null`, or a plain JavaScript object or array, for example:
 
 ```ts yolo
 import {createStore} from 'tinybase';
 
 const store = createStore();
 
-store.setValues({employees: 3}); //                OK
-store.setValues({employees: true}); //             OK
-store.setValues({employees: ['Alice', 'Bob']}); // TypeScript error
+store.setValues({employees: 3}); //                  OK
+store.setValues({employees: true}); //               OK
+store.setValues({employees: ['Alice', 'Bob']}); //   OK since v8.0
+store.setValues({employees: () => 3}); //            TypeScript error
 ```
 
 This basic typing of the API is comprehensively described throughout in the API

site/guides/03_schemas/1_using_schemas.md

@@ -32,9 +32,11 @@ As you can see, when a Values object is used that doesn't quite match those
 constraints, the data is corrected. The `website` Value is ignored, and the
 missing `open` Value gets defaulted to `false`.
 
-TinyBase supports four primitive types: `string`, `number`, `boolean`, and
-`null`. You can also allow `null` values for a specific Cell or Value by adding
-the `allowNull` property:
+TinyBase supports four primitive types in schemas: `string`, `number`,
+`boolean`, and `null`. It also supports `object` and `array` types for richer
+structured data, which are stored internally as JSON-encoded strings. You can
+also allow `null` values for a specific Cell or Value by adding the `allowNull`
+property:
 
 ```js
 const store2 = createStore().setValuesSchema({
@@ -139,8 +141,8 @@ console.log(store.getTables());
 // -> {}
 ```
 
-When no longer needed, you can also completely removes existing schemas
-with the delValuesSchema method or the delTablesSchema method.
+When no longer needed, you can also completely removes existing schemas with the
+delValuesSchema method or the delTablesSchema method.
 
 ## Summary
 

site/guides/05_persistence/2_database_persistence.md

@@ -377,8 +377,11 @@ structure of your Store.
 ### SQL NULL is TinyBase null
 
 In TinyBase v7.0, `null` became a valid Cell and Value type alongside `string`,
-`number`, and `boolean`. When a database persister loads data from a SQL table,
-any SQL `NULL` values are loaded as TinyBase `null` values.
+`number`, and `boolean`. From v8.0, `object` and `array` types are also allowed;
+these are stored as JSON-encoded strings in SQL columns. When a database
+persister loads data from a SQL table, any SQL `NULL` values are loaded as
+TinyBase `null` values, and JSON-encoded columns are decoded back to objects or
+arrays.
 
 This is the natural and correct behavior: SQL `NULL` represents an explicit null
 value, which maps directly to TinyBase's `null` type.

src/@types/store/docs.js

@@ -112,8 +112,8 @@
  * `null` since v7.0, or `object` or `array` since v8.0), and what the default
  * value can be when an explicit value is not specified.
  *
- * For `object` and `array` types, TinyBase automatically serializes values
- * to and from JSON when storing and retrieving them.
+ * For `object` and `array` types, TinyBase automatically serializes values to
+ * and from JSON when storing and retrieving them.
  *
  * If a default value is provided (and its type is correct), you can be certain
  * that the Value will always be present in a Store.
@@ -289,7 +289,8 @@
  *
  * A Cell is used when setting a cell with the setCell method, and when getting
  * it back out again with the getCell method. A Cell is a JavaScript string,
- * number, boolean; or null since v7.0.
+ * number, boolean, or null (since v7.0), or a plain JavaScript object or array
+ * (since v8.0).
  * @example
  * ```js
  * import type {Cell} from 'tinybase';
@@ -335,7 +336,8 @@
  *
  * A Value is used when setting a value with the setValue method, and when
  * getting it back out again with the getValue method. A Value is a JavaScript
- * string, number, boolean; or null since v7.0.
+ * string, number, boolean, or null (since v7.0), or a plain JavaScript object
+ * or array (since v8.0).
  * @example
  * ```js
  * import type {Value} from 'tinybase';
@@ -1222,8 +1224,8 @@
  * transaction, primarily used so that you can indicate whether the transaction
  * should be rolled back.
  *
- * It provides both the old and new Values in a two-part array. These
- * describe the state of the changed Value in the Store at the _start_ of the
+ * It provides both the old and new Values in a two-part array. These describe
+ * the state of the changed Value in the Store at the _start_ of the
  * transaction, and by the _end_ of the transaction.
  *
  * Hence, an `undefined` value for the first item in the array means that the
@@ -1511,14 +1513,17 @@
  *
  * The keyed value support is best thought of as a flat JavaScript object. The
  * Store contains a number of Value objects, each with a unique ID, and which is
- * a string, boolean, number; or null since v7.0.
+ * a string, boolean, number, null (since v7.0), or a plain JavaScript object or
+ * array (since v8.0).
  *
  * ```json
- * {                  // Store
- *   "value1": "one",   // Value (string)
- *   "value2": true,    // Value (boolean)
- *   "value3": 3,       // Value (number)
- *   "value4": null,    // Value (null since v7.0)
+ * {                           // Store
+ *   "value1": "one",            // Value (string)
+ *   "value2": true,             // Value (boolean)
+ *   "value3": 3,                // Value (number)
+ *   "value4": null,             // Value (null since v7.0)
+ *   "value5": {"x": 1},         // Value (object since v8.0)
+ *   "value6": [1, 2, 3],        // Value (array since v8.0)
  *   ...
  * }
  * ```
@@ -1535,7 +1540,8 @@
  * - Each Table contains a number of Row objects.
  * - Each Row contains a number of Cell objects.
  *
- * A Cell is a string, boolean, number; or null since v7.0.
+ * A Cell is a string, boolean, number, null (since v7.0), or a plain JavaScript
+ * object or array (since v8.0).
  *
  * The members of each level of this hierarchy are identified with a unique Id
  * (which is a string). In other words you can naively think of a Store as a
@@ -1549,6 +1555,8 @@
  *       "cell2": true,        // Cell (boolean)
  *       "cell3": 3,           // Cell (number)
  *       "cell4": null,        // Cell (null since v7.0)
+ *       "cell5": {"x": 1},    // Cell (object since v8.0)
+ *       "cell6": [1, 2, 3],   // Cell (array since v8.0)
  *       ...
  *     },
  *     ...
@@ -3069,10 +3077,10 @@
    * does not match a TablesSchema associated with the Store), will be ignored
    * silently.
    *
-   * As well as string, number, or boolean Cell types, this method can also take
-   * a MapCell function that takes the current Cell value as a parameter and
-   * maps it. This is useful if you want to efficiently increment a value
-   * without fetching it first, for example.
+   * As well as string, number, boolean, null, object, and array Cell types,
+   * this method can also take a MapCell function that takes the current Cell
+   * value as a parameter and maps it. This is useful if you want to efficiently
+   * increment a value without fetching it first, for example.
    *
    * The method returns a reference to the Store so that subsequent operations
    * can be chained in a fluent style.
@@ -3234,10 +3242,10 @@
    * If the Value is invalid (either because of its type, or because it does not
    * match a ValuesSchema associated with the Store), will be ignored silently.
    *
-   * As well as string, number, or boolean Value types, this method can also
-   * take a MapValue function that takes the current Value as a parameter and
-   * maps it. This is useful if you want to efficiently increment a value
-   * without fetching it first, for example.
+   * As well as string, number, boolean, null, object, and array Value types,
+   * this method can also take a MapValue function that takes the current Value
+   * as a parameter and maps it. This is useful if you want to efficiently
+   * increment a value without fetching it first, for example.
    *
    * The method returns a reference to the Store so that subsequent operations
    * can be chained in a fluent style.