tinybase 6.2.0-beta.2 → 6.2.0-beta.4

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

@@ -6,6 +6,8 @@
  * @since v1.0.0
  */
 
+import type {CellOrUndefined, ValueOrUndefined} from '../store/index.d.ts';
+
 /**
  * The Json type is a simple alias for a string, but is used to indicate that
  * the string should be considered to be a JSON serialization of an object.
@@ -93,6 +95,19 @@ export type GetNow = () => number;
  */
 export type Hlc = string;
 
+/**
+ * The Hash type is used within TinyBase (for example in the mergeable-store
+ * module) to quickly compare the content of two objects.
+ *
+ * This is simply an alias for a JavaScript `number`.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v6.2.0
+ */
+export type Hash = number;
+
 /**
  * The defaultSorter function is provided as a convenience to sort keys
  * alphanumerically, and can be provided to the `sliceIdSorter` and
@@ -280,3 +295,283 @@ export function getHlcFunctions(
   getLastCounter: () => number,
   getClientId: () => Id,
 ];
+
+/**
+ * The getHash function returns a deterministic hash of a string, which can be
+ * used to quickly compare the content of two entities.
+ *
+ * This is used internally within TinyBase (for example in the mergeable-store
+ * module) to quickly compare the content of two objects, but is also useful for
+ * applications that need to represent strings in a deterministic (though not
+ * cryptographically safe) way.
+ *
+ * The hash uses the Fowler–Noll–Vo hash approach, producing a JavaScript
+ * number. It is not guaranteed to be unique by any means, but small changes in
+ * input generally produce large changes in output, so it should be sufficient
+ * for most purposes.
+ * @param string The string to hash.
+ * @returns A hash of the string.
+ * @example
+ * This example gets the hash of two similar strings.
+ * ```js
+ * import {getHash} from 'tinybase';
+ * console.log(getHash('Hello, world!'));
+ * // -> 3985698964
+ * console.log(getHash('Hello, world?'));
+ * // -> 3549480870
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getHash(string: string): Hash;
+
+/**
+ * The addOrRemoveHash function combines two hashes together, which, because it
+ * is a simple alias for bitwise XOR, serves both as addition and removal of one
+ * hash from the other.
+ *
+ * This is used internally within TinyBase to collate hashes of objects, such as
+ * producing a hash for a Table which is composed of the hashes of its Rows.
+ * @param hash1 A first hash.
+ * @param hash2 A second hash to add or remove from the first.
+ * @returns The resulting hash of the two hashes added to or removed from each
+ * other.
+ * @example
+ * This example adds two hashes together.
+ * ```js
+ * import {addOrRemoveHash} from 'tinybase';
+ *
+ * const hash1 = 123456789;
+ * const hash2 = 987654321;
+ * console.log(addOrRemoveHash(hash1, hash2));
+ * // -> 1032168868
+ *
+ * console.log(addOrRemoveHash(1032168868, hash1));
+ * // -> 987654321
+ * console.log(addOrRemoveHash(1032168868, hash2));
+ * // -> 123456789
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function addOrRemoveHash(hash1: Hash, hash2: Hash): Hash;
+
+/**
+ * The getTablesHash function returns a hash for the tabular part of a Store,
+ * based on each Table Id and hash.
+ * @param tableHashes An object containing each Table Id and its hash.
+ * @returns A hash of the Tables.
+ * @example
+ * This example gets the hash of the tabular part of a Store.
+ * ```js
+ * import {getTablesHash} from 'tinybase';
+ *
+ * const tableHashes = {
+ *   pets: 4262151841, // hash of its contents
+ * };
+ *
+ * console.log(getTablesHash(tableHashes));
+ * // -> 278115833
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTablesHash(tableHashes: {[tableId: Id]: Hash}): Hash;
+
+/**
+ * The getTableInTablesHash function returns a hash for a single Table in a
+ * Store, based on its Id and hash (in turn produced from its Rows).
+ * @param tableId The Id of the Table.
+ * @param tableHash The hash of the Table.
+ * @returns A hash of the Table based on its content and Id.
+ * @example
+ * This example gets the hash of a Table and its Id.
+ * ```js
+ * import {getTableInTablesHash} from 'tinybase';
+ *
+ * const tableId = 'pets';
+ * const tableHash = 4262151841; // hash of its contents
+ *
+ * console.log(getTableInTablesHash(tableId, tableHash));
+ * // -> 278115833
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTableInTablesHash(tableId: Id, tableHash: Hash): Hash;
+
+/**
+ * The getTableHash function returns a hash for a single Table in a Store, based
+ * on each Row Id and hash.
+ * @param rowHashes An object containing each Row Id and its hash.
+ * @returns A hash of the Table.
+ * @example
+ * This example gets the hash of a Table.
+ * ```js
+ * import {getTableHash} from 'tinybase';
+ *
+ * const rowHashes = {
+ *   fido: 1810444343, // hash of its contents
+ * };
+ *
+ * console.log(getTableHash(rowHashes));
+ * // -> 4262151841
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTableHash(rowHashes: {[rowId: Id]: Hash}): Hash;
+
+/**
+ * The getRowInTableHash function returns a hash for a single Row in a Table,
+ * based on its Id and hash (in turn produced from its Cells).
+ * @param rowId The Id of the Row.
+ * @param rowHash The hash of the Row.
+ * @returns A hash of the Row based on its content and Id.
+ * @example
+ * This example gets the hash of a Row and its Id.
+ * ```js
+ * import {getRowInTableHash} from 'tinybase';
+ *
+ * const rowId = 'fido';
+ * const rowHash = 1810444343; // hash of its contents
+ *
+ * console.log(getRowInTableHash(rowId, rowHash));
+ * // -> 4262151841
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getRowInTableHash(rowId: Id, rowHash: Hash): Hash;
+
+/**
+ * The getRowHash function returns a hash for a single Row in a Table, based on
+ * each Cell Id and hash.
+ * @param cellHashes An object containing each Cell Id and its hash.
+ * @returns A hash of the Row.
+ * @example
+ * This example gets the hash of a Row.
+ * ```js
+ * import {getRowHash} from 'tinybase';
+ *
+ * const cellHashes = {
+ *   'species': 3002200796, // hash of 'dog' and '03E3B------mmxrx'
+ * };
+ *
+ * console.log(getRowHash(cellHashes));
+ * // -> 1810444343
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getRowHash(cellHashes: {[cellId: Id]: Hash}): Hash;
+
+/**
+ * The getCellInRowHash function returns a hash for a single Cell in a Row,
+ * based on its Id and hash (in turn produced from its value).
+ * @param cellId The Id of the Cell.
+ * @param cellHash The hash of the Cell.
+ * @returns A hash of the Cell based on its content and Id.
+ * @example
+ * This example gets the hash of a Cell and its Id.
+ * ```js
+ * import {getCellInRowHash} from 'tinybase';
+ *
+ * const cellId = 'species';
+ * const cellHash = '3002200796'; // hash of 'dog' and '03E3B------mmxrx'
+ *
+ * console.log(getCellInRowHash(cellId, cellHash));
+ * // -> 3777304796
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getCellInRowHash(cellId: Id, cellHash: Hash): Hash;
+
+/**
+ * The getCellHash function returns a hash for a single Cell, based on its value
+ * and the HLC of the Cell.
+ * @param cell The Cell's value (or `undefined`).
+ * @param cellHlc The HLC of the Cell.
+ * @returns A hash of the Cell.
+ * @example
+ * This example gets the hash of a Cell and its HLC.
+ * ```js
+ * import {getCellHash} from 'tinybase';
+ *
+ * const cell = 'dog';
+ * const cellHlc = '03E3B------mmxrx';
+ *
+ * console.log(getCellHash(cell, cellHlc));
+ * // -> 3002200796
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getCellHash(cell: CellOrUndefined, cellHlc: Hlc): Hash;
+
+/**
+ * The getValuesHash function returns a hash for a Values object, based on each
+ * Value Id and hash.
+ * @param valueHashes An object containing each Value Id and its hash.
+ * @returns A hash of the Values.
+ * @example
+ * This example gets the hash of a Values object.
+ * ```js
+ * import {getValuesHash} from 'tinybase';
+ *
+ * const valueHashes = {
+ *   meaningOfLife: 312420374, // hash of 42 and '03E3B------mmxrx'
+ * };
+ *
+ * console.log(getValuesHash(valueHashes));
+ * // -> 4229195646
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValuesHash(valueHashes: {[valueId: Id]: Hash}): Hash;
+
+/**
+ * The getValueInValuesHash function returns a hash for a single Value in a
+ * Values object, based on its Id and hash (in turn produced from its value).
+ * @param valueId The Id of the Value.
+ * @param valueHash The hash of the Value.
+ * @returns A hash of the Value based on its content and Id.
+ * @example
+ * This example gets the hash of a Value and its Id.
+ * ```js
+ * import {getValueInValuesHash} from 'tinybase';
+ *
+ * const valueId = 'meaningOfLife';
+ * const valueHash = 312420374; // hash of 42 and '03E3B------mmxrx'
+ *
+ * console.log(getValueInValuesHash(valueId, valueHash));
+ * // -> 330198963
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValueInValuesHash(valueId: Id, valueHash: Hash): Hash;
+
+/**
+ * The getValueHash function returns a hash for a single Value, based on its
+ * value and the HLC of the Value.
+ * @param value The Value (or `undefined`).
+ * @param valueHlc The HLC of the Value.
+ * @returns A hash of the Value.
+ * @example
+ * This example gets the hash of a Value and its HLC.
+ * ```js
+ * import {getValueHash} from 'tinybase';
+ *
+ * const value = 42;
+ * const valueHlc = '03E3B------mmxrx';
+ *
+ * console.log(getValueHash(value, valueHlc));
+ * // -> 312420374
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValueHash(value: ValueOrUndefined, valueHlc: Hlc): Hash;

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

@@ -6,6 +6,20 @@
  * @since v1.0.0
  */
 
+import type {
+  CellIdFromSchema,
+  TableIdFromSchema,
+  ValueIdFromSchema,
+} from '../../_internal/store/with-schemas/index.d.ts';
+import type {
+  CellOrUndefined,
+  NoTablesSchema,
+  NoValuesSchema,
+  OptionalTablesSchema,
+  OptionalValuesSchema,
+  ValueOrUndefined,
+} from '../../store/with-schemas/index.d.ts';
+
 /**
  * The Json type is a simple alias for a string, but is used to indicate that
  * the string should be considered to be a JSON serialization of an object.
@@ -93,6 +107,19 @@ export type GetNow = () => number;
  */
 export type Hlc = string;
 
+/**
+ * The Hash type is used within TinyBase (for example in the mergeable-store
+ * module) to quickly compare the content of two objects.
+ *
+ * This is simply an alias for a JavaScript `number`.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v6.2.0
+ */
+export type Hash = number;
+
 /**
  * The defaultSorter function is provided as a convenience to sort keys
  * alphanumerically, and can be provided to the `sliceIdSorter` and
@@ -280,3 +307,351 @@ export function getHlcFunctions(
   getLastCounter: () => number,
   getClientId: () => Id,
 ];
+
+/**
+ * The getHash function returns a deterministic hash of a string, which can be
+ * used to quickly compare the content of two entities.
+ *
+ * This is used internally within TinyBase (for example in the mergeable-store
+ * module) to quickly compare the content of two objects, but is also useful for
+ * applications that need to represent strings in a deterministic (though not
+ * cryptographically safe) way.
+ *
+ * The hash uses the Fowler–Noll–Vo hash approach, producing a JavaScript
+ * number. It is not guaranteed to be unique by any means, but small changes in
+ * input generally produce large changes in output, so it should be sufficient
+ * for most purposes.
+ * @param string The string to hash.
+ * @returns A hash of the string.
+ * @example
+ * This example gets the hash of two similar strings.
+ * ```js
+ * import {getHash} from 'tinybase';
+ * console.log(getHash('Hello, world!'));
+ * // -> 3985698964
+ * console.log(getHash('Hello, world?'));
+ * // -> 3549480870
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getHash(string: string): Hash;
+
+/**
+ * The addOrRemoveHash function combines two hashes together, which, because it
+ * is a simple alias for bitwise XOR, serves both as addition and removal of one
+ * hash from the other.
+ *
+ * This is used internally within TinyBase to collate hashes of objects, such as
+ * producing a hash for a Table which is composed of the hashes of its Rows.
+ * @param hash1 A first hash.
+ * @param hash2 A second hash to add or remove from the first.
+ * @returns The resulting hash of the two hashes added to or removed from each
+ * other.
+ * @example
+ * This example adds two hashes together.
+ * ```js
+ * import {addOrRemoveHash} from 'tinybase';
+ *
+ * const hash1 = 123456789;
+ * const hash2 = 987654321;
+ * console.log(addOrRemoveHash(hash1, hash2));
+ * // -> 1032168868
+ *
+ * console.log(addOrRemoveHash(1032168868, hash1));
+ * // -> 987654321
+ * console.log(addOrRemoveHash(1032168868, hash2));
+ * // -> 123456789
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function addOrRemoveHash(hash1: Hash, hash2: Hash): Hash;
+
+/**
+ * The getTablesHash function returns a hash for the tabular part of a Store,
+ * based on each Table Id and hash.
+ * @param tableHashes An object containing each Table Id and its hash.
+ * @returns A hash of the Tables.
+ * @example
+ * This example gets the hash of the tabular part of a Store.
+ * ```js
+ * import {getTablesHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getTablesHash(tableHashes: {[tableId: Id]: Hash}): Hash;
+ * ```
+ *
+ * const tableHashes = {
+ *   pets: 4262151841, // hash of its contents
+ * };
+ *
+ * console.log(getTablesHash(tableHashes));
+ * // -> 278115833
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTablesHash<
+  Schema extends OptionalTablesSchema = NoTablesSchema,
+>(tableHashes: {[TableId in TableIdFromSchema<Schema>]: Hash}): Hash;
+
+/**
+ * The getTableInTablesHash function returns a hash for a single Table in a
+ * Store, based on its Id and hash (in turn produced from its Rows).
+ * @param tableId The Id of the Table.
+ * @param tableHash The hash of the Table.
+ * @returns A hash of the Table based on its content and Id.
+ * @example
+ * This example gets the hash of a Table and its Id.
+ * ```js
+ * import {getTableInTablesHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getTableInTablesHash(tableId: Id, tableHash: Hash): Hash;
+ * ```
+ *
+ * const tableId = 'pets';
+ * const tableHash = 4262151841; // hash of its contents
+ *
+ * console.log(getTableInTablesHash(tableId, tableHash));
+ * // -> 278115833
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTableInTablesHash<
+  Schema extends OptionalTablesSchema = NoTablesSchema,
+>(tableId: TableIdFromSchema<Schema>, tableHash: Hash): Hash;
+
+/**
+ * The getTableHash function returns a hash for a single Table in a Store, based
+ * on each Row Id and hash.
+ * @param rowHashes An object containing each Row Id and its hash.
+ * @returns A hash of the Table.
+ * @example
+ * This example gets the hash of a Table.
+ * ```js
+ * import {getTableHash} from 'tinybase';
+ *
+ * const rowHashes = {
+ *   fido: 1810444343, // hash of its contents
+ * };
+ *
+ * console.log(getTableHash(rowHashes));
+ * // -> 4262151841
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getTableHash(rowHashes: {[rowId: Id]: Hash}): Hash;
+
+/**
+ * The getRowInTableHash function returns a hash for a single Row in a Table,
+ * based on its Id and hash (in turn produced from its Cells).
+ * @param rowId The Id of the Row.
+ * @param rowHash The hash of the Row.
+ * @returns A hash of the Row based on its content and Id.
+ * @example
+ * This example gets the hash of a Row and its Id.
+ * ```js
+ * import {getRowInTableHash} from 'tinybase';
+ *
+ * const rowId = 'fido';
+ * const rowHash = 1810444343; // hash of its contents
+ *
+ * console.log(getRowInTableHash(rowId, rowHash));
+ * // -> 4262151841
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getRowInTableHash(rowId: Id, rowHash: Hash): Hash;
+
+/**
+ * The getRowHash function returns a hash for a single Row in a Table, based on
+ * each Cell Id and hash.
+ * @param cellHashes An object containing each Cell Id and its hash.
+ * @returns A hash of the Row.
+ * @example
+ * This example gets the hash of a Row.
+ * ```js
+ * import {getRowHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getRowHash(cellHashes: {[cellId: Id]: Hash}): Hash;
+ * ```
+ *
+ * const cellHashes = {
+ *   'species': 3002200796, // hash of 'dog' and '03E3B------mmxrx'
+ * };
+ *
+ * console.log(getRowHash(cellHashes));
+ * // -> 1810444343
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getRowHash<
+  Schema extends OptionalTablesSchema = NoTablesSchema,
+  TableId extends TableIdFromSchema<Schema> = Id,
+>(cellHashes: {[CellId in CellIdFromSchema<Schema, TableId>]?: Hash}): Hash;
+
+/**
+ * The getCellInRowHash function returns a hash for a single Cell in a Row,
+ * based on its Id and hash (in turn produced from its value).
+ * @param cellId The Id of the Cell.
+ * @param cellHash The hash of the Cell.
+ * @returns A hash of the Cell based on its content and Id.
+ * @example
+ * This example gets the hash of a Cell and its Id.
+ * ```js
+ * import {getCellInRowHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getCellInRowHash(cellId: Id, cellHash: Hash): Hash;
+ * ```
+ *
+ * const cellId = 'species';
+ * const cellHash = '3002200796'; // hash of 'dog' and '03E3B------mmxrx'
+ *
+ * console.log(getCellInRowHash(cellId, cellHash));
+ * // -> 3777304796
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getCellInRowHash<
+  Schema extends OptionalTablesSchema = NoTablesSchema,
+  TableId extends TableIdFromSchema<Schema> = Id,
+>(cellId: CellIdFromSchema<Schema, TableId>, cellHash: Hash): Hash;
+
+/**
+ * The getCellHash function returns a hash for a single Cell, based on its value
+ * and the HLC of the Cell.
+ * @param cell The Cell's value (or `undefined`).
+ * @param cellHlc The HLC of the Cell.
+ * @returns A hash of the Cell.
+ * @example
+ * This example gets the hash of a Cell and its HLC.
+ * ```js
+ * import {getCellHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getCellHash(cell: CellOrUndefined, cellHlc: Hlc): Hash;
+ * ```
+ *
+ * const cell = 'dog';
+ * const cellHlc = '03E3B------mmxrx';
+ *
+ * console.log(getCellHash(cell, cellHlc));
+ * // -> 3002200796
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getCellHash<
+  Schema extends OptionalTablesSchema = NoTablesSchema,
+  TableId extends TableIdFromSchema<Schema> = Id,
+  CellId extends CellIdFromSchema<Schema, TableId> = Id,
+>(cell: CellOrUndefined<Schema, TableId, CellId>, cellHlc: Hlc): Hash;
+
+/**
+ * The getValuesHash function returns a hash for a Values object, based on each
+ * Value Id and hash.
+ * @param valueHashes An object containing each Value Id and its hash.
+ * @returns A hash of the Values.
+ * @example
+ * This example gets the hash of a Values object.
+ * ```js
+ * import {getValuesHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getValuesHash(valueHashes: {[valueId: Id]: Hash}): Hash;
+ * ```
+ *
+ * const valueHashes = {
+ *   meaningOfLife: 312420374, // hash of 42 and '03E3B------mmxrx'
+ * };
+ *
+ * console.log(getValuesHash(valueHashes));
+ * // -> 4229195646
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValuesHash<
+  Schema extends OptionalValuesSchema = NoValuesSchema,
+>(valueHashes: {[ValueId in ValueIdFromSchema<Schema>]?: Hash}): Hash;
+
+/**
+ * The getValueInValuesHash function returns a hash for a single Value in a
+ * Values object, based on its Id and hash (in turn produced from its value).
+ * @param valueId The Id of the Value.
+ * @param valueHash The hash of the Value.
+ * @returns A hash of the Value based on its content and Id.
+ * @example
+ * This example gets the hash of a Value and its Id.
+ * ```js
+ * import {getValueInValuesHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getValueInValuesHash(valueId: Id, valueHash: Hash): Hash;
+ * ```
+ *
+ * const valueId = 'meaningOfLife';
+ * const valueHash = 312420374; // hash of 42 and '03E3B------mmxrx'
+ *
+ * console.log(getValueInValuesHash(valueId, valueHash));
+ * // -> 330198963
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValueInValuesHash<
+  Schema extends OptionalValuesSchema = NoValuesSchema,
+>(valueId: ValueIdFromSchema<Schema>, valueHash: Hash): Hash;
+
+/**
+ * The getValueHash function returns a hash for a single Value, based on its
+ * value and the HLC of the Value.
+ * @param value The Value (or `undefined`).
+ * @param valueHlc The HLC of the Value.
+ * @returns A hash of the Value.
+ * @example
+ * This example gets the hash of a Value and its HLC.
+ * ```js
+ * import {getValueHash} from 'tinybase';
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * getValueHash(value: ValueOrUndefined, valueHlc: Hlc): Hash;
+ * ```
+ *
+ * const value = 42;
+ * const valueHlc = '03E3B------mmxrx';
+ *
+ * console.log(getValueHash(value, valueHlc));
+ * // -> 312420374
+ * ```
+ * @category Hash
+ * @since v6.2.0
+ */
+export function getValueHash<
+  Schema extends OptionalValuesSchema = NoValuesSchema,
+>(value: ValueOrUndefined<Schema, Id>, valueHlc: Hlc): Hash;