tinybase 9.5.0-beta.0 → 9.5.0

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

@@ -21,6 +21,50 @@ import type {
   Sorter,
 } from '../common/index.d.ts';
 
+type SchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+
+type SchemaTypeArray = readonly [SchemaType, ...SchemaType[]];
+
+type CellOrValueFromSchemaType<Type> = Type extends readonly (infer Type)[]
+  ? CellOrValueFromSchemaType<Type>
+  : Type extends 'string'
+    ? string
+    : Type extends 'number'
+      ? number
+      : Type extends 'boolean'
+        ? boolean
+        : Type extends 'object'
+          ? AnyObject
+          : Type extends 'array'
+            ? AnyArray
+            : never;
+
+type CellOrValueFromSchema<Schema> = Schema extends {
+  enum: readonly (infer Enum)[];
+}
+  ? Enum
+  : Schema extends {type: infer Type}
+    ? CellOrValueFromSchemaType<Type>
+    : never;
+
+type NullFromSchema<Schema> = Schema extends {allowNull: true} ? null : never;
+
+type ValidDefault<Schema> = Schema extends {default: infer Default}
+  ? [Default] extends [CellOrValueFromSchema<Schema> | NullFromSchema<Schema>]
+    ? unknown
+    : never
+  : unknown;
+
+type ValidTablesSchema<Schema extends TablesSchema> = {
+  [TableId in keyof Schema]: {
+    [CellId in keyof Schema[TableId]]: ValidDefault<Schema[TableId][CellId]>;
+  };
+};
+
+type ValidValuesSchema<Schema extends ValuesSchema> = {
+  [ValueId in keyof Schema]: ValidDefault<Schema[ValueId]>;
+};
+
 /**
  * The TablesSchema type describes the tabular structure of a Store in terms of
  * valid Table Ids and the types of Cell that can exist within them.
@@ -52,17 +96,25 @@ 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`, `number`,
- * `null` since v7.0, or `object` or `array` since v8.0), and what the default
- * value can be when an explicit value is not specified.
+ * A CellSchema specifies either the type of the Cell (`string`, `boolean`,
+ * `number`, `object`, or `array`), a non-empty array of those types, or a
+ * non-empty `enum` of exact primitive values that are allowed. Multiple type
+ * names form a union, such as `type: ['string', 'number']`, and repeated names
+ * have no additional effect. The `type` and `enum` properties are mutually
+ * exclusive, and enum members can be strings, finite numbers, or booleans,
+ * including a mixture of those types.
  *
  * For `object` and `array` types, TinyBase automatically serializes values to
  * and from JSON when storing and retrieving them. Their contents should
  * recursively be strings, finite numbers, booleans, `null`, plain objects, or
  * arrays to ensure they are preserved.
  *
- * 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. You can also set `required`
+ * Set `allowNull` to `true` to also allow `null`, whether the schema uses
+ * `type` or `enum`. A default value is used only when it has the correct type,
+ * matches any member of a type union, is an enum member when applicable, or is
+ * `null` when allowed. Literal schemas passed to Store schema setters are
+ * checked against these default rules by TypeScript. A valid default means
+ * that the 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.
  *
@@ -105,6 +157,30 @@ export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};
  *   default: {},
  * };
  * ```
+ * @example
+ * When applied to a Store, this CellSchema allows either a string or numeric
+ * Cell.
+ *
+ * ```js
+ * import type {CellSchema} from 'tinybase';
+ *
+ * export const referenceCell: CellSchema = {
+ *   type: ['string', 'number'],
+ * };
+ * ```
+ * @example
+ * When applied to a Store, this CellSchema allows one of three exact primitive
+ * values, or `null`.
+ *
+ * ```js
+ * import type {CellSchema} from 'tinybase';
+ *
+ * export const ratingCell: CellSchema = {
+ *   enum: ['good', 5, true],
+ *   allowNull: true,
+ *   default: 'good',
+ * };
+ * ```
  * @category Schema
  * @since v1.0.0
  */
@@ -114,28 +190,50 @@ export type CellSchema =
       default?: string | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'number';
       default?: number | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'boolean';
       default?: boolean | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'object';
-      default?: AnyObject;
+      default?: AnyObject | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'array';
-      default?: AnyArray;
+      default?: AnyArray | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      type: SchemaTypeArray;
+      default?: string | number | boolean | AnyObject | AnyArray | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      enum: readonly [
+        string | number | boolean,
+        ...(string | number | boolean)[],
+      ];
+      type?: never;
+      default?: string | number | boolean | null;
       allowNull?: boolean;
       required?: boolean;
     };
@@ -166,16 +264,24 @@ 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`, `number`,
- * `null` since v7.0, or `object` or `array` since v8.0), and what the default
- * value can be when an explicit value is not specified.
+ * A ValueSchema specifies either the type of the Value (`string`, `boolean`,
+ * `number`, `object`, or `array`), a non-empty array of those types, or a
+ * non-empty `enum` of exact primitive values that are allowed. Multiple type
+ * names form a union, such as `type: ['string', 'number']`, and repeated names
+ * have no additional effect. The `type` and `enum` properties are mutually
+ * exclusive, and enum members can be strings, finite numbers, or booleans,
+ * including a mixture of those types.
  *
  * For `object` and `array` types, TinyBase automatically serializes values to
  * and from JSON when storing and retrieving them. Their contents should
  * recursively be strings, finite numbers, booleans, `null`, plain objects, or
  * arrays to ensure they are preserved.
  *
- * If a default value is provided (and its type is correct), you can be certain
+ * Set `allowNull` to `true` to also allow `null`, whether the schema uses
+ * `type` or `enum`. A default value is used only when it has the correct type,
+ * matches any member of a type union, is an enum member when applicable, or is
+ * `null` when allowed. Literal schemas passed to Store schema setters are
+ * checked against these default rules by TypeScript. A valid default means
  * 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.
@@ -219,6 +325,30 @@ export type ValuesSchema = {[valueId: Id]: ValueSchema};
  *   default: [],
  * };
  * ```
+ * @example
+ * When applied to a Store, this ValueSchema allows either a string or numeric
+ * Value.
+ *
+ * ```js
+ * import type {ValueSchema} from 'tinybase';
+ *
+ * export const referenceValue: ValueSchema = {
+ *   type: ['string', 'number'],
+ * };
+ * ```
+ * @example
+ * When applied to a Store, this ValueSchema allows one of three exact primitive
+ * values, or `null`.
+ *
+ * ```js
+ * import type {ValueSchema} from 'tinybase';
+ *
+ * export const ratingValue: ValueSchema = {
+ *   enum: ['good', 5, true],
+ *   allowNull: true,
+ *   default: 'good',
+ * };
+ * ```
  * @category Schema
  * @since v3.0.0
  */
@@ -228,28 +358,50 @@ export type ValueSchema =
       default?: string | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'number';
       default?: number | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'boolean';
       default?: boolean | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'object';
-      default?: AnyObject;
+      default?: AnyObject | null;
       allowNull?: boolean;
       required?: boolean;
+      enum?: never;
     }
   | {
       type: 'array';
-      default?: AnyArray;
+      default?: AnyArray | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      type: SchemaTypeArray;
+      default?: string | number | boolean | AnyObject | AnyArray | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      enum: readonly [
+        string | number | boolean,
+        ...(string | number | boolean)[],
+      ];
+      type?: never;
+      default?: string | number | boolean | null;
       allowNull?: boolean;
       required?: boolean;
     };
@@ -3918,7 +4070,9 @@ export interface Store {
    * @category Setter
    * @since v3.0.0
    */
-  setTablesSchema(tablesSchema: TablesSchema): this;
+  setTablesSchema<const TS extends TablesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+  ): this;
 
   /**
    * The setValuesSchema method lets you specify the ValuesSchema of the keyed
@@ -3949,7 +4103,9 @@ export interface Store {
    * @category Setter
    * @since v3.0.0
    */
-  setValuesSchema(valuesSchema: ValuesSchema): this;
+  setValuesSchema<const VS extends ValuesSchema>(
+    valuesSchema: VS & ValidValuesSchema<VS>,
+  ): this;
 
   /**
    * The setSchema method lets you specify the TablesSchema and ValuesSchema of
@@ -4012,7 +4168,10 @@ export interface Store {
    * @category Setter
    * @since v1.0.0
    */
-  setSchema(tablesSchema: TablesSchema, valuesSchema?: ValuesSchema): this;
+  setSchema<const TS extends TablesSchema, const VS extends ValuesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+    valuesSchema?: VS & ValidValuesSchema<VS>,
+  ): this;
 
   /**
    * The delTables method lets you remove all of the data in a Store.