[docs] Documentation for Id reuse

Author: jamesgpearce

site/guides/10_releases.md

@@ -43,6 +43,11 @@ These are each described in the new TinyBase and TypeScript guide.
 Also in v3.1, the ORM-like type definition generation in the tools module has
 been extended to emit ui-react definitions.
 
+Finally, v3.0.1 adds a `reuseRowIds` parameter to the addRow method and the
+useAddRowCallback hook. It defaults to `true`, for backwards compatibility, but
+if set to `false`, new Row Ids will not be reused unless the whole Table is
+deleted.
+
 ## v3.0
 
 This major new release adds key/value store functionality to TinyBase. Alongside

src/types/docs/store.js

@@ -1957,8 +1957,17 @@
    * Row is added to the Table. However it is likely to be a string
    * representation of an increasing integer.
    *
+   * The `reuseRowIds` parameter defaults to `true`, which means that if you
+   * delete a Row and then add another, the Id will be re-used - unless you
+   * delete the entire Table, in which case all Row Ids will reset. Otherwise,
+   * if you specify `reuseRowIds` to be `false`, then the Id will be a
+   * monotonically increasing string representation of an increasing integer,
+   * regardless of any you may have previously deleted.
+   *
    * @param tableId The Id of the Table in the Store.
    * @param row The data of a single Row to be added.
+   * @param reuseRowIds Whether Ids should be recycled from previously deleted
+   * Row objects, defaulting to `true`.
    * @returns A reference to the Store.
    * @example
    * This example adds a single Row.

src/types/docs/ui-react.js

@@ -1443,6 +1443,13 @@
  * hook's `storeOrStoreId` parameter) is always automatically used as a hook
  * dependency for the callback.
  *
+ * The `reuseRowIds` parameter defaults to `true`, which means that if you
+ * delete a Row and then add another, the Id will be re-used - unless you delete
+ * the entire Table, in which case all Row Ids will reset. Otherwise, if you
+ * specify `reuseRowIds` to be `false`, then the Id will be a monotonically
+ * increasing string representation of an increasing integer, regardless of any
+ * you may have previously deleted.
+ *
  * @param tableId The Id of the Table in the Store.
  * @param getRow A function which returns the Row object that will be used to
  * update the Store, based on the parameter the callback will receive (and which
@@ -1458,6 +1465,9 @@
  * @param thenDeps An optional array of dependencies for the `then` function,
  * which, if any change, result in the regeneration of the callback. This
  * parameter defaults to an empty array.
+ * @param reuseRowIds Whether Ids should be recycled from previously deleted Row
+ * objects, defaulting to `true`.
+ *
  * @returns A parameterized callback for subsequent use.
  * @example
  * This example uses the useAddRowCallback hook to create an event handler which

src/types/store.d.ts

@@ -358,7 +358,7 @@ export interface Store {
   setRow(tableId: Id, rowId: Id, row: Row): Store;
 
   /// Store.addRow
-  addRow(tableId: Id, row: Row): Id | undefined;
+  addRow(tableId: Id, row: Row, reuseRowIds?: boolean): Id | undefined;
 
   /// Store.setPartialRow
   setPartialRow(tableId: Id, rowId: Id, partialRow: Row): Store;

src/types/ui-react.d.ts

@@ -174,6 +174,7 @@ export function useAddRowCallback<Parameter>(
   storeOrStoreId?: StoreOrStoreId,
   then?: (rowId: Id | undefined, store: Store, row: Row) => void,
   thenDeps?: React.DependencyList,
+  reuseRowIds?: boolean,
 ): ParameterizedCallback<Parameter>;
 
 /// useSetPartialRowCallback

src/types/with-schemas/store.d.ts

@@ -685,6 +685,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   addRow<TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId,
     row: Row<Schemas[0], TableId, true>,
+    reuseRowIds?: boolean,
   ): Id | undefined;
 
   /// Store.setPartialRow

src/types/with-schemas/ui-react.d.ts

@@ -256,6 +256,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
     then?: (rowId: Id | undefined, store: Store<Schemas>, row: AddRow) => void,
     thenDeps?: React.DependencyList,
+    reuseRowIds?: boolean,
   ) => ParameterizedCallback<Parameter>;
 
   /// useSetPartialRowCallback