tinybase 9.1.0-beta.1 → 9.1.0

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/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.

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

@@ -61,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`.
@@ -79,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.
  *
@@ -94,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
@@ -134,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`.
@@ -152,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.
  *
@@ -167,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