tinybase 7.0.0-beta.2 → 7.0.0

package/@types/common/index.d.ts

@@ -65,7 +65,7 @@ export type Callback = () => void;
  * @category Parameter
  * @since v1.0.0
  */
-export type SortKey = string | number | boolean;
+export type SortKey = string | number | boolean | null;
 
 /**
  * The GetNow type is used to represent a function that returns the current time

package/@types/mergeable-store/index.d.ts

@@ -887,7 +887,7 @@ export interface MergeableStore extends Store {
    *
    * store.applyMergeableChanges([
    *   [{pets: [{fido: [{color: ['black', 'Nn1JUF----2FnHIC']}]}]}],
-   *   [{open: [null, 'Nn1JUF----3FnHIC']}],
+   *   [{open: [undefined, 'Nn1JUF----3FnHIC']}],
    *   1,
    * ]);
    * console.log(store.getTables());

package/@types/mergeable-store/with-schemas/index.d.ts

@@ -1149,7 +1149,7 @@ export interface MergeableStore<
    *
    * store.applyMergeableChanges([
    *   [{pets: [{fido: [{color: ['black', 'Nn1JUF----2FnHIC']}]}]}],
-   *   [{open: [null, 'Nn1JUF----3FnHIC']}],
+   *   [{open: [undefined, 'Nn1JUF----3FnHIC']}],
    *   1,
    * ]);
    * console.log(store.getTables());

package/@types/persisters/persister-cr-sqlite-wasm/index.d.ts

@@ -75,6 +75,10 @@ export interface CrSqliteWasmPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param db The database instance that was returned from `crSqlite3.open(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-cr-sqlite-wasm/with-schemas/index.d.ts

@@ -95,6 +95,10 @@ export interface CrSqliteWasmPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param db The database instance that was returned from `crSqlite3.open(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-durable-object-sql-storage/index.d.ts

@@ -233,6 +233,10 @@ export interface DurableObjectSqlStoragePersister extends Persister<Persists.Mer
  * See the documentation for the DpcJson, DpcFragmented, and DpcTabular types
  * for more information on how all of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * As well as providing a reference to the Store or MergeableStore to persist,
  * you must provide a `sqlStorage` parameter which identifies the Durable Object
  * SQLite storage to persist it to.

package/@types/persisters/persister-durable-object-sql-storage/with-schemas/index.d.ts

@@ -263,6 +263,10 @@ export interface DurableObjectSqlStoragePersister<
  * See the documentation for the DpcJson, DpcFragmented, and DpcTabular types
  * for more information on how all of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * As well as providing a reference to the Store or MergeableStore to persist,
  * you must provide a `sqlStorage` parameter which identifies the Durable Object
  * SQLite storage to persist it to.

package/@types/persisters/persister-electric-sql/index.d.ts

@@ -83,6 +83,10 @@ export interface ElectricSqlPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param electricClient The Electric client that was returned from `await
  * electrify(...)`.

package/@types/persisters/persister-electric-sql/with-schemas/index.d.ts

@@ -103,6 +103,10 @@ export interface ElectricSqlPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param electricClient The Electric client that was returned from `await
  * electrify(...)`.

package/@types/persisters/persister-expo-sqlite/index.d.ts

@@ -86,6 +86,10 @@ export interface ExpoSqlitePersister extends Persister<Persists.StoreOrMergeable
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.

package/@types/persisters/persister-expo-sqlite/with-schemas/index.d.ts

@@ -107,6 +107,10 @@ export interface ExpoSqlitePersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.

package/@types/persisters/persister-libsql/index.d.ts

@@ -74,6 +74,10 @@ export interface LibSqlPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param client The database client that was returned from `createClient(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-libsql/with-schemas/index.d.ts

@@ -94,6 +94,10 @@ export interface LibSqlPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param client The database client that was returned from `createClient(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-pglite/index.d.ts

@@ -81,7 +81,11 @@ export interface PglitePersister extends Persister<Persists.StoreOrMergeableStor
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
- * This method is asynchronous because it will await the creation of dedicated
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
+ * This method is asynchronous because it will await the completion of the
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.
  * @param store The Store or MergeableStore to persist.

package/@types/persisters/persister-pglite/with-schemas/index.d.ts

@@ -102,7 +102,11 @@ export interface PglitePersister<
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
- * This method is asynchronous because it will await the creation of dedicated
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
+ * This method is asynchronous because it will await the completion of the
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.
  * @param store The Store or MergeableStore to persist.

package/@types/persisters/persister-postgres/index.d.ts

@@ -77,6 +77,10 @@ export interface PostgresPersister extends Persister<Persists.StoreOrMergeableSt
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * This method is asynchronous because it will await the creation of dedicated
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.

package/@types/persisters/persister-postgres/with-schemas/index.d.ts

@@ -98,6 +98,10 @@ export interface PostgresPersister<
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
  *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
  * This method is asynchronous because it will await the creation of dedicated
  * new connections to the database. You will need to `await` a call to this
  * function or handle the return type natively as a Promise.

package/@types/persisters/persister-powersync/index.d.ts

@@ -76,6 +76,10 @@ export interface PowerSyncPersister extends Persister {
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param powerSync The PowerSync instance.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-powersync/with-schemas/index.d.ts

@@ -96,6 +96,10 @@ export interface PowerSyncPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store to persist.
  * @param powerSync The PowerSync instance.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-react-native-sqlite/index.d.ts

@@ -87,6 +87,10 @@ export interface ReactNativeSqlitePersister extends Persister<Persists.StoreOrMe
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `await SQLite.openDatabase(...)`.

package/@types/persisters/persister-react-native-sqlite/with-schemas/index.d.ts

@@ -108,6 +108,10 @@ export interface ReactNativeSqlitePersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `await SQLite.openDatabase(...)`.

package/@types/persisters/persister-sqlite-bun/index.d.ts

@@ -76,6 +76,10 @@ export interface SqliteBunPersister extends Persister<Persists.StoreOrMergeableS
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from `new Database(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-sqlite-bun/with-schemas/index.d.ts

@@ -97,6 +97,10 @@ export interface SqliteBunPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from `new Database(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

package/@types/persisters/persister-sqlite-wasm/index.d.ts

@@ -82,6 +82,10 @@ export interface SqliteWasmPersister extends Persister<Persists.StoreOrMergeable
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param sqlite3 The WASM module that was returned from `sqlite3InitModule`.
  * @param db The database instance that was returned from `new

package/@types/persisters/persister-sqlite-wasm/with-schemas/index.d.ts

@@ -104,6 +104,10 @@ export interface SqliteWasmPersister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param sqlite3 The WASM module that was returned from `sqlite3InitModule`.
  * @param db The database instance that was returned from `new

package/@types/persisters/persister-sqlite3/index.d.ts

@@ -76,6 +76,10 @@ export interface Sqlite3Persister extends Persister<Persists.StoreOrMergeableSto
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from `new
  * sqlite3.Database(...)`.

package/@types/persisters/persister-sqlite3/with-schemas/index.d.ts

@@ -97,6 +97,10 @@ export interface Sqlite3Persister<
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
  * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from `new
  * sqlite3.Database(...)`.

package/@types/queries/index.d.ts

@@ -77,7 +77,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * @category Result
  * @since v2.0.0
  */
-export type ResultCell = string | number | boolean;
+export type ResultCell = string | number | boolean | null;
 
 /**
  * The ResultCellOrUndefined type is the data structure representing a single

package/@types/store/index.d.ts

@@ -44,9 +44,9 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * The CellSchema type describes what values are allowed for each Cell in a
  * Table.
  *
- * A CellSchema specifies the type of the Cell (`string`, `boolean`, or
- * `number`), and what the default value can be when an explicit value is not
- * specified.
+ * A CellSchema specifies the type of the Cell (`string`, `boolean`, `number`;
+ * or `null`, since v7.0), and what the default value can be when an explicit
+ * value is not specified.
  *
  * If a default value is provided (and its type is correct), you can be certain
  * that that Cell will always be present in a Row.
@@ -70,9 +70,9 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * @since v1.0.0
  */
 export type CellSchema =
-  | {type: 'string'; default?: string}
-  | {type: 'number'; default?: number}
-  | {type: 'boolean'; default?: boolean};
+  | {type: 'string'; default?: string | null; allowNull?: boolean}
+  | {type: 'number'; default?: number | null; allowNull?: boolean}
+  | {type: 'boolean'; default?: boolean | null; allowNull?: boolean};
 
 /**
  * The ValuesSchema type describes the keyed Values that can be set in a Store
@@ -100,9 +100,9 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * The ValueSchema type describes what values are allowed for keyed Values in a
  * Store.
  *
- * A ValueSchema specifies the type of the Value (`string`, `boolean`, or
- * `number`), and what the default value can be when an explicit value is not
- * specified.
+ * A ValueSchema specifies the type of the Value (`string`, `boolean`, `number`;
+ * or `null` since v7.0), and what the default value can be when an explicit
+ * value is not specified.
  *
  * 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.
@@ -126,9 +126,9 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * @since v3.0.0
  */
 export type ValueSchema =
-  | {type: 'string'; default?: string}
-  | {type: 'number'; default?: number}
-  | {type: 'boolean'; default?: boolean};
+  | {type: 'string'; default?: string | null; allowNull?: boolean}
+  | {type: 'number'; default?: number | null; allowNull?: boolean}
+  | {type: 'boolean'; default?: boolean | null; allowNull?: boolean};
 
 /**
  * The NoTablesSchema type is a TablesSchema-like type for when one has not been
@@ -280,7 +280,7 @@ export type Row = {[cellId: Id]: Cell};
  *
  * 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, or boolean.
+ * number, boolean; or null since v7.0.
  * @example
  * ```js
  * import type {Cell} from 'tinybase';
@@ -290,7 +290,7 @@ export type Row = {[cellId: Id]: Cell};
  * @category Store
  * @since v1.0.0
  */
-export type Cell = string | number | boolean;
+export type Cell = string | number | boolean | null;
 
 /**
  * The CellOrUndefined type is a data structure representing the data in a
@@ -329,7 +329,7 @@ export type Values = {[valueId: Id]: Value};
  *
  * 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, or boolean.
+ * string, number, boolean; or null since v7.0.
  * @example
  * ```js
  * import type {Value} from 'tinybase';
@@ -339,7 +339,7 @@ export type Values = {[valueId: Id]: Value};
  * @category Store
  * @since v3.0.0
  */
-export type Value = string | number | boolean;
+export type Value = string | number | boolean | null;
 
 /**
  * The ValueOrUndefined type is a data structure representing the data in a
@@ -1704,13 +1704,14 @@ export type StoreListenerStats = {
  *
  * 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, or number.
+ * a string, boolean, number; or null since v7.0.
  *
  * ```json
  * {                  // Store
  *   "value1": "one",   // Value (string)
  *   "value2": true,    // Value (boolean)
  *   "value3": 3,       // Value (number)
+ *   "value4": null,    // Value (null since v7.0)
  *   ...
  * }
  * ```
@@ -1727,7 +1728,7 @@ export type StoreListenerStats = {
  * - Each Table contains a number of Row objects.
  * - Each Row contains a number of Cell objects.
  *
- * A Cell is a string, boolean, or number value.
+ * A Cell is a string, boolean, number; or null since v7.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
@@ -1740,6 +1741,7 @@ export type StoreListenerStats = {
  *       "cell1": "one",       // Cell (string)
  *       "cell2": true,        // Cell (boolean)
  *       "cell3": 3,           // Cell (number)
+ *       "cell4": null,        // Cell (null since v7.0)
  *       ...
  *     },
  *     ...
@@ -3547,7 +3549,7 @@ export interface Store {
    *   .setTables({pets: {fido: {species: 'dog', color: 'brown'}}})
    *   .setValues({open: true});
    *
-   * store.applyChanges([{pets: {fido: {color: 'black'}}}, {open: null}]);
+   * store.applyChanges([{pets: {fido: {color: 'black'}}}, {open: undefined}]);
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog', color: 'black'}}}
    * console.log(store.getValues());

package/@types/store/with-schemas/index.d.ts

@@ -60,9 +60,9 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * The CellSchema type describes what values are allowed for each Cell in a
  * Table.
  *
- * A CellSchema specifies the type of the Cell (`string`, `boolean`, or
- * `number`), and what the default value can be when an explicit value is not
- * specified.
+ * A CellSchema specifies the type of the Cell (`string`, `boolean`, `number`;
+ * or `null`, since v7.0), and what the default value can be when an explicit
+ * value is not specified.
  *
  * If a default value is provided (and its type is correct), you can be certain
  * that that Cell will always be present in a Row.
@@ -116,9 +116,9 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * The ValueSchema type describes what values are allowed for keyed Values in a
  * Store.
  *
- * A ValueSchema specifies the type of the Value (`string`, `boolean`, or
- * `number`), and what the default value can be when an explicit value is not
- * specified.
+ * A ValueSchema specifies the type of the Value (`string`, `boolean`, `number`;
+ * or `null` since v7.0), and what the default value can be when an explicit
+ * value is not specified.
  *
  * 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.
@@ -361,12 +361,12 @@ export type Row<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * string | number | boolean;
+ * string | number | boolean | null;
  * ```
  *
  * 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, or boolean.
+ * number, boolean; or null since v7.0.
  * @example
  * ```js
  * import type {Cell} from 'tinybase';
@@ -463,12 +463,12 @@ export type Values<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * string | number | boolean;
+ * string | number | boolean | null;
  * ```
  *
  * 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, or boolean.
+ * string, number, boolean; or null since v7.0.
  * @example
  * ```js
  * import type {Value} from 'tinybase';
@@ -2675,13 +2675,14 @@ export type StoreListenerStats = {
  *
  * 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, or number.
+ * a string, boolean, number; or null since v7.0.
  *
  * ```json
  * {                  // Store
  *   "value1": "one",   // Value (string)
  *   "value2": true,    // Value (boolean)
  *   "value3": 3,       // Value (number)
+ *   "value4": null,    // Value (null since v7.0)
  *   ...
  * }
  * ```
@@ -2698,7 +2699,7 @@ export type StoreListenerStats = {
  * - Each Table contains a number of Row objects.
  * - Each Row contains a number of Cell objects.
  *
- * A Cell is a string, boolean, or number value.
+ * A Cell is a string, boolean, number; or null since v7.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
@@ -2711,6 +2712,7 @@ export type StoreListenerStats = {
  *       "cell1": "one",       // Cell (string)
  *       "cell2": true,        // Cell (boolean)
  *       "cell3": 3,           // Cell (number)
+ *       "cell4": null,        // Cell (null since v7.0)
  *       ...
  *     },
  *     ...
@@ -4767,7 +4769,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *   .setTables({pets: {fido: {species: 'dog', color: 'brown'}}})
    *   .setValues({open: true});
    *
-   * store.applyChanges([{pets: {fido: {color: 'black'}}}, {open: null}]);
+   * store.applyChanges([{pets: {fido: {color: 'black'}}}, {open: undefined}]);
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog', color: 'black'}}}
    * console.log(store.getValues());

package/agents.md

@@ -279,3 +279,65 @@ for consistency and tree-shaking. Always use factory functions (`createStore`,
 `createIndexes`, etc.) with builder pattern chaining. Maintain 100% test
 coverage and follow the strict 80-character line length. See
 `.github/copilot-instructions.md` for detailed coding patterns.
+
+## Documentation System
+
+TinyBase has a sophisticated documentation system that generates the website
+from source code and markdown files.
+
+### Documentation Structure
+
+1. **Type Definitions (`src/@types/*/`)**: TypeScript `.d.ts` files contain the
+   API type definitions. **Never add comments directly to `.d.ts` files**.
+
+2. **Documentation Files (`src/@types/*/docs.js`)**: Companion `docs.js` files
+   sit alongside `.d.ts` files. Use `///` convention to document types and
+   functions. These are stitched together at build time to generate
+   documentation.
+
+3. **Guide Files (`site/guides/*/*.md`)**: Markdown files in the `site/guides/`
+   directory, organized by topic (basics, schemas, persistence, etc.). These are
+   source files for guides on the website.
+
+4. **Generated Files**: `/releases.md` and `/readme.md` in the root are
+   **GENERATED** from `/site/guides/16_releases.md` and `/site/home/index.md`.
+   **Never edit the generated files directly**.
+
+### Documentation Testing
+
+TinyBase has automated tests that validate all inline code examples in
+documentation:
+
+```bash
+npx vitest run ./test/unit/documentation.test.ts --retry=0
+```
+
+**How it works**:
+
+- Extracts all code blocks from markdown files and `docs.js` files
+- Concatenates all examples from each file together
+- Parses and executes them to ensure they work
+- This means examples in the same file share scope
+
+**Critical constraints**:
+
+- Don't redeclare variables across examples in the same file
+- First example can declare `const store = createStore()`, subsequent examples
+  reuse it
+- Include necessary imports in examples that use them
+- Avoid async operations in examples unless necessary
+- Keep examples simple and focused
+
+**Common pitfalls**:
+
+- ❌ Declaring `const store` multiple times in the same file
+- ❌ Using undefined functions (forgot import statement)
+- ✅ First example: `const store = createStore()`
+- ✅ Later examples: `store.setCell(...)` (reuses existing store)
+
+### Adding New Documentation
+
+1. **API Documentation**: Edit `docs.js` file next to the type definition
+2. **Guide Content**: Edit markdown files in `/site/guides/`
+3. **Release Notes**: Edit `/site/guides/16_releases.md` (not `/releases.md`)
+4. **Always run documentation tests** after changes to verify examples work