tinybase 9.5.0-beta.0 → 9.5.0

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

@@ -5,7 +5,9 @@ import type {
   OptionalTablesSchema,
   OptionalValuesSchema,
   Store,
+  TablesSchema,
   Value,
+  ValuesSchema,
 } from '../../../store/with-schemas/index.d.ts';
 
 export type TableIdFromSchema<Schema extends OptionalTablesSchema> = AsId<
@@ -94,10 +96,10 @@ export type CellIsDefaultedFromSchema<
   CellId extends CellIdFromSchema<Schema, TableId>,
   Then,
   Else,
-> = Schema[TableId][CellId] extends {
-  default: infer _;
-}
-  ? Then
+> = Schema[TableId][CellId] extends {default: infer Default}
+  ? [Default] extends [Cell<Schema, TableId, CellId>]
+    ? Then
+    : Else
   : Else;
 
 export type CellIsRequiredFromSchema<
@@ -190,12 +192,45 @@ export type ValueIsDefaultedFromSchema<
   ValueId extends ValueIdFromSchema<Schema>,
   Then,
   Else,
-> = Schema[ValueId] extends {
-  default: infer _;
-}
-  ? Then
+> = Schema[ValueId] extends {default: infer Default}
+  ? [Default] extends [Value<Schema, ValueId>]
+    ? Then
+    : Else
   : Else;
 
+type ValidCellDefault<
+  Schema extends TablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellId extends CellIdFromSchema<Schema, TableId>,
+> = Schema[TableId][CellId] extends {default: infer Default}
+  ? [Default] extends [Cell<Schema, TableId, CellId>]
+    ? unknown
+    : never
+  : unknown;
+
+export type ValidTablesSchema<Schema extends TablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]: {
+    [CellId in CellIdFromSchema<Schema, TableId>]: ValidCellDefault<
+      Schema,
+      TableId,
+      CellId
+    >;
+  };
+};
+
+type ValidValueDefault<
+  Schema extends ValuesSchema,
+  ValueId extends ValueIdFromSchema<Schema>,
+> = Schema[ValueId] extends {default: infer Default}
+  ? [Default] extends [Value<Schema, ValueId>]
+    ? unknown
+    : never
+  : unknown;
+
+export type ValidValuesSchema<Schema extends ValuesSchema> = {
+  [ValueId in ValueIdFromSchema<Schema>]: ValidValueDefault<Schema, ValueId>;
+};
+
 export type ValueIsRequiredFromSchema<
   Schema extends OptionalValuesSchema,
   ValueId extends ValueIdFromSchema<Schema>,

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

@@ -22,6 +22,8 @@
 import type {
   CellIdFromSchema,
   TableIdFromSchema,
+  ValidTablesSchema,
+  ValidValuesSchema,
   ValueIdFromSchema,
 } from '../../_internal/store/with-schemas/index.d.ts';
 import type {GetNow, Hash, Hlc, Id} from '../../common/with-schemas/index.d.ts';
@@ -1327,9 +1329,12 @@ export interface MergeableStore<
    * @category Setter
    * @since v3.0.0
    */
-  setTablesSchema<TS extends TablesSchema>(
-    tablesSchema: TS,
-  ): MergeableStore<[typeof tablesSchema, Schemas[1]]>;
+  setTablesSchema<const TS extends TablesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+  ): MergeableStore<[TS, 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
@@ -1360,9 +1365,12 @@ export interface MergeableStore<
    * @category Setter
    * @since v3.0.0
    */
-  setValuesSchema<VS extends ValuesSchema>(
-    valuesSchema: VS,
-  ): MergeableStore<[Schemas[0], typeof valuesSchema]>;
+  setValuesSchema<const VS extends ValuesSchema>(
+    valuesSchema: VS & ValidValuesSchema<VS>,
+  ): MergeableStore<[Schemas[0], VS]>;
+  setValuesSchema<const VS extends ValuesSchema>(
+    valuesSchema: VS & ValidValuesSchema<VS>,
+  ): Store<[Schemas[0], VS]>;
 
   /**
    * The setSchema method lets you specify the TablesSchema and ValuesSchema of
@@ -1425,15 +1433,26 @@ export interface MergeableStore<
    * @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>,
   ): MergeableStore<
     [
-      typeof tablesSchema,
+      TS,
       Exclude<ValuesSchema, typeof valuesSchema> extends never
         ? NoValuesSchema
-        : NonNullable<typeof valuesSchema>,
+        : VS,
+    ]
+  >;
+  setSchema<const TS extends TablesSchema, const VS extends ValuesSchema>(
+    tablesSchema: TS & ValidTablesSchema<TS>,
+    valuesSchema?: VS & ValidValuesSchema<VS>,
+  ): Store<
+    [
+      TS,
+      Exclude<ValuesSchema, typeof valuesSchema> extends never
+        ? NoValuesSchema
+        : VS,
     ]
   >;
 

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

@@ -113,7 +113,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * A ResultCell is typically accessed with the getResultCell method or
  * addResultCellListener method. It is similar to the Cell type in the store
  * module, but without schema-specific typing, and is a JavaScript string,
- * number, or boolean.
+ * number, boolean, null, object, or array.
  * @example
  * ```js
  * import type {ResultCell} from 'tinybase';
@@ -123,7 +123,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * @category Result
  * @since v2.0.0
  */
-export type ResultCell = string | number | boolean | null;
+export type ResultCell = Cell;
 
 /**
  * The ResultCellOrUndefined type is the data structure representing a single
@@ -146,7 +146,7 @@ export type ResultCellOrUndefined = ResultCell | undefined;
  * @category Aggregators
  * @since v2.0.0
  */
-export type Aggregate = (cells: Cell[], length: number) => ResultCell;
+export type Aggregate = (cells: ResultCell[], length: number) => ResultCell;
 
 /**
  * The AggregateAdd type describes a function that can be used to optimize a
@@ -172,8 +172,8 @@ export type Aggregate = (cells: Cell[], length: number) => ResultCell;
  * @since v2.0.0
  */
 export type AggregateAdd = (
-  current: Cell,
-  add: Cell,
+  current: ResultCell,
+  add: ResultCell,
   length: number,
 ) => ResultCellOrUndefined;
 
@@ -204,8 +204,8 @@ export type AggregateAdd = (
  * @since v2.0.0
  */
 export type AggregateRemove = (
-  current: Cell,
-  remove: Cell,
+  current: ResultCell,
+  remove: ResultCell,
   length: number,
 ) => ResultCellOrUndefined;
 
@@ -235,9 +235,9 @@ export type AggregateRemove = (
  * @since v2.0.0
  */
 export type AggregateReplace = (
-  current: Cell,
-  add: Cell,
-  remove: Cell,
+  current: ResultCell,
+  add: ResultCell,
+  remove: ResultCell,
   length: number,
 ) => ResultCellOrUndefined;
 
@@ -2055,7 +2055,7 @@ export type Having = {
    * @category Definition
    * @since v2.0.0
    */
-  (selectedOrGroupedCellId: Id, equals: Cell): void;
+  (selectedOrGroupedCellId: Id, equals: ResultCell): void;
   /**
    * Calling this function with one callback parameter is used to include only
    * those Rows which meet a calculated boolean condition.

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

@@ -19,7 +19,7 @@ import type {
   TableIdFromSchema,
 } from '../../_internal/store/with-schemas/index.d.ts';
 import type {Id, IdOrNull, Ids} from '../../common/with-schemas/index.d.ts';
-import type {GetIdChanges} from '../../store/index.d.ts';
+import type {Cell as BaseCell, GetIdChanges} from '../../store/index.d.ts';
 import type {
   Cell,
   CellOrUndefined,
@@ -124,7 +124,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * A ResultCell is typically accessed with the getResultCell method or
  * addResultCellListener method. It is similar to the Cell type in the store
  * module, but without schema-specific typing, and is a JavaScript string,
- * number, or boolean.
+ * number, boolean, null, object, or array.
  * @example
  * ```js
  * import type {ResultCell} from 'tinybase';
@@ -134,7 +134,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * @category Result
  * @since v2.0.0
  */
-export type ResultCell = string | number | boolean;
+export type ResultCell = BaseCell;
 
 /**
  * The ResultCellOrUndefined type is the data structure representing a single
@@ -833,6 +833,20 @@ export type QueriesListenerStats = {
    * @since v2.0.0
    */
   cell: number;
+  /**
+   * The number of ParamValuesListener functions registered with the Queries
+   * object.
+   * @category Stat
+   * @since v2.0.0
+   */
+  paramValues: number;
+  /**
+   * The number of ParamValueListener functions registered with the Queries
+   * object.
+   * @category Stat
+   * @since v7.2.0
+   */
+  paramValue: number;
 };
 
 /**

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

@@ -2,9 +2,9 @@
  * The schematizers module provides utilities for converting schemas from
  * popular validation libraries into TinyBase's schema format.
  *
- * Schematizers perform "best-effort" conversion, extracting basic type
- * information (string, number, boolean) and default values while discarding
- * complex validation rules that TinyBase doesn't support.
+ * Schematizers perform "best-effort" conversion, extracting basic type and
+ * type union, primitive enum and literal, and default information while
+ * discarding complex validation rules that TinyBase doesn't support.
  * @packageDocumentation
  * @module schematizers
  * @since v7.1.0
@@ -51,7 +51,9 @@ export interface Schematizer {
  * @param unwrapSchema - A function that unwraps a schema to extract the base
  * type, default value, nullable flag, and optional required flag. It should
  * recursively unwrap optional/nullable wrappers and return a tuple of
- * [schema, defaultValue, allowNull, required].
+ * [schema, defaultValue, allowNull, required]. The unwrapped schema should have
+ * either a supported `type` property, a non-empty `type` array containing
+ * supported types, or a non-empty `enum` property containing primitive values.
  * @param getProperties - A function that extracts the properties/entries/shape
  * from an object schema. Returns undefined if the schema is not an object.
  * @param getPropertyRequired - An optional function that extracts whether an

package/@types/schematizers/schematizer-arktype/index.d.ts

@@ -19,10 +19,10 @@ export interface ArkTypeSchematizer extends Schematizer {
  * The toTablesSchema method converts a mapping of ArkType object schemas into a
  * TinyBase TablesSchema.
  *
- * This method extracts basic type information (string, number, boolean),
- * string literals, default values, nullable flags, and required flags from
- * ArkType schemas. Complex validation rules like min/max, regex patterns,
- * refinements, and transforms are ignored.
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, default values, nullable flags, and
+ * required flags from ArkType schemas. Complex validation rules like min/max,
+ * regex patterns, refinements, and transforms are ignored.
  * @param schemas - A mapping of table IDs to ArkType object schemas.
  * @returns A TinyBase TablesSchema.
  * @example
@@ -57,8 +57,8 @@ export interface ArkTypeSchematizer extends Schematizer {
  * The toValuesSchema method converts a mapping of ArkType schemas into a
  * TinyBase ValuesSchema.
  *
- * This method extracts basic type information, string literals, default
- * values, and required flags from ArkType schemas.
+ * This method extracts basic type information and unions, primitive literal
+ * unions, default values, and required flags from ArkType schemas.
  * @param schemas - A mapping of value IDs to ArkType schemas.
  * @returns A TinyBase ValuesSchema.
  * @example

package/@types/schematizers/schematizer-arktype/with-schemas/index.d.ts

@@ -5,4 +5,115 @@
  * @module schematizer-arktype
  * @since v7.1.0
  */
-export type {ArkTypeSchematizer} from '../index.d.ts';
+import type {
+  TablesSchema,
+  ValuesSchema,
+} from '../../../store/with-schemas/index.d.ts';
+import type {Schematizer} from '../../with-schemas/index.d.ts';
+
+/**
+ * The ArkTypeSchematizer interface represents a schematizer specifically for
+ * converting ArkType schemas into TinyBase schemas.
+ * @category Schematizer
+ * @since v7.1.0
+ */
+export interface ArkTypeSchematizer extends Schematizer {
+  /**
+ * The toTablesSchema method converts a mapping of ArkType object schemas into a
+ * TinyBase TablesSchema.
+ *
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, default values, nullable flags, and
+ * required flags from ArkType schemas. Complex validation rules like min/max,
+ * regex patterns, refinements, and transforms are ignored.
+ * @param schemas - A mapping of table IDs to ArkType object schemas.
+ * @returns A TinyBase TablesSchema.
+ * @example
+ * This example converts ArkType schemas to TinyBase format.
+ *
+ * ```js
+ * import {type} from 'arktype';
+ * import {createStore} from 'tinybase';
+ * import {createArkTypeSchematizer} from 'tinybase/schematizers/schematizer-arktype';
+ *
+ * const schematizer = createArkTypeSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: type({
+ *     species: 'string',
+ *     age: 'number',
+ *     sold: type('boolean').default(false),
+ *   }),
+ * });
+ *
+ * const store = createStore().setTablesSchema(tablesSchema);
+ * store.setRow('pets', 'fido', {species: 'dog', age: 3});
+ * console.log(store.getRow('pets', 'fido'));
+ * // -> {species: 'dog', age: 3, sold: false}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toTablesSchema(schemas: {[tableId: string]: any}): TablesSchema;
+
+  /**
+ * The toValuesSchema method converts a mapping of ArkType schemas into a
+ * TinyBase ValuesSchema.
+ *
+ * This method extracts basic type information and unions, primitive literal
+ * unions, default values, and required flags from ArkType schemas.
+ * @param schemas - A mapping of value IDs to ArkType schemas.
+ * @returns A TinyBase ValuesSchema.
+ * @example
+ * This example converts ArkType value schemas.
+ *
+ * ```js
+ * import {type} from 'arktype';
+ * import {createStore} from 'tinybase';
+ * import {createArkTypeSchematizer} from 'tinybase/schematizers/schematizer-arktype';
+ *
+ * const schematizer = createArkTypeSchematizer();
+ *
+ * const valuesSchema = schematizer.toValuesSchema({
+ *   theme: type('string').default('light'),
+ *   count: 'number',
+ * });
+ *
+ * const store = createStore().setValuesSchema(valuesSchema);
+ * store.setValues({count: 1});
+ * console.log(store.getValues());
+ * // -> {theme: 'light', count: 1}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toValuesSchema(schemas: {[valueId: string]: any}): ValuesSchema;
+}
+
+/**
+ * The createArkTypeSchematizer function creates an ArkTypeSchematizer object
+ * that can convert ArkType schemas into TinyBase schemas.
+ *
+ * The schematizer is stateless and can be reused for multiple conversions.
+ * @returns A new ArkTypeSchematizer instance.
+ * @example
+ * This example creates an ArkType schematizer and uses it to convert schemas.
+ *
+ * ```js
+ * import {type} from 'arktype';
+ * import {createArkTypeSchematizer} from 'tinybase/schematizers/schematizer-arktype';
+ *
+ * const schematizer = createArkTypeSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: type({
+ *     species: 'string',
+ *   }),
+ * });
+ * console.log(tablesSchema);
+ * // -> {pets: {species: {type: 'string', required: true}}}
+ * ```
+ * @category Creation
+ * @since v7.1.0
+ */
+export function createArkTypeSchematizer(): ArkTypeSchematizer;

package/@types/schematizers/schematizer-effect/index.d.ts

@@ -19,12 +19,11 @@ export interface EffectSchematizer extends Schematizer {
  * The toTablesSchema method converts a mapping of Effect Schema struct schemas
  * into a TinyBase TablesSchema.
  *
- * This method extracts basic type information (string, number, boolean),
- * string literals, nullable flags, optional flags, and required flags from
- * Effect schemas. Default values are not supported as they exist in Effect's
- * runtime
- * transformations, not in the schema AST. Complex validation rules,
- * transformations, and refinements are ignored.
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, nullable flags, optional flags, and
+ * required flags from Effect schemas. Default values are not supported as they
+ * exist in Effect's runtime transformations, not in the schema AST. Complex
+ * validation rules, transformations, and refinements are ignored.
  * @param schemas - A mapping of table IDs to Effect Schema struct schemas.
  * @returns A TinyBase TablesSchema.
  * @example
@@ -59,11 +58,10 @@ export interface EffectSchematizer extends Schematizer {
  * The toValuesSchema method converts a mapping of Effect Schema schemas into a
  * TinyBase ValuesSchema.
  *
- * This method extracts basic type information (string, number, boolean),
- * string literals, nullable flags, optional flags, and required flags from
- * Effect schemas. Default values are not supported as they exist in Effect's
- * runtime
- * transformations, not in the schema AST.
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, nullable flags, optional flags, and
+ * required flags from Effect schemas. Default values are not supported as they
+ * exist in Effect's runtime transformations, not in the schema AST.
  * @param schemas - A mapping of value IDs to Effect Schema schemas.
  * @returns A TinyBase ValuesSchema.
  * @example

package/@types/schematizers/schematizer-effect/with-schemas/index.d.ts

@@ -5,4 +5,117 @@
  * @module schematizer-effect
  * @since v7.1.0
  */
-export type {EffectSchematizer, createEffectSchematizer} from '../index.d.ts';
+import type {
+  TablesSchema,
+  ValuesSchema,
+} from '../../../store/with-schemas/index.d.ts';
+import type {Schematizer} from '../../with-schemas/index.d.ts';
+
+/**
+ * The EffectSchematizer interface represents a schematizer specifically for
+ * converting Effect Schema schemas into TinyBase schemas.
+ * @category Schematizer
+ * @since v7.1.0
+ */
+export interface EffectSchematizer extends Schematizer {
+  /**
+ * The toTablesSchema method converts a mapping of Effect Schema struct schemas
+ * into a TinyBase TablesSchema.
+ *
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, nullable flags, optional flags, and
+ * required flags from Effect schemas. Default values are not supported as they
+ * exist in Effect's runtime transformations, not in the schema AST. Complex
+ * validation rules, transformations, and refinements are ignored.
+ * @param schemas - A mapping of table IDs to Effect Schema struct schemas.
+ * @returns A TinyBase TablesSchema.
+ * @example
+ * This example converts Effect Schema schemas to TinyBase format.
+ *
+ * ```js
+ * import {Boolean, Number, String, Struct} from 'effect/Schema';
+ * import {createStore} from 'tinybase';
+ * import {createEffectSchematizer} from 'tinybase/schematizers/schematizer-effect';
+ *
+ * const schematizer = createEffectSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: Struct({
+ *     species: String,
+ *     age: Number,
+ *     sold: Boolean,
+ *   }),
+ * });
+ *
+ * const store = createStore().setTablesSchema(tablesSchema);
+ * store.setRow('pets', 'fido', {species: 'dog', age: 3, sold: false});
+ * console.log(store.getRow('pets', 'fido'));
+ * // -> {species: 'dog', age: 3, sold: false}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toTablesSchema(schemas: {[tableId: string]: any}): TablesSchema;
+
+  /**
+ * The toValuesSchema method converts a mapping of Effect Schema schemas into a
+ * TinyBase ValuesSchema.
+ *
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive literal unions, nullable flags, optional flags, and
+ * required flags from Effect schemas. Default values are not supported as they
+ * exist in Effect's runtime transformations, not in the schema AST.
+ * @param schemas - A mapping of value IDs to Effect Schema schemas.
+ * @returns A TinyBase ValuesSchema.
+ * @example
+ * This example converts Effect Schema schemas to TinyBase values.
+ *
+ * ```js
+ * import {Boolean, Number} from 'effect/Schema';
+ * import {createStore} from 'tinybase';
+ * import {createEffectSchematizer} from 'tinybase/schematizers/schematizer-effect';
+ *
+ * const schematizer = createEffectSchematizer();
+ *
+ * const valuesSchema = schematizer.toValuesSchema({
+ *   open: Boolean,
+ *   employees: Number,
+ * });
+ *
+ * const store = createStore().setValuesSchema(valuesSchema);
+ * store.setValues({open: true, employees: 3});
+ * console.log(store.getValues());
+ * // -> {open: true, employees: 3}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toValuesSchema(schemas: {[valueId: string]: any}): ValuesSchema;
+}
+
+/**
+ * The createEffectSchematizer function creates an EffectSchematizer instance
+ * for converting Effect Schema schemas to TinyBase schemas.
+ * @returns A new EffectSchematizer instance.
+ * @example
+ * This example creates an Effect Schema schematizer.
+ *
+ * ```js
+ * import {String, Struct} from 'effect/Schema';
+ * import {createEffectSchematizer} from 'tinybase/schematizers/schematizer-effect';
+ *
+ * const schematizer = createEffectSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: Struct({
+ *     species: String,
+ *   }),
+ * });
+ *
+ * console.log(tablesSchema);
+ * // -> {pets: {species: {type: 'string', required: true}}}
+ * ```
+ * @category Creation
+ * @since v7.1.0
+ */
+export function createEffectSchematizer(): EffectSchematizer;

package/@types/schematizers/schematizer-typebox/index.d.ts

@@ -19,10 +19,10 @@ export interface TypeBoxSchematizer extends Schematizer {
  * The toTablesSchema method converts a mapping of TypeBox object schemas into a
  * TinyBase TablesSchema.
  *
- * This method extracts basic type information (string, number, boolean),
- * string enums, default values, nullable flags, and required flags from TypeBox
- * schemas. Complex validation rules like min/max, patterns, formats, and
- * custom validators are ignored.
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive enums and literals, default values, nullable flags,
+ * and required flags from TypeBox schemas. Complex validation rules like
+ * min/max, patterns, formats, and custom validators are ignored.
  * @param schemas - A mapping of table IDs to TypeBox object schemas.
  * @returns A TinyBase TablesSchema.
  * @example
@@ -57,9 +57,9 @@ export interface TypeBoxSchematizer extends Schematizer {
  * The toValuesSchema method converts a mapping of TypeBox schemas into a
  * TinyBase ValuesSchema.
  *
- * This method extracts basic type information (string, number, boolean),
- * string enums, default values, nullable flags, and required flags from TypeBox
- * schemas.
+ * This method extracts basic type information (string, number, boolean), basic
+ * type unions, primitive enums and literals, default values, nullable flags,
+ * and required flags from TypeBox schemas.
  * @param schemas - A mapping of value IDs to TypeBox schemas.
  * @returns A TinyBase ValuesSchema.
  * @example