tinybase 3.0.0-beta.0 → 3.0.0

package/lib/debug/tools.d.ts

@@ -10,7 +10,7 @@
  * @since v2.2.0
  */
 
-import {Schema, Store} from './store.d';
+import {Store, TablesSchema, ValuesSchema} from './store.d';
 import {Id} from './common.d';
 
 /**
@@ -36,6 +36,10 @@ export type StoreStats = {
    * Table objects.
    */
   totalCells: number;
+  /**
+   * The number of Value objects in the Store, since v3.0.0.
+   */
+  totalValues: number;
   /**
    * The string length of the Store when serialized to JSON.
    */
@@ -106,6 +110,7 @@ export type StoreStatsRowDetail = {
  * @since v2.2.0
  */
 export interface Tools {
+  /* eslint-disable max-len */
   /**
    * The getStoreStats method provides a set of statistics about the Store, and
    * is used for debugging purposes.
@@ -125,10 +130,11 @@ export interface Tools {
    *   .setTable('species', {
    *     dog: {price: 5},
    *     cat: {price: 4},
-   *   });
+   *   })
+   *   .setValues({open: true, employees: 3});
    * const tools = createTools(store);
    * console.log(tools.getStoreStats());
-   * // -> {totalTables: 2, totalRows: 5, totalCells: 8, jsonLength: 182}
+   * // -> {totalTables: 2, totalRows: 5, totalCells: 8, totalValues: 2, jsonLength: 212}
    * ```
    * @example
    * This example creates a Tools object and gets detailed statistics about it.
@@ -162,24 +168,27 @@ export interface Tools {
    * @since v2.2.0
    */
   getStoreStats(detail?: boolean): StoreStats;
+  /* eslint-enable max-len */
 
   /**
-   * The getStoreSchema method returns the Schema of the Store as an object.
+   * The getStoreTablesSchema method returns the TablesSchema of the Store as an
+   * object.
    *
-   * If the Store does not already have an explicit Schema associated with it,
-   * the data in the Store will be scanned to attempt to infer a new Schema.
+   * If the Store does not already have an explicit TablesSchema associated with
+   * it, the data in the Store will be scanned to attempt to infer a new
+   * TablesSchema.
    *
    * To be successful, this requires all the values of a given Cell across a
-   * Table object's  Row objects to have a consistent type. If a given Cell Id
+   * Table object's Row objects to have a consistent type. If a given Cell Id
    * appears in every Row, then a `default` for that Cell is specified in the
-   * Schema, based on the most common value found.
+   * TablesSchema, based on the most common value found.
    *
-   * @returns A Schema object for the Store.
+   * @returns A TablesSchema object for the Store.
    * @example
-   * This example creates a Tools object and gets basic statistics about a Store
-   * that already has a Schema.
+   * This example creates a Tools object and gets the schema of a Store that
+   * already has a TablesSchema.
    * ```js
-   * const store = createStore().setSchema({
+   * const store = createStore().setTablesSchema({
    *   pets: {
    *     species: {type: 'string'},
    *     color: {type: 'string'},
@@ -188,13 +197,13 @@ export interface Tools {
    *     price: {type: 'number'},
    *   },
    * });
-   * const schema = createTools(store).getStoreSchema();
+   * const schema = createTools(store).getStoreTablesSchema();
    * console.log(schema.pets);
    * // -> {species: {type: 'string'}, color: {type: 'string'}}
    * ```
    * @example
-   * This example creates a Tools object and gets basic statistics about a Store
-   * that doesn't already have a Schema.
+   * This example creates a Tools object and infers the schema of a Store that
+   * doesn't already have a TablesSchema.
    * ```js
    * const store = createStore()
    *   .setTable('pets', {
@@ -206,7 +215,7 @@ export interface Tools {
    *     dog: {price: 5, barks: true},
    *     cat: {price: 4, purrs: true},
    *   });
-   * const schema = createTools(store).getStoreSchema();
+   * const schema = createTools(store).getStoreTablesSchema();
    * console.log(schema.pets.species);
    * // -> {type: 'string', default: 'dog'}
    * console.log(schema.pets.color);
@@ -219,18 +228,57 @@ export interface Tools {
    * // -> {type: 'boolean'}
    * ```
    * @category Modelling
-   * @since v2.2.0
+   * @since v3.0.0
    */
-  getStoreSchema(): Schema;
+  getStoreTablesSchema(): TablesSchema;
+
+  /**
+   * The getStoreValuesSchema method returns the ValuesSchema of the Store as an
+   * object.
+   *
+   * If the Store does not already have an explicit ValuesSchema associated with
+   * it, the data in the Store will be scanned to infer a new ValuesSchema,
+   * based on the types of the Values present. Note that, unlike the inference
+   * of Cell values in the TablesSchema, it is not able to determine whether a
+   * Value should have a default or not.
+   *
+   * @returns A ValuesSchema object for the Store.
+   * @example
+   * This example creates a Tools object and gets the schema of a Store that
+   * already has a ValuesSchema.
+   * ```js
+   * const store = createStore().setValuesSchema({
+   *   open: {type: 'boolean', default: true},
+   *   employees: {type: 'number'},
+   * });
+   *
+   * const schema = createTools(store).getStoreValuesSchema();
+   * console.log(schema);
+   * // -> {open: {type: 'boolean', default: true}, employees: {type: 'number'}}
+   * ```
+   * @example
+   * This example creates a Tools object and infers the schema of a Store that
+   * doesn't already have a ValuesSchema.
+   * ```js
+   * const store = createStore().setValues({open: true, employees: 3});
+   * const schema = createTools(store).getStoreValuesSchema();
+   *
+   * console.log(schema);
+   * // -> {open: {type: 'boolean'}, employees: {type: 'number'}}
+   * ```
+   * @category Modelling
+   * @since v3.0.0
+   */
+  getStoreValuesSchema(): ValuesSchema;
 
   /**
    * The getStoreApi method returns a code-generated .d.ts file and a .ts file
    * that describe the schema of a Store in an ORM style.
    *
-   * If the Store does not already have an explicit Schema associated with it,
-   * the data in the Store will be scanned to attempt to infer a new Schema. The
-   * method returns two strings (which should be saved as files) though if no
-   * schema can be inferred, the strings will be empty.
+   * If the Store does not already have an explicit TablesSchema associated with
+   * it, the data in the Store will be scanned to attempt to infer a new
+   * TablesSchema. The method returns two strings (which should be saved as
+   * files) though if no schema can be inferred, the strings will be empty.
    *
    * The method takes a single argument which represents the name you want the
    * generated store object to have in code. You are expected to save the files
@@ -278,9 +326,9 @@ export interface Tools {
    * `.ts` files.
    * @example
    * This example creates a Tools object and generates code for a Store that
-   * already has a Schema.
+   * already has a TablesSchema.
    * ```js
-   * const store = createStore().setSchema({
+   * const store = createStore().setTablesSchema({
    *   pets: {
    *     price: {type: 'number'},
    *   },
@@ -294,12 +342,12 @@ export interface Tools {
    * // -> 'export type PetsRow = {\'price\'?: number;};'
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[40]);
+   * console.log(tsLines[41]);
    * // -> 'getPetsTable: (): PetsTable => store.getTable(PETS) as PetsTable,'
    * ```
    * @example
    * This example creates a Tools object and generates code for a Store that
-   * doesn't already have a Schema.
+   * doesn't already have a TablesSchema.
    * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {price: 5},
@@ -314,7 +362,7 @@ export interface Tools {
    * // -> 'export type PetsRow = {\'price\': number;};'
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[42]);
+   * console.log(tsLines[43]);
    * // -> 'getPetsTable: (): PetsTable => store.getTable(PETS) as PetsTable,'
    * ```
    * @category Modelling
@@ -349,9 +397,9 @@ export interface Tools {
    * `.ts` files.
    * @example
    * This example creates a Tools object and generates code for a Store that
-   * already has a Schema.
+   * already has a TablesSchema.
    * ```js
-   * const store = createStore().setSchema({
+   * const store = createStore().setTablesSchema({
    *   pets: {
    *     price: {type: 'number'},
    *   },
@@ -360,18 +408,18 @@ export interface Tools {
    * const [dTs, ts] = await tools.getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
-   * console.log(dTsLines[14]);
+   * console.log(dTsLines[5]);
    * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
-   * console.log(dTsLines[19]);
+   * console.log(dTsLines[10]);
    * // -> 'export type PetsRow = {price?: number};'
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[73]);
+   * console.log(tsLines[72]);
    * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
    * ```
    * @example
    * This example creates a Tools object and generates code for a Store that
-   * doesn't already have a Schema.
+   * doesn't already have a TablesSchema.
    * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {price: 5},
@@ -381,21 +429,42 @@ export interface Tools {
    * const [dTs, ts] = await tools.getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
-   * console.log(dTsLines[14]);
+   * console.log(dTsLines[5]);
    * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
-   * console.log(dTsLines[19]);
+   * console.log(dTsLines[10]);
    * // -> 'export type PetsRow = {price: number};'
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[75]);
+   * console.log(tsLines[74]);
    * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
    * ```
    * @category Modelling
    * @since v2.2.0
    */
   getPrettyStoreApi(storeName: string): Promise<[string, string]>;
+
+  /**
+   * The getStore method returns a reference to the underlying Store that is
+   * backing this Tools object.
+   *
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Tools object against a newly-created Store and
+   * then gets its reference in order to update its data.
+   *
+   * ```js
+   * const tools = createTools(createStore());
+   * tools.getStore().setCell('species', 'dog', 'price', 5);
+   * console.log(tools.getStoreStats().totalCells);
+   * // -> 1
+   * ```
+   * @category Getter
+   * @since v3.0.0
+   */
+  getStore(): Store;
 }
 
+/* eslint-disable max-len */
 /**
  * The createTools function creates a Tools object, and is the main entry point
  * into the tools module.
@@ -419,10 +488,11 @@ export interface Tools {
  *   .setTable('species', {
  *     dog: {price: 5},
  *     cat: {price: 4},
- *   });
+ *   })
+ *   .setValues({open: true, employees: 3});
  * const tools = createTools(store);
  * console.log(tools.getStoreStats());
- * // -> {totalTables: 2, totalRows: 5, totalCells: 8, jsonLength: 182}
+ * // -> {totalTables: 2, totalRows: 5, totalCells: 8, totalValues: 2, jsonLength: 212}
  * ```
  * @example
  * This example creates a Tools object, and calls the method a second time
@@ -439,3 +509,4 @@ export interface Tools {
  * @since v2.2.0
  */
 export function createTools(store: Store): Tools;
+/* eslint-enable max-len */