tinybase 8.5.0-beta.0 → 8.5.0-beta.1

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

@@ -0,0 +1,242 @@
+/**
+ * The ui-react-dom-charts module of the TinyBase project provides components
+ * to make it easy to create web-based reactive charts with Store and Queries
+ * objects.
+ *
+ * The components in this module use the react-dom module and so are not
+ * appropriate for environments like React Native (although those in the
+ * lower-level ui-react module are).
+ *
+ * For a full list of SVG class names that can be styled with CSS, see the
+ * Using Charts guide.
+ * @packageDocumentation
+ * @module ui-react-dom-charts
+ * @since v8.5.0
+ */
+import type {Id} from '../common/index.d.ts';
+import type {
+  ComponentReturnType,
+  QueriesOrQueriesId,
+  StoreOrStoreId,
+} from '../ui-react/index.d.ts';
+
+/**
+ * The ChartProps type describes the props that are used to configure the
+ * chart element that renders a chart.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartProps = {
+  /**
+   * An optional string that will be used as the class attribute of the chart's
+   * SVG element. This can be used as the root selector for styling chart
+   * internals, as shown in the Using Charts guide.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+};
+
+/**
+ * The ChartTableSourceProps type describes the props that bind a chart to a
+ * Table in a Store.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartTableSourceProps = {
+  /**
+   * The Id of the Table in the Store to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tableId: Id;
+  /**
+   * The Store to chart, or the Id of a Store that is registered with the
+   * Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly store?: StoreOrStoreId;
+  /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queryId?: never;
+  /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queries?: never;
+};
+
+/**
+ * The ChartQuerySourceProps type describes the props that bind a chart to a
+ * Query in a Queries object.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartQuerySourceProps = {
+  /**
+   * The Id of the query in the Queries object to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queryId: Id;
+  /**
+   * The Queries object to chart, or the Id of a Queries object that is
+   * registered with the Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queries?: QueriesOrQueriesId;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tableId?: never;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly store?: never;
+};
+
+/**
+ * The ChartBindingProps type describes the props that bind a chart to Cell
+ * values in TinyBase data.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartBindingProps = {
+  /**
+   * The Id of the Cell that provides each data point's x value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly xCellId: Id;
+  /**
+   * The Id of the Cell that provides each data point's y value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly yCellId: Id;
+  /**
+   * The Id of the Cell used to sort the charted rows.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly sortCellId?: Id;
+  /**
+   * Whether the charted rows should be sorted in descending order.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly descending?: boolean;
+  /**
+   * The number of sorted rows to skip before charting.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of sorted rows to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly limit?: number;
+};
+
+/**
+ * The LineChart component renders a line chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The LineChart component then renders an SVG chart from Cells in the
+ * `pets` Table.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {LineChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <LineChart
+ *       tableId="pets"
+ *       xCellId="order"
+ *       yCellId="sold"
+ *       className="sales"
+ *     />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {order: 1, sold: 12},
+ *   rabbits: {order: 2, sold: 9},
+ * });
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * console.log(app.firstChild?.getAttribute('class'));
+ * // -> 'sales'
+ * ```
+ */
+export function LineChart(
+  props: (ChartTableSourceProps | ChartQuerySourceProps) &
+    ChartBindingProps &
+    ChartProps,
+): ComponentReturnType;
+
+/**
+ * The BarChart component renders a bar chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Queries object and provides it through Provider
+ * context. The BarChart component then renders an SVG chart from Cells in the
+ * `bySpecies` query.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {BarChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <BarChart queryId="bySpecies" xCellId="species" yCellId="sold" />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {species: 'hamster', sold: 12},
+ *   rabbits: {species: 'rabbit', sold: 9},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'bySpecies',
+ *   'pets',
+ *   ({select}) => {
+ *     select('species');
+ *     select('sold');
+ *   },
+ * );
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * ```
+ */
+export function BarChart(
+  props: (ChartTableSourceProps | ChartQuerySourceProps) &
+    ChartBindingProps &
+    ChartProps,
+): ComponentReturnType;

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

@@ -0,0 +1,296 @@
+/**
+ * The ui-react-dom-charts module of the TinyBase project provides components
+ * to make it easy to create web-based reactive charts with Store and Queries
+ * objects.
+ *
+ * The components in this module use the react-dom module and so are not
+ * appropriate for environments like React Native (although those in the
+ * lower-level ui-react module are).
+ *
+ * For a full list of SVG class names that can be styled with CSS, see the
+ * Using Charts guide.
+ * @packageDocumentation
+ * @module ui-react-dom-charts
+ * @since v8.5.0
+ */
+import type {
+  CellIdFromSchema,
+  TableIdFromSchema,
+} from '../../_internal/store/with-schemas/index.d.ts';
+import type {ComponentReturnType} from '../../_internal/ui-react/with-schemas/index.d.ts';
+import type {
+  QueriesOrQueriesId,
+  StoreOrStoreId,
+} from '../../_internal/ui/with-schemas/index.d.ts';
+import type {Id} from '../../common/with-schemas/index.d.ts';
+import type {OptionalSchemas} from '../../store/with-schemas/index.d.ts';
+
+/**
+ * The ChartProps type describes the props that are used to configure the
+ * chart element that renders a chart.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartProps = {
+  /**
+   * An optional string that will be used as the class attribute of the chart's
+   * SVG element. This can be used as the root selector for styling chart
+   * internals, as shown in the Using Charts guide.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+};
+
+/**
+ * The ChartTableSourceProps type describes the props that bind a chart to a
+ * Table in a Store.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartTableSourceProps<
+  Schemas extends OptionalSchemas,
+  TableIds extends TableIdFromSchema<Schemas[0]> = TableIdFromSchema<
+    Schemas[0]
+  >,
+> = TableIds extends infer TableId
+  ? TableId extends TableIdFromSchema<Schemas[0]>
+    ? {
+        /**
+   * The Id of the Table in the Store to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+        readonly tableId: TableId;
+        /**
+   * The Store to chart, or the Id of a Store that is registered with the
+   * Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+        readonly store?: StoreOrStoreId<Schemas>;
+        /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+        readonly queryId?: never;
+        /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+        readonly queries?: never;
+      }
+    : never
+  : never;
+
+/**
+ * The ChartQuerySourceProps type describes the props that bind a chart to a
+ * Query in a Queries object.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartQuerySourceProps<Schemas extends OptionalSchemas> = {
+  /**
+   * The Id of the query in the Queries object to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queryId: Id;
+  /**
+   * The Queries object to chart, or the Id of a Queries object that is
+   * registered with the Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queries?: QueriesOrQueriesId<Schemas>;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tableId?: never;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly store?: never;
+};
+
+/**
+ * The ChartBindingProps type describes the props that bind a chart to Cell
+ * values in TinyBase data.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartBindingProps<CellId extends Id = Id> = {
+  /**
+   * The Id of the Cell that provides each data point's x value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly xCellId: CellId;
+  /**
+   * The Id of the Cell that provides each data point's y value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly yCellId: CellId;
+  /**
+   * The Id of the Cell used to sort the charted rows.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly sortCellId?: CellId;
+  /**
+   * Whether the charted rows should be sorted in descending order.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly descending?: boolean;
+  /**
+   * The number of sorted rows to skip before charting.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of sorted rows to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly limit?: number;
+};
+
+type ChartTableBindingProps<
+  Schemas extends OptionalSchemas,
+  TableIds extends TableIdFromSchema<Schemas[0]> = TableIdFromSchema<
+    Schemas[0]
+  >,
+> = TableIds extends infer TableId
+  ? TableId extends TableIdFromSchema<Schemas[0]>
+    ? ChartTableSourceProps<Schemas, TableId> &
+        ChartBindingProps<CellIdFromSchema<Schemas[0], TableId>>
+    : never
+  : never;
+
+/**
+ * The WithSchemas type provides a version of this module that is typed with
+ * schemas.
+ * @category Development
+ * @since v8.5.0
+ */
+export type WithSchemas<Schemas extends OptionalSchemas> = {
+  /**
+ * The LineChart component renders a line chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The LineChart component then renders an SVG chart from Cells in the
+ * `pets` Table.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * LineChart(
+ *   props: (ChartTableSourceProps | ChartQuerySourceProps) &
+ *     ChartBindingProps &
+ *     ChartProps,
+ * ): ComponentReturnType;
+ * ```
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {LineChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <LineChart
+ *       tableId="pets"
+ *       xCellId="order"
+ *       yCellId="sold"
+ *       className="sales"
+ *     />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {order: 1, sold: 12},
+ *   rabbits: {order: 2, sold: 9},
+ * });
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * console.log(app.firstChild?.getAttribute('class'));
+ * // -> 'sales'
+ * ```
+ */
+  LineChart: (
+    props:
+      | (ChartTableBindingProps<Schemas> & ChartProps)
+      | (ChartQuerySourceProps<Schemas> & ChartBindingProps & ChartProps),
+  ) => ComponentReturnType;
+
+  /**
+ * The BarChart component renders a bar chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Queries object and provides it through Provider
+ * context. The BarChart component then renders an SVG chart from Cells in the
+ * `bySpecies` query.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * BarChart(
+ *   props: (ChartTableSourceProps | ChartQuerySourceProps) &
+ *     ChartBindingProps &
+ *     ChartProps,
+ * ): ComponentReturnType;
+ * ```
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {BarChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <BarChart queryId="bySpecies" xCellId="species" yCellId="sold" />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {species: 'hamster', sold: 12},
+ *   rabbits: {species: 'rabbit', sold: 9},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'bySpecies',
+ *   'pets',
+ *   ({select}) => {
+ *     select('species');
+ *     select('sold');
+ *   },
+ * );
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * ```
+ */
+  BarChart: (
+    props:
+      | (ChartTableBindingProps<Schemas> & ChartProps)
+      | (ChartQuerySourceProps<Schemas> & ChartBindingProps & ChartProps),
+  ) => ComponentReturnType;
+};

package/common/index.js

@@ -2,15 +2,16 @@ const EMPTY_STRING = '';
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const math = Math;
 const getIfNotFunction = (predicate) => (value, then, otherwise) =>
   predicate(value)
     ? /* istanbul ignore next */
       otherwise?.()
     : then(value);
 const GLOBAL = globalThis;
-const math = Math;
 const mathMax = math.max;
 const mathFloor = math.floor;
+const mathRandom = math.random;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
 const isUndefined = (thing) => thing === void 0;
 const ifNotUndefined = getIfNotFunction(isUndefined);
@@ -38,7 +39,7 @@ const decode = (str, pos) => mapGet(DECODE, str[pos]) ?? 0;
 const getRandomValues = GLOBAL.crypto
   ? (array) => GLOBAL.crypto.getRandomValues(array)
   : /* istanbul ignore next */
-    (array) => arrayMap(array, () => mathFloor(math.random() * 256));
+    (array) => arrayMap(array, () => mathFloor(mathRandom() * 256));
 const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),

package/common/with-schemas/index.js

@@ -2,15 +2,16 @@ const EMPTY_STRING = '';
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const math = Math;
 const getIfNotFunction = (predicate) => (value, then, otherwise) =>
   predicate(value)
     ? /* istanbul ignore next */
       otherwise?.()
     : then(value);
 const GLOBAL = globalThis;
-const math = Math;
 const mathMax = math.max;
 const mathFloor = math.floor;
+const mathRandom = math.random;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
 const isUndefined = (thing) => thing === void 0;
 const ifNotUndefined = getIfNotFunction(isUndefined);
@@ -38,7 +39,7 @@ const decode = (str, pos) => mapGet(DECODE, str[pos]) ?? 0;
 const getRandomValues = GLOBAL.crypto
   ? (array) => GLOBAL.crypto.getRandomValues(array)
   : /* istanbul ignore next */
-    (array) => arrayMap(array, () => mathFloor(math.random() * 256));
+    (array) => arrayMap(array, () => mathFloor(mathRandom() * 256));
 const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),

package/index.js

@@ -42,16 +42,17 @@ const strEndsWith = (str, suffix) => str.endsWith(suffix);
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const math = Math;
 const getIfNotFunction = (predicate) => (value, then, otherwise) =>
   predicate(value)
     ? /* istanbul ignore next */
       otherwise?.()
     : then(value);
 const GLOBAL = globalThis;
-const math = Math;
 const mathMax = math.max;
 const mathMin = math.min;
 const mathFloor = math.floor;
+const mathRandom = math.random;
 const isFiniteNumber = isFinite;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
 const isNullish = (thing) => thing == null;
@@ -63,6 +64,7 @@ const ifNotNullish = getIfNotFunction(isNullish);
 const ifNotUndefined = getIfNotFunction(isUndefined);
 const isTypeStringOrBoolean = (type) => type == STRING || type == BOOLEAN;
 const isString = (thing) => getTypeOf(thing) == STRING;
+const isNumber = (thing) => getTypeOf(thing) == NUMBER;
 const isFunction = (thing) => getTypeOf(thing) == FUNCTION;
 const isArray = (thing) => Array.isArray(thing);
 const slice = (arrayOrString, start, end) => arrayOrString.slice(start, end);
@@ -785,7 +787,7 @@ const decode = (str, pos) => mapGet(DECODE, str[pos]) ?? 0;
 const getRandomValues = GLOBAL.crypto
   ? (array) => GLOBAL.crypto.getRandomValues(array)
   : /* istanbul ignore next */
-    (array) => arrayMap(array, () => mathFloor(math.random() * 256));
+    (array) => arrayMap(array, () => mathFloor(mathRandom() * 256));
 const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),
@@ -1191,7 +1193,7 @@ const stampValidate = (stamp, validateThing) =>
   isArray(stamp) &&
   size(stamp) == 3 &&
   isString(stamp[1]) &&
-  getTypeOf(stamp[2]) == NUMBER &&
+  isNumber(stamp[2]) &&
   isFiniteNumber(stamp[2]) &&
   validateThing(stamp[0]);
 

package/mergeable-store/index.js

@@ -35,15 +35,16 @@ const strEndsWith = (str, suffix) => str.endsWith(suffix);
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const math = Math;
 const getIfNotFunction = (predicate) => (value, then, otherwise) =>
   predicate(value)
     ? /* istanbul ignore next */
       otherwise?.()
     : then(value);
 const GLOBAL = globalThis;
-const math = Math;
 const mathMax = math.max;
 const mathFloor = math.floor;
+const mathRandom = math.random;
 const isFiniteNumber = isFinite;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
 const isNullish = (thing) => thing == null;
@@ -53,6 +54,7 @@ const ifNotNullish = getIfNotFunction(isNullish);
 const ifNotUndefined = getIfNotFunction(isUndefined);
 const isTypeStringOrBoolean = (type) => type == STRING || type == BOOLEAN;
 const isString = (thing) => getTypeOf(thing) == STRING;
+const isNumber = (thing) => getTypeOf(thing) == NUMBER;
 const isFunction = (thing) => getTypeOf(thing) == FUNCTION;
 const isArray = (thing) => Array.isArray(thing);
 const slice = (arrayOrString, start, end) => arrayOrString.slice(start, end);
@@ -307,7 +309,7 @@ const decode = (str, pos) => mapGet(DECODE, str[pos]) ?? 0;
 const getRandomValues = GLOBAL.crypto
   ? (array) => GLOBAL.crypto.getRandomValues(array)
   : /* istanbul ignore next */
-    (array) => arrayMap(array, () => mathFloor(math.random() * 256));
+    (array) => arrayMap(array, () => mathFloor(mathRandom() * 256));
 const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),
@@ -432,7 +434,7 @@ const stampValidate = (stamp, validateThing) =>
   isArray(stamp) &&
   size(stamp) == 3 &&
   isString(stamp[1]) &&
-  getTypeOf(stamp[2]) == NUMBER &&
+  isNumber(stamp[2]) &&
   isFiniteNumber(stamp[2]) &&
   validateThing(stamp[0]);