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

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

@@ -33,6 +33,53 @@ export type DefaultCellIdFromSchema<
   }[CellIdFromSchema<Schema, TableId>]
 >;
 
+export type RequiredCellIdFromSchema<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  IsRequired extends boolean = true,
+> = AsId<
+  {
+    [CellId in CellIdFromSchema<Schema, TableId>]: CellIsRequiredFromSchema<
+      Schema,
+      TableId,
+      CellId,
+      IsRequired extends true ? CellId : never,
+      IsRequired extends true ? never : CellId
+    >;
+  }[CellIdFromSchema<Schema, TableId>]
+>;
+
+export type PresentCellIdFromSchema<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  IsPresent extends boolean = true,
+> = AsId<
+  {
+    [CellId in CellIdFromSchema<Schema, TableId>]: CellIsPresentFromSchema<
+      Schema,
+      TableId,
+      CellId,
+      IsPresent extends true ? CellId : never,
+      IsPresent extends true ? never : CellId
+    >;
+  }[CellIdFromSchema<Schema, TableId>]
+>;
+
+export type RequiredNonDefaultCellIdFromSchema<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+> = AsId<
+  {
+    [CellId in CellIdFromSchema<Schema, TableId>]: CellIsRequiredFromSchema<
+      Schema,
+      TableId,
+      CellId,
+      CellIsDefaultedFromSchema<Schema, TableId, CellId, never, CellId>,
+      never
+    >;
+  }[CellIdFromSchema<Schema, TableId>]
+>;
+
 export type AllCellIdFromSchema<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema> = TableIdFromSchema<Schema>,
@@ -53,13 +100,39 @@ export type CellIsDefaultedFromSchema<
   ? Then
   : Else;
 
+export type CellIsRequiredFromSchema<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellId extends CellIdFromSchema<Schema, TableId>,
+  Then,
+  Else,
+> = Schema[TableId][CellId] extends {
+  required: true;
+}
+  ? Then
+  : Else;
+
+export type CellIsPresentFromSchema<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellId extends CellIdFromSchema<Schema, TableId>,
+  Then,
+  Else,
+> = CellIsDefaultedFromSchema<
+  Schema,
+  TableId,
+  CellId,
+  Then,
+  CellIsRequiredFromSchema<Schema, TableId, CellId, Then, Else>
+>;
+
 export type DefaultedCellFromSchema<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema>,
   CellId extends CellIdFromSchema<Schema, TableId>,
 > =
   | Cell<Schema, TableId, CellId>
-  | CellIsDefaultedFromSchema<Schema, TableId, CellId, never, undefined>;
+  | CellIsPresentFromSchema<Schema, TableId, CellId, never, undefined>;
 
 export type ValueIdFromSchema<Schema extends OptionalValuesSchema> = AsId<
   keyof Schema
@@ -77,6 +150,41 @@ export type DefaultValueIdFromSchema<
   >;
 }[ValueIdFromSchema<Schema>];
 
+export type RequiredValueIdFromSchema<
+  Schema extends OptionalValuesSchema,
+  IsRequired extends boolean = true,
+> = {
+  [ValueId in ValueIdFromSchema<Schema>]: ValueIsRequiredFromSchema<
+    Schema,
+    ValueId,
+    IsRequired extends true ? ValueId : never,
+    IsRequired extends true ? never : ValueId
+  >;
+}[ValueIdFromSchema<Schema>];
+
+export type PresentValueIdFromSchema<
+  Schema extends OptionalValuesSchema,
+  IsPresent extends boolean = true,
+> = {
+  [ValueId in ValueIdFromSchema<Schema>]: ValueIsPresentFromSchema<
+    Schema,
+    ValueId,
+    IsPresent extends true ? ValueId : never,
+    IsPresent extends true ? never : ValueId
+  >;
+}[ValueIdFromSchema<Schema>];
+
+export type RequiredNonDefaultValueIdFromSchema<
+  Schema extends OptionalValuesSchema,
+> = {
+  [ValueId in ValueIdFromSchema<Schema>]: ValueIsRequiredFromSchema<
+    Schema,
+    ValueId,
+    ValueIsDefaultedFromSchema<Schema, ValueId, never, ValueId>,
+    never
+  >;
+}[ValueIdFromSchema<Schema>];
+
 export type ValueIsDefaultedFromSchema<
   Schema extends OptionalValuesSchema,
   ValueId extends ValueIdFromSchema<Schema>,
@@ -88,12 +196,35 @@ export type ValueIsDefaultedFromSchema<
   ? Then
   : Else;
 
+export type ValueIsRequiredFromSchema<
+  Schema extends OptionalValuesSchema,
+  ValueId extends ValueIdFromSchema<Schema>,
+  Then,
+  Else,
+> = Schema[ValueId] extends {
+  required: true;
+}
+  ? Then
+  : Else;
+
+export type ValueIsPresentFromSchema<
+  Schema extends OptionalValuesSchema,
+  ValueId extends ValueIdFromSchema<Schema>,
+  Then,
+  Else,
+> = ValueIsDefaultedFromSchema<
+  Schema,
+  ValueId,
+  Then,
+  ValueIsRequiredFromSchema<Schema, ValueId, Then, Else>
+>;
+
 export type DefaultedValueFromSchema<
   Schema extends OptionalValuesSchema,
   ValueId extends ValueIdFromSchema<Schema>,
 > =
   | Value<Schema, ValueId>
-  | ValueIsDefaultedFromSchema<Schema, ValueId, never, undefined>;
+  | ValueIsPresentFromSchema<Schema, ValueId, never, undefined>;
 
 export type AsId<Key> = Exclude<Key & Id, number>;
 

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

@@ -83,11 +83,26 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
 export type Callback = () => void;
 
 /**
- * The SortKey type represents a value that can be used by a sort function.
+ * The SortKey type represents a Cell value, or `undefined`, that can be used by
+ * a sort function.
  * @category Parameter
  * @since v1.0.0
  */
-export type SortKey = string | number | boolean | null;
+export type SortKey = CellOrUndefined;
+
+/**
+ * The Sorter type represents a function that compares two SortKey values.
+ *
+ * A Sorter is provided to methods that sort Row Ids when the default
+ * alphanumeric ordering is not appropriate. Return a positive or negative
+ * number to indicate which of the two SortKey values should be ordered first.
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @category Parameter
+ * @since v9.1.0
+ */
+export type Sorter = (sortKey1: SortKey, sortKey2: SortKey) => number;
 
 /**
  * The GetNow type is used to represent a function that returns the current time

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

@@ -95,11 +95,27 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
 export type Callback = () => void;
 
 /**
- * The SortKey type represents a value that can be used by a sort function.
+ * The SortKey type represents a Cell value, or `undefined`, that can be used by
+ * a sort function.
  * @category Parameter
  * @since v1.0.0
  */
-export type SortKey = string | number | boolean;
+export type SortKey =
+  string | number | boolean | null | AnyObject | AnyArray | undefined;
+
+/**
+ * The Sorter type represents a function that compares two SortKey values.
+ *
+ * A Sorter is provided to methods that sort Row Ids when the default
+ * alphanumeric ordering is not appropriate. Return a positive or negative
+ * number to indicate which of the two SortKey values should be ordered first.
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @category Parameter
+ * @since v9.1.0
+ */
+export type Sorter = (sortKey1: SortKey, sortKey2: SortKey) => number;
 
 /**
  * The GetNow type is used to represent a function that returns the current time

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

@@ -92,6 +92,27 @@ export type SliceCallback = (
  */
 export type IndexIdsListener = (indexes: Indexes) => void;
 
+/**
+ * The HasIndexListener type describes a function that is used to listen to
+ * Index definitions being added or removed.
+ *
+ * A HasIndexListener is provided when using the addHasIndexListener method.
+ * See that method for specific examples.
+ *
+ * When called, a HasIndexListener is given a reference to the Indexes object,
+ * the Id of the Index that changed, and whether it now exists.
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
+ * @param hasIndex Whether the Index now exists.
+ * @category Listener
+ * @since v9.1.0
+ */
+export type HasIndexListener = (
+  indexes: Indexes,
+  indexId: Id,
+  hasIndex: boolean,
+) => void;
+
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -108,6 +129,30 @@ export type IndexIdsListener = (indexes: Indexes) => void;
  */
 export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
 
+/**
+ * The HasSliceListener type describes a function that is used to listen to
+ * Slices being added to or removed from an Index.
+ *
+ * A HasSliceListener is provided when using the addHasSliceListener method. See
+ * that method for specific examples.
+ *
+ * When called, a HasSliceListener is given a reference to the Indexes object,
+ * the Id of the Index that changed, the Id of the Slice that changed, and
+ * whether it now exists.
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
+ * @param sliceId The Id of the Slice that changed.
+ * @param hasSlice Whether the Slice now exists.
+ * @category Listener
+ * @since v9.1.0
+ */
+export type HasSliceListener = (
+  indexes: Indexes,
+  indexId: Id,
+  sliceId: Id,
+  hasSlice: boolean,
+) => void;
+
 /**
  * The SliceRowIdsListener type describes a function that is used to listen to
  * changes to the Row Ids in a Slice.
@@ -812,6 +857,27 @@ export interface Indexes {
    */
   addIndexIdsListener(listener: IndexIdsListener): Id;
 
+  /**
+   * The addHasIndexListener method registers a listener function with the
+   * Indexes object that will be called whenever an Index definition is added or
+   * removed.
+   *
+   * You can either listen to a single Index (by specifying the Index Id as the
+   * method's first parameter), or changes to any Index (by providing a `null`
+   * wildcard).
+   *
+   * The provided listener is a HasIndexListener function, and will be called
+   * with a reference to the Indexes object, the Id of the Index that changed,
+   * and whether it now exists.
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Index is
+   * added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @category Listener
+   * @since v9.1.0
+   */
+  addHasIndexListener(indexId: IdOrNull, listener: HasIndexListener): Id;
+
   /**
    * The addSliceRowIdsListener method registers a listener function with the
    * Indexes object that will be called whenever the Row Ids in a Slice change.
@@ -909,6 +975,37 @@ export interface Indexes {
     listener: SliceRowIdsListener,
   ): Id;
 
+  /**
+   * The addHasSliceListener method registers a listener function with the
+   * Indexes object that will be called whenever a Slice is added to or removed
+   * from an Index.
+   *
+   * You can either listen to a single Slice (by specifying the Index Id and
+   * Slice Id as the method's first two parameters), or changes to any Slice (by
+   * providing `null` wildcards).
+   *
+   * Both, either, or neither of the `indexId` and `sliceId` parameters can be
+   * wildcarded with `null`. You can listen to a specific Slice in a specific
+   * Index, any Slice in a specific Index, a specific Slice in any Index, or any
+   * Slice in any Index.
+   *
+   * The provided listener is a HasSliceListener function, and will be called
+   * with a reference to the Indexes object, the Id of the Index, the Id of the
+   * Slice that changed, and whether it now exists.
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param sliceId The Id of the Slice to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Slice is
+   * added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @category Listener
+   * @since v9.1.0
+   */
+  addHasSliceListener(
+    indexId: IdOrNull,
+    sliceId: IdOrNull,
+    listener: HasSliceListener,
+  ): Id;
+
   /**
    * The delListener method removes a listener that was previously added to the
    * Indexes object.

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

@@ -133,6 +133,37 @@ export type IndexIdsListener<Schemas extends OptionalSchemas> = (
   indexes: Indexes<Schemas>,
 ) => void;
 
+/**
+ * The HasIndexListener type describes a function that is used to listen to
+ * Index definitions being added or removed.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   indexes: Indexes,
+ *   indexId: Id,
+ *   hasIndex: boolean,
+ * ) => void;
+ * ```
+ *
+ * A HasIndexListener is provided when using the addHasIndexListener method.
+ * See that method for specific examples.
+ *
+ * When called, a HasIndexListener is given a reference to the Indexes object,
+ * the Id of the Index that changed, and whether it now exists.
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
+ * @param hasIndex Whether the Index now exists.
+ * @category Listener
+ * @since v9.1.0
+ */
+export type HasIndexListener<Schemas extends OptionalSchemas> = (
+  indexes: Indexes<Schemas>,
+  indexId: Id,
+  hasIndex: boolean,
+) => void;
+
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -158,6 +189,41 @@ export type SliceIdsListener<Schemas extends OptionalSchemas> = (
   indexId: Id,
 ) => void;
 
+/**
+ * The HasSliceListener type describes a function that is used to listen to
+ * Slices being added to or removed from an Index.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   indexes: Indexes,
+ *   indexId: Id,
+ *   sliceId: Id,
+ *   hasSlice: boolean,
+ * ) => void;
+ * ```
+ *
+ * A HasSliceListener is provided when using the addHasSliceListener method. See
+ * that method for specific examples.
+ *
+ * When called, a HasSliceListener is given a reference to the Indexes object,
+ * the Id of the Index that changed, the Id of the Slice that changed, and
+ * whether it now exists.
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
+ * @param sliceId The Id of the Slice that changed.
+ * @param hasSlice Whether the Slice now exists.
+ * @category Listener
+ * @since v9.1.0
+ */
+export type HasSliceListener<Schemas extends OptionalSchemas> = (
+  indexes: Indexes<Schemas>,
+  indexId: Id,
+  sliceId: Id,
+  hasSlice: boolean,
+) => void;
+
 /**
  * The SliceRowIdsListener type describes a function that is used to listen to
  * changes to the Row Ids in a Slice.
@@ -845,6 +911,36 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    */
   addIndexIdsListener(listener: IndexIdsListener<Schemas>): Id;
 
+  /**
+   * The addHasIndexListener method registers a listener function with the
+   * Indexes object that will be called whenever an Index definition is added or
+   * removed.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addHasIndexListener(indexId: IdOrNull, listener: HasIndexListener): Id;
+   * ```
+   *
+   * You can either listen to a single Index (by specifying the Index Id as the
+   * method's first parameter), or changes to any Index (by providing a `null`
+   * wildcard).
+   *
+   * The provided listener is a HasIndexListener function, and will be called
+   * with a reference to the Indexes object, the Id of the Index that changed,
+   * and whether it now exists.
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Index is
+   * added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @category Listener
+   * @since v9.1.0
+   */
+  addHasIndexListener(
+    indexId: IdOrNull,
+    listener: HasIndexListener<Schemas>,
+  ): Id;
+
   /**
    * The addSliceIdsListener method registers a listener function with the
    * Indexes object that will be called whenever the Slice Ids in an Index
@@ -1042,6 +1138,47 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
     listener: SliceRowIdsListener<Schemas>,
   ): Id;
 
+  /**
+   * The addHasSliceListener method registers a listener function with the
+   * Indexes object that will be called whenever a Slice is added to or removed
+   * from an Index.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addHasSliceListener(
+   *   indexId: IdOrNull,
+   *   sliceId: IdOrNull,
+   *   listener: HasSliceListener,
+   * ): Id;
+   * ```
+   *
+   * You can either listen to a single Slice (by specifying the Index Id and
+   * Slice Id as the method's first two parameters), or changes to any Slice (by
+   * providing `null` wildcards).
+   *
+   * Both, either, or neither of the `indexId` and `sliceId` parameters can be
+   * wildcarded with `null`. You can listen to a specific Slice in a specific
+   * Index, any Slice in a specific Index, a specific Slice in any Index, or any
+   * Slice in any Index.
+   *
+   * The provided listener is a HasSliceListener function, and will be called
+   * with a reference to the Indexes object, the Id of the Index, the Id of the
+   * Slice that changed, and whether it now exists.
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param sliceId The Id of the Slice to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Slice is
+   * added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @category Listener
+   * @since v9.1.0
+   */
+  addHasSliceListener(
+    indexId: IdOrNull,
+    sliceId: IdOrNull,
+    listener: HasSliceListener<Schemas>,
+  ): Id;
+
   /**
    * The delListener method removes a listener that was previously added to the
    * Indexes object.