tinybase 9.1.0-beta.1 → 9.1.0-beta.2

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,
@@ -72,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`.
@@ -90,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.
  *
@@ -105,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
@@ -145,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`.
@@ -163,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.
  *
@@ -178,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
@@ -371,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
@@ -480,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>;
 };
 
 /**
@@ -4543,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;
 
   /**
@@ -4740,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.

package/@types/ui-react/index.d.ts

@@ -7255,6 +7255,26 @@ export function useProvideIndexes(indexesId: Id, indexes: Indexes): void;
  */
 export function useIndexIds(indexesOrIndexesId?: IndexesOrIndexesId): Ids;
 
+/**
+ * The useHasIndex hook returns a boolean indicating whether a given Index
+ * exists in the Indexes object, and registers a listener so that any changes to
+ * that result will cause a re-render.
+ *
+ * This hook follows the same Indexes object resolution rules as the useIndexIds
+ * hook.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether an Index with that Id exists.
+ * @category Indexes hooks
+ * @since v9.1.0
+ */
+export function useHasIndex(
+  indexId: Id,
+  indexesOrIndexesId?: IndexesOrIndexesId,
+): boolean;
+
 /**
  * The useSliceIds hook gets the list of Slice Ids in an Index, and registers a
  * listener so that any changes to that result will cause a re-render.
@@ -7375,6 +7395,28 @@ export function useSliceIds(
   indexesOrIndexesId?: IndexesOrIndexesId,
 ): Ids;
 
+/**
+ * The useHasSlice hook returns a boolean indicating whether a given Slice
+ * exists in an Index, and registers a listener so that any changes to that
+ * result will cause a re-render.
+ *
+ * This hook follows the same Indexes object resolution rules as the useSliceIds
+ * hook.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param sliceId The Id of a possible Slice in the Index.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether a Slice with that Id exists.
+ * @category Indexes hooks
+ * @since v9.1.0
+ */
+export function useHasSlice(
+  indexId: Id,
+  sliceId: Id,
+  indexesOrIndexesId?: IndexesOrIndexesId,
+): boolean;
+
 /**
  * The useSliceRowIds hook gets the list of Row Ids in a given Slice, and
  * registers a listener so that any changes to that result will cause a

package/@types/ui-react/with-schemas/index.d.ts

@@ -141,6 +141,8 @@ import type {
   MapCell,
   MapValue,
   OptionalSchemas,
+  PartialRow,
+  PartialValues,
   Row,
   RowCountListener,
   RowIdsListener,
@@ -3577,14 +3579,14 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v1.0.0
  */
-  useSetTablesCallback: <Parameter, SetTables = Tables<Schemas[0], true>>(
+  useSetTablesCallback: <Parameter>(
     getTables: (
       parameter: Parameter,
       store: Store<Schemas>,
-    ) => NoInfer<SetTables>,
+    ) => Tables<Schemas[0], true>,
     getTablesDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, tables: SetTables) => void,
+    then?: (store: Store<Schemas>, tables: Tables<Schemas[0], true>) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -3688,16 +3690,18 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   useSetTableCallback: <
     Parameter,
     TableId extends TableIdFromSchema<Schemas[0]>,
-    SetTable = Table<Schemas[0], TableId, true>,
   >(
     tableId: TableId | GetId<Schemas, Parameter, TableId>,
     getTable: (
       parameter: Parameter,
       store: Store<Schemas>,
-    ) => NoInfer<SetTable>,
+    ) => Table<Schemas[0], TableId, true>,
     getTableDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, table: SetTable) => void,
+    then?: (
+      store: Store<Schemas>,
+      table: Table<Schemas[0], TableId, true>,
+    ) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -3803,17 +3807,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v1.0.0
  */
-  useSetRowCallback: <
-    Parameter,
-    TableId extends TableIdFromSchema<Schemas[0]>,
-    SetRow = Row<Schemas[0], TableId, true>,
-  >(
+  useSetRowCallback: <Parameter, TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId | GetId<Schemas, Parameter, TableId>,
     rowId: Id | GetId<Schemas, Parameter, Id>,
-    getRow: (parameter: Parameter, store: Store<Schemas>) => NoInfer<SetRow>,
+    getRow: (
+      parameter: Parameter,
+      store: Store<Schemas>,
+    ) => Row<Schemas[0], TableId, true>,
     getRowDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, row: SetRow) => void,
+    then?: (store: Store<Schemas>, row: Row<Schemas[0], TableId, true>) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -3924,16 +3927,19 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v1.0.0
  */
-  useAddRowCallback: <
-    Parameter,
-    TableId extends TableIdFromSchema<Schemas[0]>,
-    AddRow = Row<Schemas[0], TableId, true>,
-  >(
+  useAddRowCallback: <Parameter, TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId | GetId<Schemas, Parameter, TableId>,
-    getRow: (parameter: Parameter, store: Store<Schemas>) => NoInfer<AddRow>,
+    getRow: (
+      parameter: Parameter,
+      store: Store<Schemas>,
+    ) => Row<Schemas[0], TableId, true>,
     getRowDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (rowId: Id | undefined, store: Store<Schemas>, row: AddRow) => void,
+    then?: (
+      rowId: Id | undefined,
+      store: Store<Schemas>,
+      row: Row<Schemas[0], TableId, true>,
+    ) => void,
     thenDeps?: React.DependencyList,
     reuseRowIds?: boolean,
   ) => ParameterizedCallback<Parameter>;
@@ -4045,17 +4051,19 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   useSetPartialRowCallback: <
     Parameter,
     TableId extends TableIdFromSchema<Schemas[0]>,
-    SetPartialRow = Row<Schemas[0], TableId, true>,
   >(
     tableId: TableId | GetId<Schemas, Parameter, TableId>,
     rowId: Id | GetId<Schemas, Parameter, Id>,
     getPartialRow: (
       parameter: Parameter,
       store: Store<Schemas>,
-    ) => NoInfer<SetPartialRow>,
+    ) => PartialRow<Schemas[0], TableId>,
     getPartialRowDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, partialRow: SetPartialRow) => void,
+    then?: (
+      store: Store<Schemas>,
+      partialRow: PartialRow<Schemas[0], TableId>,
+    ) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -4319,14 +4327,14 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v3.0.0
  */
-  useSetValuesCallback: <Parameter, SetValues = Values<Schemas[1], true>>(
+  useSetValuesCallback: <Parameter>(
     getValues: (
       parameter: Parameter,
       store: Store<Schemas>,
-    ) => NoInfer<SetValues>,
+    ) => Values<Schemas[1], true>,
     getValuesDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, values: SetValues) => void,
+    then?: (store: Store<Schemas>, values: Values<Schemas[1], true>) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -4424,17 +4432,17 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v3.0.0
  */
-  useSetPartialValuesCallback: <
-    Parameter,
-    SetPartialValues = Values<Schemas[1], true>,
-  >(
+  useSetPartialValuesCallback: <Parameter>(
     getPartialValues: (
       parameter: Parameter,
       store: Store<Schemas>,
-    ) => NoInfer<SetPartialValues>,
+    ) => PartialValues<Schemas[1]>,
     getPartialValuesDeps?: React.DependencyList,
     storeOrStoreId?: StoreOrStoreId<Schemas>,
-    then?: (store: Store<Schemas>, partialValues: SetPartialValues) => void,
+    then?: (
+      store: Store<Schemas>,
+      partialValues: PartialValues<Schemas[1]>,
+    ) => void,
     thenDeps?: React.DependencyList,
   ) => ParameterizedCallback<Parameter>;
 
@@ -8179,6 +8187,35 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  */
   useIndexIds(indexesOrIndexesId?: IndexesOrIndexesId<Schemas>): Ids;
 
+  /**
+ * The useHasIndex hook returns a boolean indicating whether a given Index
+ * exists in the Indexes object, and registers a listener so that any changes to
+ * that result will cause a re-render.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useHasIndex(
+ *   indexId: Id,
+ *   indexesOrIndexesId?: IndexesOrIndexesId,
+ * ): boolean;
+ * ```
+ *
+ * This hook follows the same Indexes object resolution rules as the useIndexIds
+ * hook.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether an Index with that Id exists.
+ * @category Indexes hooks
+ * @since v9.1.0
+ */
+  useHasIndex: (
+    indexId: Id,
+    indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
+  ) => boolean;
+
   /**
  * The useSliceIds hook gets the list of Slice Ids in an Index, and registers a
  * listener so that any changes to that result will cause a re-render.
@@ -8308,6 +8345,38 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
   ) => Ids;
 
+  /**
+ * The useHasSlice hook returns a boolean indicating whether a given Slice
+ * exists in an Index, and registers a listener so that any changes to that
+ * result will cause a re-render.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useHasSlice(
+ *   indexId: Id,
+ *   sliceId: Id,
+ *   indexesOrIndexesId?: IndexesOrIndexesId,
+ * ): boolean;
+ * ```
+ *
+ * This hook follows the same Indexes object resolution rules as the useSliceIds
+ * hook.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param sliceId The Id of a possible Slice in the Index.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether a Slice with that Id exists.
+ * @category Indexes hooks
+ * @since v9.1.0
+ */
+  useHasSlice: (
+    indexId: Id,
+    sliceId: Id,
+    indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
+  ) => boolean;
+
   /**
  * The useSliceRowIds hook gets the list of Row Ids in a given Slice, and
  * registers a listener so that any changes to that result will cause a

package/@types/ui-solid/index.d.ts

@@ -6871,6 +6871,26 @@ export function useIndexIds(
   indexesOrIndexesId?: MaybeAccessor<IndexesOrIndexesId | undefined>,
 ): Accessor<Ids>;
 
+/**
+ * The useHasIndex primitive returns a boolean indicating whether a given Index
+ * exists in the Indexes object, and registers a listener so that any changes to
+ * that result will cause an update.
+ *
+ * This primitive follows the same Indexes object resolution rules as the
+ * useIndexIds primitive.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether an Index with that Id exists.
+ * @category Indexes primitives
+ * @since v9.1.0
+ */
+export function useHasIndex(
+  indexId: MaybeAccessor<Id>,
+  indexesOrIndexesId?: MaybeAccessor<IndexesOrIndexesId | undefined>,
+): Accessor<boolean>;
+
 /**
  * The useSliceIds primitive gets the list of Slice Ids in an Index, and
  * registers a listener so that any changes to that result will cause an update.
@@ -6958,6 +6978,28 @@ export function useSliceIds(
   indexesOrIndexesId?: MaybeAccessor<IndexesOrIndexesId | undefined>,
 ): Accessor<Ids>;
 
+/**
+ * The useHasSlice primitive returns a boolean indicating whether a given Slice
+ * exists in an Index, and registers a listener so that any changes to that
+ * result will cause an update.
+ *
+ * This primitive follows the same Indexes object resolution rules as the
+ * useSliceIds primitive.
+ * @param indexId The Id of a possible Index in the Indexes object.
+ * @param sliceId The Id of a possible Slice in the Index.
+ * @param indexesOrIndexesId The Indexes object to be accessed: omit for the
+ * default context Indexes object, provide an Id for a named context Indexes
+ * object, or provide an explicit reference.
+ * @returns Whether a Slice with that Id exists.
+ * @category Indexes primitives
+ * @since v9.1.0
+ */
+export function useHasSlice(
+  indexId: MaybeAccessor<Id>,
+  sliceId: MaybeAccessor<Id>,
+  indexesOrIndexesId?: MaybeAccessor<IndexesOrIndexesId | undefined>,
+): Accessor<boolean>;
+
 /**
  * The useSliceRowIds primitive gets the list of Row Ids in a given Slice, and
  * registers a listener so that any changes to that result will cause an update.