tinybase 5.0.0-beta.2 → 5.0.0-beta.21

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

@@ -0,0 +1,509 @@
+/**
+ * The mergeable-store module
+ * @packageDocumentation
+ * @module mergeable-store
+ * @since v5.0.0
+ */
+
+import type {
+  CellIdFromSchema,
+  TableIdFromSchema,
+  ValueIdFromSchema,
+} from '../../_internal/store/with-schemas/index.d.cts';
+import type {
+  CellOrUndefined,
+  Content,
+  NoSchemas,
+  NoTablesSchema,
+  NoValuesSchema,
+  OptionalSchemas,
+  OptionalTablesSchema,
+  OptionalValuesSchema,
+  Store,
+  TablesSchema,
+  ValueOrUndefined,
+  ValuesSchema,
+} from '../../store/with-schemas/index.d.cts';
+import type {Id} from '../../common/with-schemas/index.d.cts';
+
+/**
+ * The Hash type
+ * @category Stamps
+ */
+export type Hash = number;
+
+/**
+ * The Time type
+ * @category Stamps
+ */
+export type Time = string;
+
+/**
+ * The Stamp type
+ * @category Stamps
+ */
+export type Stamp<Thing, Hashed extends boolean = false> = Hashed extends true
+  ? [thing: Thing, time: Time, hash: Hash]
+  : [thing: Thing, time?: Time];
+
+// ContentHashes
+export type ContentHashes = [tablesHash: Hash, valuesHash: Hash];
+
+// TablesStamp
+export type TablesStamp<
+  Schema extends OptionalTablesSchema,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [TableId in TableIdFromSchema<Schema>]?: TableStamp<
+      Schema,
+      TableId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// TableHashes
+export type TableHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: Hash;
+};
+
+// TableStamp
+export type TableStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<{[rowId: Id]: RowStamp<Schema, TableId, Hashed>}, Hashed>;
+
+// RowHashes
+export type RowHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: {[rowId: Id]: Hash};
+};
+
+// RowStamp
+export type RowStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [CellId in CellIdFromSchema<Schema, TableId>]?: CellStamp<
+      Schema,
+      TableId,
+      CellId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// CellHashes
+export type CellHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: {
+    [rowId: Id]: {[CellId in CellIdFromSchema<Schema, TableId>]?: Hash};
+  };
+};
+
+// CellStamp
+export type CellStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellId extends CellIdFromSchema<Schema, TableId>,
+  Hashed extends boolean = false,
+> = Stamp<CellOrUndefined<Schema, TableId, CellId>, Hashed>;
+
+// ValuesStamp
+export type ValuesStamp<
+  Schema extends OptionalValuesSchema,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [ValueId in ValueIdFromSchema<Schema>]?: ValueStamp<
+      Schema,
+      ValueId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// ValuesHashes
+export type ValuesHashes<Schema extends OptionalValuesSchema> = {
+  [ValueId in ValueIdFromSchema<Schema>]?: Hash;
+};
+
+// ValueStamp
+export type ValueStamp<
+  Schema extends OptionalValuesSchema,
+  ValueId extends ValueIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<ValueOrUndefined<Schema, ValueId>, Hashed>;
+
+/**
+ * The MergeableContent type
+ * @category Mergeable
+ */
+export type MergeableContent<Schemas extends OptionalSchemas> = [
+  mergeableTables: TablesStamp<Schemas[0], true>,
+  mergeableValues: ValuesStamp<Schemas[1], true>,
+];
+
+/**
+ * The MergeableChanges type
+ * @category Mergeable
+ */
+export type MergeableChanges<Schemas extends OptionalSchemas> = [
+  mergeableTables: TablesStamp<Schemas[0]>,
+  mergeableValues: ValuesStamp<Schemas[1]>,
+  isChanges: 1,
+];
+
+/**
+ * The MergeableStore type
+ * @category Mergeable
+ */
+export interface MergeableStore<Schemas extends OptionalSchemas>
+  extends Store<Schemas> {
+  //
+  /**
+   * The getMergeableContent method
+   * @category Getter
+   */
+  getMergeableContent(): MergeableContent<Schemas>;
+
+  /**
+   * The getMergeableContentHashes method
+   * @category Syncing
+   */
+  getMergeableContentHashes(): ContentHashes;
+
+  /**
+   * The getMergeableTableHashes method
+   * @category Syncing
+   */
+  getMergeableTableHashes(): TableHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableTableDiff method
+   * @category Syncing
+   */
+  getMergeableTableDiff(
+    relativeTo: TableHashes<Schemas[0]>,
+  ): [
+    newTables: TablesStamp<Schemas[0]>,
+    differentTableHashes: TableHashes<Schemas[0]>,
+  ];
+
+  /**
+   * The getMergeableRowHashes method
+   * @category Syncing
+   */
+  getMergeableRowHashes(
+    otherTableHashes: TableHashes<Schemas[0]>,
+  ): RowHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableRowDiff method
+   * @category Syncing
+   */
+  getMergeableRowDiff(
+    otherTableRowHashes: RowHashes<Schemas[0]>,
+  ): [
+    newRows: TablesStamp<Schemas[0]>,
+    differentRowHashes: RowHashes<Schemas[0]>,
+  ];
+
+  /**
+   * The getMergeableCellHashes method
+   * @category Syncing
+   */
+  getMergeableCellHashes(
+    otherTableRowHashes: RowHashes<Schemas[0]>,
+  ): CellHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableCellDiff method
+   * @category Syncing
+   */
+  getMergeableCellDiff(
+    otherTableRowCellHashes: CellHashes<Schemas[0]>,
+  ): TablesStamp<Schemas[0]>;
+
+  /**
+   * The getMergeableValuesHashes method
+   * @category Syncing
+   */
+  getMergeableValuesHashes(): ValuesHashes<Schemas[1]>;
+
+  /**
+   * The getMergeableValueDiff method
+   * @category Syncing
+   */
+  getMergeableValueDiff(
+    relativeTo: ValuesHashes<Schemas[1]>,
+  ): ValuesStamp<Schemas[1]>;
+
+  /**
+   * The setMergeableContent method
+   * @category Setter
+   */
+  setMergeableContent(
+    mergeableContent: MergeableContent<Schemas>,
+  ): MergeableStore<Schemas>;
+
+  /**
+   * The setDefaultContent method
+   * @category Setter
+   */
+  setDefaultContent(content: Content<Schemas>): MergeableStore<Schemas>;
+
+  /**
+   * The getTransactionMergeableChanges method
+   * @category Getter
+   */
+  getTransactionMergeableChanges(): MergeableChanges<Schemas>;
+
+  /**
+   * The applyMergeableChanges method
+   * @category Setter
+   */
+  applyMergeableChanges(
+    mergeableChanges: MergeableChanges<Schemas> | MergeableContent<Schemas>,
+  ): MergeableStore<Schemas>;
+
+  /**
+   * The merge method
+   * @category Setter
+   */
+  merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
+
+  /**
+   * The isMergeable methods lets you know if the Store is mergeable.
+   *
+   * This will always be false for a Store, and true for a MergeableStore.
+   * @category Information
+   * @since v5.0.0
+   */
+  isMergeable: () => boolean;
+
+  /**
+   * The setTablesSchema method lets you specify the TablesSchema of the tabular
+   * part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, or Cell objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * TablesSchema with the delTablesSchema method.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema of a Store after it has been created.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTablesSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setTablesSchema<TS extends TablesSchema>(
+    tablesSchema: TS,
+  ): MergeableStore<[typeof tablesSchema, Schemas[1]]>;
+
+  /**
+   * The setValuesSchema method lets you specify the ValuesSchema of the keyed
+   * Values part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Values are removed. These changes will fire any
+   * listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * ValuesSchema with the delValuesSchema method.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the ValuesSchema of a Store after it has been created.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setValuesSchema({
+   *   open: {type: 'boolean', default: false},
+   * });
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setValuesSchema<VS extends ValuesSchema>(
+    valuesSchema: VS,
+  ): MergeableStore<[Schemas[0], typeof valuesSchema]>;
+
+  /**
+   * The setSchema method lets you specify the TablesSchema and ValuesSchema of
+   * the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, Cell, or Value objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * From v3.0 onwards, this method takes two arguments. The first is the
+   * TablesSchema object, the second the ValuesSchema. In previous versions
+   * (before the existence of the ValuesSchema data structure), only the first
+   * was present. For backwards compatibility the new second parameter is
+   * optional.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema and ValuesSchema of a Store after it has
+   * been created.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setSchema(
+   *   {
+   *     pets: {
+   *       species: {type: 'string'},
+   *       sold: {type: 'boolean', default: false},
+   *     },
+   *   },
+   *   {open: {type: 'boolean', default: false}},
+   * );
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @example
+   * This example sets just the TablesSchema of a Store after it has been
+   * created.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   */
+  setSchema<TS extends TablesSchema, VS extends ValuesSchema>(
+    tablesSchema: TS,
+    valuesSchema?: VS,
+  ): MergeableStore<
+    [
+      typeof tablesSchema,
+      Exclude<ValuesSchema, typeof valuesSchema> extends never
+        ? NoValuesSchema
+        : NonNullable<typeof valuesSchema>,
+    ]
+  >;
+
+  /**
+   * The delTablesSchema method lets you remove the TablesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema of a Store.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTablesSchema({
+   *   pets: {species: {type: 'string'}},
+   * });
+   * store.delTablesSchema();
+   * console.log(store.getTablesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   */
+  delTablesSchema<
+    ValuesSchema extends OptionalValuesSchema = Schemas[1],
+  >(): MergeableStore<[NoTablesSchema, ValuesSchema]>;
+
+  /**
+   * The delValuesSchema method lets you remove the ValuesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the ValuesSchema of a Store.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setValuesSchema({
+   *   sold: {type: 'boolean', default: false},
+   * });
+   * store.delValuesSchema();
+   * console.log(store.getValuesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delValuesSchema<
+    TablesSchema extends OptionalTablesSchema = Schemas[0],
+  >(): MergeableStore<[TablesSchema, NoValuesSchema]>;
+
+  /**
+   * The delSchema method lets you remove both the TablesSchema and ValuesSchema
+   * of the Store.
+   *
+   * Prior to v3.0, this method removed the TablesSchema only.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema and ValuesSchema of a Store.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore()
+   *   .setTablesSchema({
+   *     pets: {species: {type: 'string'}},
+   *   })
+   *   .setValuesSchema({
+   *     sold: {type: 'boolean', default: false},
+   *   });
+   * store.delSchema();
+   * console.log(store.getSchemaJson());
+   * // -> '[{},{}]'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delSchema(): MergeableStore<NoSchemas>;
+}
+
+/**
+ * The createMergeableStore function
+ * @category Creation
+ */
+export function createMergeableStore(uniqueId?: Id): MergeableStore<NoSchemas>;