tinybase 9.5.0-beta.0 → 9.5.0

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

@@ -22,6 +22,8 @@ import type {
   StoreAlias,
   TableIdFromSchema,
   Truncate,
+  ValidTablesSchema,
+  ValidValuesSchema,
   ValueIdFromSchema,
 } from '../../_internal/store/with-schemas/index.d.ts';
 import type {
@@ -34,6 +36,24 @@ import type {
   Sorter,
 } from '../../common/with-schemas/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
+            : string | number | boolean | AnyObject | AnyArray;
+
 /**
  * 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.
@@ -65,17 +85,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.
  *
@@ -118,15 +146,86 @@ 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
  */
 export type CellSchema =
-  | {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};
+  | {
+      type: 'string';
+      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 | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      type: 'array';
+      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;
+    };
 
 /**
  * The ValuesSchema type describes the keyed Values that can be set in a Store
@@ -154,16 +253,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.
@@ -207,15 +314,86 @@ 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
  */
 export type ValueSchema =
-  | {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};
+  | {
+      type: 'string';
+      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 | null;
+      allowNull?: boolean;
+      required?: boolean;
+      enum?: never;
+    }
+  | {
+      type: 'array';
+      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;
+    };
 
 /**
  * The NoTablesSchema type is a TablesSchema-like type for when one has not been
@@ -482,17 +660,17 @@ export type Cell<
   TableId extends TableIdFromSchema<Schema>,
   CellId extends CellIdFromSchema<Schema, TableId>,
   CellType = Schema[TableId][CellId]['type'],
-> = CellType extends 'string'
-  ? string
-  : CellType extends 'number'
-    ? number
-    : CellType extends 'boolean'
-      ? boolean
-      : CellType extends 'object'
-        ? AnyObject
-        : CellType extends 'array'
-          ? AnyArray
-          : string | number | boolean | AnyObject | AnyArray;
+  CellEnum = Schema[TableId][CellId] extends {
+    enum: readonly (infer Enum)[];
+  }
+    ? Enum
+    : never,
+  CellNull = Schema[TableId][CellId] extends {allowNull: true} ? null : never,
+> =
+  | ([CellEnum] extends [never]
+      ? CellOrValueFromSchemaType<CellType>
+      : CellEnum)
+  | CellNull;
 
 /**
  * The CellOrUndefined type is a data structure representing the data in a
@@ -614,17 +792,15 @@ export type Value<
   Schema extends OptionalValuesSchema,
   ValueId extends ValueIdFromSchema<Schema>,
   ValueType = Schema[ValueId]['type'],
-> = ValueType extends 'string'
-  ? string
-  : ValueType extends 'number'
-    ? number
-    : ValueType extends 'boolean'
-      ? boolean
-      : ValueType extends 'object'
-        ? AnyObject
-        : ValueType extends 'array'
-          ? AnyArray
-          : string | number | boolean | AnyObject | AnyArray;
+  ValueEnum = Schema[ValueId] extends {enum: readonly (infer Enum)[]}
+    ? Enum
+    : never,
+  ValueNull = Schema[ValueId] extends {allowNull: true} ? null : never,
+> =
+  | ([ValueEnum] extends [never]
+      ? CellOrValueFromSchemaType<ValueType>
+      : ValueEnum)
+  | ValueNull;
 
 /**
  * The ValueOrUndefined type is a data structure representing the data in a
@@ -5093,7 +5269,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * setTablesSchema(tablesSchema: TablesSchema): this;
+   * setTablesSchema<const TS extends TablesSchema>(
+   *   tablesSchema: TS & ValidTablesSchema<TS>,
+   * ): this;
    * ```
    *
    * Note that this may result in a change to data in the Store, as defaults are
@@ -5124,9 +5302,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * @category Setter
    * @since v3.0.0
    */
-  setTablesSchema<TS extends TablesSchema>(
-    tablesSchema: TS,
-  ): Store<[typeof tablesSchema, Schemas[1]]>;
+  setTablesSchema<const TS extends TablesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+  ): Store<[TS, Schemas[1]]>;
 
   /**
    * The setValuesSchema method lets you specify the ValuesSchema of the keyed
@@ -5135,7 +5313,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * setValuesSchema(valuesSchema: ValuesSchema): this;
+   * setValuesSchema<const VS extends ValuesSchema>(
+   *   valuesSchema: VS & ValidValuesSchema<VS>,
+   * ): this;
    * ```
    *
    * Note that this may result in a change to data in the Store, as defaults are
@@ -5163,9 +5343,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * @category Setter
    * @since v3.0.0
    */
-  setValuesSchema<VS extends ValuesSchema>(
-    valuesSchema: VS,
-  ): Store<[Schemas[0], typeof valuesSchema]>;
+  setValuesSchema<const VS extends ValuesSchema>(
+    valuesSchema: VS & ValidValuesSchema<VS>,
+  ): Store<[Schemas[0], VS]>;
 
   /**
    * The setSchema method lets you specify the TablesSchema and ValuesSchema of
@@ -5174,7 +5354,10 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * setSchema(tablesSchema: TablesSchema, valuesSchema?: ValuesSchema): this;
+   * setSchema<const TS extends TablesSchema, const VS extends ValuesSchema>(
+   *   tablesSchema: TS & ValidTablesSchema<TS>,
+   *   valuesSchema?: VS & ValidValuesSchema<VS>,
+   * ): this;
    * ```
    *
    * Note that this may result in a change to data in the Store, as defaults are
@@ -5234,15 +5417,15 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * @category Setter
    * @since v1.0.0
    */
-  setSchema<TS extends TablesSchema, VS extends ValuesSchema>(
-    tablesSchema: TS,
-    valuesSchema?: VS,
+  setSchema<const TS extends TablesSchema, const VS extends ValuesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+    valuesSchema?: VS & ValidValuesSchema<VS>,
   ): Store<
     [
-      typeof tablesSchema,
+      TS,
       Exclude<ValuesSchema, typeof valuesSchema> extends never
         ? NoValuesSchema
-        : NonNullable<typeof valuesSchema>,
+        : VS,
     ]
   >;
 

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

@@ -98,7 +98,7 @@ export const enum Message {
  */
 export type Send = (
   toClientId: IdOrNull,
-  requestId: Id,
+  requestId: IdOrNull,
   message: Message,
   body: any,
 ) => void;
@@ -123,7 +123,7 @@ export type Send = (
  */
 export type Receive = (
   fromClientId: Id,
-  requestId: Id,
+  requestId: IdOrNull,
   message: Message,
   body: any,
 ) => void;
@@ -137,7 +137,17 @@ export type Receive = (
  * @since v5.0.0
  */
 export type SynchronizerStats = {
+  /**
+   * The number of times messages have been sent.
+   * @category Stat
+   * @since v5.0.0
+   */
   sends: number;
+  /**
+   * The number of times messages has been received.
+   * @category Stat
+   * @since v5.0.0
+   */
   receives: number;
 };