tinybase 9.1.0-beta.0 → 9.1.0-beta.2

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

@@ -18,6 +18,7 @@ import type {
   IdOrNull,
   Ids,
   Json,
+  Sorter,
 } from '../common/index.d.ts';
 
 /**
@@ -60,11 +61,13 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * object or array Cell directly, and get back the same structure.
  *
  * 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.
+ * that that Cell will always be present in a Row. You can also set `required`
+ * to `true` to indicate to schema-based typing that the Cell should be present
+ * even if it does not have a default.
  *
- * If the default value is _not_ provided (or its type is incorrect), the Cell
- * may be missing from the Row, but when present you can be guaranteed it is of
- * the correct type.
+ * If neither a default value nor `required: true` is provided, the Cell may be
+ * missing from the Row, but when present you can be guaranteed it is of the
+ * correct type.
  * @example
  * When applied to a Store, this CellSchema ensures a boolean Cell is always
  * present, and defaults it to `false`.
@@ -78,6 +81,18 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * };
  * ```
  * @example
+ * When applied to a Store, this CellSchema expects a string Cell to be present
+ * without providing a default value.
+ *
+ * ```js
+ * import type {CellSchema} from 'tinybase';
+ *
+ * export const requiredString: CellSchema = {
+ *   type: 'string',
+ *   required: true,
+ * };
+ * ```
+ * @example
  * When applied to a Store, this CellSchema allows an object Cell containing
  * arbitrary data, defaulting to an empty object.
  *
@@ -93,11 +108,36 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * @since v1.0.0
  */
 export type CellSchema =
-  | {type: 'string'; default?: string | null; allowNull?: boolean}
-  | {type: 'number'; default?: number | null; allowNull?: boolean}
-  | {type: 'boolean'; default?: boolean | null; allowNull?: boolean}
-  | {type: 'object'; default?: AnyObject; allowNull?: boolean}
-  | {type: 'array'; default?: AnyArray; allowNull?: boolean};
+  | {
+      type: 'string';
+      default?: string | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'number';
+      default?: number | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'boolean';
+      default?: boolean | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'object';
+      default?: AnyObject;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'array';
+      default?: AnyArray;
+      allowNull?: boolean;
+      required?: boolean;
+    };
 
 /**
  * The ValuesSchema type describes the keyed Values that can be set in a Store
@@ -133,11 +173,13 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * 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.
+ * that the Value will always be present in a Store. You can also set `required`
+ * to `true` to indicate to schema-based typing that the Value should be
+ * present even if it does not have a default.
  *
- * If the default value is _not_ provided (or its type is incorrect), the Value
- * may not be present in the Store, but when present you can be guaranteed it is
- * of the correct type.
+ * If neither a default value nor `required: true` is provided, the Value may
+ * not be present in the Store, but when present you can be guaranteed it is of
+ * the correct type.
  * @example
  * When applied to a Store, this ValueSchema ensures a boolean Value is always
  * present, and defaults it to `false`.
@@ -151,6 +193,18 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * };
  * ```
  * @example
+ * When applied to a Store, this ValueSchema expects a string Value to be
+ * present without providing a default value.
+ *
+ * ```js
+ * import type {ValueSchema} from 'tinybase';
+ *
+ * export const requiredString: ValueSchema = {
+ *   type: 'string',
+ *   required: true,
+ * };
+ * ```
+ * @example
  * When applied to a Store, this ValueSchema allows an array Value containing
  * a list of items, defaulting to an empty array.
  *
@@ -166,11 +220,36 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * @since v3.0.0
  */
 export type ValueSchema =
-  | {type: 'string'; default?: string | null; allowNull?: boolean}
-  | {type: 'number'; default?: number | null; allowNull?: boolean}
-  | {type: 'boolean'; default?: boolean | null; allowNull?: boolean}
-  | {type: 'object'; default?: AnyObject; allowNull?: boolean}
-  | {type: 'array'; default?: AnyArray; allowNull?: boolean};
+  | {
+      type: 'string';
+      default?: string | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'number';
+      default?: number | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'boolean';
+      default?: boolean | null;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'object';
+      default?: AnyObject;
+      allowNull?: boolean;
+      required?: boolean;
+    }
+  | {
+      type: 'array';
+      default?: AnyArray;
+      allowNull?: boolean;
+      required?: boolean;
+    };
 
 /**
  * The NoTablesSchema type is a TablesSchema-like type for when one has not been
@@ -625,7 +704,7 @@ export type DoRollback = (store: Store) => boolean;
  * the getSortedRowIds method.
  *
  * It's an object containing the Id of the Table in the Store, and optional
- * `cellId`, `descending`, `offset`, and `limit` parameters. See the
+ * `cellId`, `descending`, `offset`, `limit`, and `sorter` parameters. See the
  * getSortedRowIds method for specific examples.
  * @category Store
  * @since v6.1.0
@@ -662,6 +741,13 @@ export type SortedRowIdsArgs = {
    * @since v6.1.0
    */
   limit?: number;
+  /**
+   * A custom function for comparing the sorting values, defaulting to the
+   * defaultSorter function.
+   * @category Argument
+   * @since v9.1.0
+   */
+  sorter?: Sorter;
 };
 
 /**
@@ -2196,10 +2282,11 @@ export interface Store {
    * The getSortedRowIds method returns the Ids of every Row in a given Table,
    * sorted according to the values in a specified Cell.
    *
-   * The sorting of the rows is alphanumeric, and you can indicate whether it
-   * should be in descending order. The `offset` and `limit` parameters are used
-   * to paginate results, but default to `0` and `undefined` to return all
-   * available Row Ids if not specified.
+   * By default the sorting of the rows is alphanumeric, and you can indicate
+   * whether it should be in descending order. The `offset` and `limit`
+   * parameters are used to paginate results, but default to `0` and
+   * `undefined` to return all available Row Ids if not specified. The `sorter`
+   * parameter can provide a custom comparison function.
    *
    * Note that every call to this method will perform the sorting afresh - there
    * is no caching of the results - and so you are advised to memoize the
@@ -2216,6 +2303,8 @@ export interface Store {
    * any.
    * @param limit The maximum number of Row Ids to return, or `undefined` for
    * all.
+   * @param sorter A custom function for comparing the sorting values, or
+   * `undefined` to use the defaultSorter function.
    * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
    * This example retrieves sorted Row Ids in a Table.
@@ -2287,6 +2376,24 @@ export interface Store {
    * // -> ['cujo', 'felix', 'fido']
    * ```
    * @example
+   * This example retrieves Row Ids sorted numerically by their own value.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * ['1', '10', '2'].forEach((rowId) =>
+   *   store.setRow('pets', rowId, {sold: false}),
+   * );
+   * const numericSorter = (sortKey1, sortKey2) =>
+   *   Number(sortKey1) - Number(sortKey2);
+   *
+   * console.log(
+   *   store.getSortedRowIds({tableId: 'pets', sorter: numericSorter}),
+   * );
+   * // -> ['1', '2', '10']
+   * ```
+   * @example
    * This example retrieves the sorted Row Ids of a Table that does not exist,
    * returning an empty array.
    *
@@ -2306,13 +2413,14 @@ export interface Store {
     descending?: boolean,
     offset?: number,
     limit?: number,
+    sorter?: Sorter,
   ): Ids;
 
   /**
    * When called with one object argument, the getSortedRowIds method
    * destructures it to make it easier to skip optional parameters.
    * @param args A SortedRowIdsArgs object containing the Id of the Table in the
-   * Store, and optional `cellId`, `descending`, `offset`, and `limit`
+   * Store, and optional `cellId`, `descending`, `offset`, `limit`, and `sorter`
    * parameters.
    * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
@@ -5813,7 +5921,7 @@ export interface Store {
    * addSortedRowIdsListener method destructures it to make it easier to skip
    * optional parameters.
    * @param args A SortedRowIdsArgs object containing the Id of the Table in the
-   * Store, and optional `cellId`, `descending`, `offset`, and `limit`
+   * Store, and optional `cellId`, `descending`, `offset`, `limit`, and `sorter`
    * parameters.
    * @param listener The function that will be called whenever the sorted Row
    * Ids in the Table change.

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

@@ -13,10 +13,12 @@
 import type {
   AllCellIdFromSchema,
   CellIdFromSchema,
-  DefaultCellIdFromSchema,
-  DefaultValueIdFromSchema,
   DefaultedCellFromSchema,
   DefaultedValueFromSchema,
+  PresentCellIdFromSchema,
+  PresentValueIdFromSchema,
+  RequiredNonDefaultCellIdFromSchema,
+  RequiredNonDefaultValueIdFromSchema,
   StoreAlias,
   TableIdFromSchema,
   Truncate,
@@ -29,6 +31,7 @@ import type {
   IdOrNull,
   Ids,
   Json,
+  Sorter,
 } from '../../common/with-schemas/index.d.ts';
 
 /**
@@ -71,11 +74,13 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * object or array Cell directly, and get back the same structure.
  *
  * 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.
+ * that that Cell will always be present in a Row. You can also set `required`
+ * to `true` to indicate to schema-based typing that the Cell should be present
+ * even if it does not have a default.
  *
- * If the default value is _not_ provided (or its type is incorrect), the Cell
- * may be missing from the Row, but when present you can be guaranteed it is of
- * the correct type.
+ * If neither a default value nor `required: true` is provided, the Cell may be
+ * missing from the Row, but when present you can be guaranteed it is of the
+ * correct type.
  * @example
  * When applied to a Store, this CellSchema ensures a boolean Cell is always
  * present, and defaults it to `false`.
@@ -89,6 +94,18 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  * };
  * ```
  * @example
+ * When applied to a Store, this CellSchema expects a string Cell to be present
+ * without providing a default value.
+ *
+ * ```js
+ * import type {CellSchema} from 'tinybase';
+ *
+ * export const requiredString: CellSchema = {
+ *   type: 'string',
+ *   required: true,
+ * };
+ * ```
+ * @example
  * When applied to a Store, this CellSchema allows an object Cell containing
  * arbitrary data, defaulting to an empty object.
  *
@@ -104,11 +121,11 @@ 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: 'object'; default?: AnyObject}
-  | {type: 'array'; default?: AnyArray};
+  | {type: 'string'; default?: string; required?: boolean}
+  | {type: 'number'; default?: number; required?: boolean}
+  | {type: 'boolean'; default?: boolean; required?: boolean}
+  | {type: 'object'; default?: AnyObject; required?: boolean}
+  | {type: 'array'; default?: AnyArray; required?: boolean};
 
 /**
  * The ValuesSchema type describes the keyed Values that can be set in a Store
@@ -144,11 +161,13 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * 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.
+ * that the Value will always be present in a Store. You can also set `required`
+ * to `true` to indicate to schema-based typing that the Value should be
+ * present even if it does not have a default.
  *
- * If the default value is _not_ provided (or its type is incorrect), the Value
- * may not be present in the Store, but when present you can be guaranteed it is
- * of the correct type.
+ * If neither a default value nor `required: true` is provided, the Value may
+ * not be present in the Store, but when present you can be guaranteed it is of
+ * the correct type.
  * @example
  * When applied to a Store, this ValueSchema ensures a boolean Value is always
  * present, and defaults it to `false`.
@@ -162,6 +181,18 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  * };
  * ```
  * @example
+ * When applied to a Store, this ValueSchema expects a string Value to be
+ * present without providing a default value.
+ *
+ * ```js
+ * import type {ValueSchema} from 'tinybase';
+ *
+ * export const requiredString: ValueSchema = {
+ *   type: 'string',
+ *   required: true,
+ * };
+ * ```
+ * @example
  * When applied to a Store, this ValueSchema allows an array Value containing
  * a list of items, defaulting to an empty array.
  *
@@ -177,11 +208,11 @@ 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: 'object'; default?: AnyObject}
-  | {type: 'array'; default?: AnyArray};
+  | {type: 'string'; default?: string; required?: boolean}
+  | {type: 'number'; default?: number; required?: boolean}
+  | {type: 'boolean'; default?: boolean; required?: boolean}
+  | {type: 'object'; default?: AnyObject; required?: boolean}
+  | {type: 'array'; default?: AnyArray; required?: boolean};
 
 /**
  * The NoTablesSchema type is a TablesSchema-like type for when one has not been
@@ -370,22 +401,40 @@ export type Row<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema>,
   WhenSet extends boolean = false,
-> = (WhenSet extends true
-  ? {
-      -readonly [CellId in DefaultCellIdFromSchema<Schema, TableId>]?: Cell<
-        Schema,
-        TableId,
-        CellId
-      >;
-    }
+> = WhenSet extends true
+  ? RequiredNonDefaultCellIdFromSchema<Schema, TableId> extends never
+    ? PartialRow<Schema, TableId>
+    : {
+        -readonly [
+          CellId in RequiredNonDefaultCellIdFromSchema<Schema, TableId>
+        ]: Cell<Schema, TableId, CellId>;
+      } & PartialRow<Schema, TableId>
   : {
-      -readonly [CellId in DefaultCellIdFromSchema<Schema, TableId>]: Cell<
+      -readonly [CellId in PresentCellIdFromSchema<Schema, TableId>]: Cell<
         Schema,
         TableId,
         CellId
       >;
-    }) & {
-  -readonly [CellId in DefaultCellIdFromSchema<Schema, TableId, false>]?: Cell<
+    } & {
+      -readonly [
+        CellId in PresentCellIdFromSchema<Schema, TableId, false>
+      ]?: Cell<Schema, TableId, CellId>;
+    };
+
+/**
+ * The PartialRow type is a Row-like type used when setting part of a row.
+ *
+ * In schema-based typing, a PartialRow allows any known Cell to be omitted,
+ * including Cells marked with `required: true`, while still preventing unknown
+ * Cell Ids from being used.
+ * @category Store
+ * @since v9.1.0
+ */
+export type PartialRow<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+> = {
+  -readonly [CellId in CellIdFromSchema<Schema, TableId>]?: Cell<
     Schema,
     TableId,
     CellId
@@ -479,23 +528,38 @@ export type CellOrUndefined<
 export type Values<
   Schema extends OptionalValuesSchema,
   WhenSet extends boolean = false,
-> = (WhenSet extends true
-  ? {
-      -readonly [ValueId in DefaultValueIdFromSchema<Schema>]?: Value<
+> = WhenSet extends true
+  ? RequiredNonDefaultValueIdFromSchema<Schema> extends never
+    ? PartialValues<Schema>
+    : {
+        -readonly [
+          ValueId in RequiredNonDefaultValueIdFromSchema<Schema>
+        ]: Value<Schema, ValueId>;
+      } & PartialValues<Schema>
+  : {
+      -readonly [ValueId in PresentValueIdFromSchema<Schema>]: Value<
         Schema,
         ValueId
       >;
-    }
-  : {
-      -readonly [ValueId in DefaultValueIdFromSchema<Schema>]: Value<
+    } & {
+      -readonly [ValueId in PresentValueIdFromSchema<Schema, false>]?: Value<
         Schema,
         ValueId
       >;
-    }) & {
-  -readonly [ValueId in DefaultValueIdFromSchema<Schema, false>]?: Value<
-    Schema,
-    ValueId
-  >;
+    };
+
+/**
+ * The PartialValues type is a Values-like type used when setting some keyed
+ * values.
+ *
+ * In schema-based typing, PartialValues allows any known Value to be omitted,
+ * including Values marked with `required: true`, while still preventing unknown
+ * Value Ids from being used.
+ * @category Store
+ * @since v9.1.0
+ */
+export type PartialValues<Schema extends OptionalValuesSchema> = {
+  -readonly [ValueId in ValueIdFromSchema<Schema>]?: Value<Schema, ValueId>;
 };
 
 /**
@@ -947,7 +1011,7 @@ export type DoRollback<Schemas extends OptionalSchemas> = (
  * the getSortedRowIds method.
  *
  * It's an object containing the Id of the Table in the Store, and optional
- * `cellId`, `descending`, `offset`, and `limit` parameters. See the
+ * `cellId`, `descending`, `offset`, `limit`, and `sorter` parameters. See the
  * getSortedRowIds method for specific examples.
  * @category Store
  * @since v6.1.0
@@ -989,6 +1053,13 @@ export type SortedRowIdsArgs<
    * @since v6.1.0
    */
   limit?: number;
+  /**
+   * A custom function for comparing the sorting values, defaulting to the
+   * defaultSorter function.
+   * @category Argument
+   * @since v9.1.0
+   */
+  sorter?: Sorter;
 };
 
 /**
@@ -3216,13 +3287,15 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *   descending?: boolean,
    *   offset?: number,
    *   limit?: number,
+   *   sorter?: Sorter,
    * ): Ids;
    * ```
    *
-   * The sorting of the rows is alphanumeric, and you can indicate whether it
-   * should be in descending order. The `offset` and `limit` parameters are used
-   * to paginate results, but default to `0` and `undefined` to return all
-   * available Row Ids if not specified.
+   * By default the sorting of the rows is alphanumeric, and you can indicate
+   * whether it should be in descending order. The `offset` and `limit`
+   * parameters are used to paginate results, but default to `0` and
+   * `undefined` to return all available Row Ids if not specified. The `sorter`
+   * parameter can provide a custom comparison function.
    *
    * Note that every call to this method will perform the sorting afresh - there
    * is no caching of the results - and so you are advised to memoize the
@@ -3239,6 +3312,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * any.
    * @param limit The maximum number of Row Ids to return, or `undefined` for
    * all.
+   * @param sorter A custom function for comparing the sorting values, or
+   * `undefined` to use the defaultSorter function.
    * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
    * This example retrieves sorted Row Ids in a Table.
@@ -3310,6 +3385,24 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * // -> ['cujo', 'felix', 'fido']
    * ```
    * @example
+   * This example retrieves Row Ids sorted numerically by their own value.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * ['1', '10', '2'].forEach((rowId) =>
+   *   store.setRow('pets', rowId, {sold: false}),
+   * );
+   * const numericSorter = (sortKey1, sortKey2) =>
+   *   Number(sortKey1) - Number(sortKey2);
+   *
+   * console.log(
+   *   store.getSortedRowIds({tableId: 'pets', sorter: numericSorter}),
+   * );
+   * // -> ['1', '2', '10']
+   * ```
+   * @example
    * This example retrieves the sorted Row Ids of a Table that does not exist,
    * returning an empty array.
    *
@@ -3329,13 +3422,14 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     descending?: boolean,
     offset?: number,
     limit?: number,
+    sorter?: Sorter,
   ): Ids;
 
   /**
    * When called with one object argument, the getSortedRowIds method
    * destructures it to make it easier to skip optional parameters.
    * @param args A SortedRowIdsArgs object containing the Id of the Table in the
-   * Store, and optional `cellId`, `descending`, `offset`, and `limit`
+   * Store, and optional `cellId`, `descending`, `offset`, `limit`, and `sorter`
    * parameters.
    * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
@@ -4512,7 +4606,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   setPartialRow<TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId,
     rowId: Id,
-    partialRow: Row<Schemas[0], TableId, true>,
+    partialRow: PartialRow<Schemas[0], TableId>,
   ): this;
 
   /**
@@ -4709,7 +4803,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * @category Setter
    * @since v3.0.0
    */
-  setPartialValues(partialValues: Values<Schemas[1], true>): this;
+  setPartialValues(partialValues: PartialValues<Schemas[1]>): this;
 
   /**
    * The setValue method sets a single keyed Value in the Store.
@@ -7295,7 +7389,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * addSortedRowIdsListener method destructures it to make it easier to skip
    * optional parameters.
    * @param args A SortedRowIdsArgs object containing the Id of the Table in the
-   * Store, and optional `cellId`, `descending`, `offset`, and `limit`
+   * Store, and optional `cellId`, `descending`, `offset`, `limit`, and `sorter`
    * parameters.
    * @param listener The function that will be called whenever the sorted Row
    * Ids in the Table change.