feat(store): add useSortedRowIds composable

Author: nickmessing

packages/private/docs/api/store/composables.md

@@ -875,6 +875,92 @@ store.setCell('pets', 'felix', 'color', 'black')
 
 </div>
 
+## useSortedRowIds {#use-sorted-row-ids}
+
+The `useSortedRowIds` composable returns a **readonly** reference to the sorted (and optionally, paginated) [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) of every [Row](https://tinybase.org/api/store/type-aliases/store/row/) in a given [Table](https://tinybase.org/api/store/type-aliases/store/table/), and registers a listener so that any changes to that result will cause a re-render.
+
+When first accessed, this composable will create a listener so that changes to the sorted [Row](https://tinybase.org/api/store/type-aliases/store/row/) [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) will cause a re-render. When the component containing this composable is unmounted, the listener will be automatically removed.
+
+### Parameters
+
+<div class="hide-default-store">
+
+- `store` ([`Store`](https://tinybase.org/api/store/interfaces/store/store/)): The store to listen to.
+
+</div>
+
+- `tableId` ([`MaybeRefOrGetter`](https://vuejs.org/api/utility-types.html#maybereforgetter)`<string>`): The [Id](https://tinybase.org/api/common/type-aliases/identity/id/) of the [Table](https://tinybase.org/api/store/type-aliases/store/table/) in the [Store](https://tinybase.org/api/store/interfaces/store/store/).
+
+- `cellId`<span class="blue">?</span> ([`MaybeRefOrGetter`](https://vuejs.org/api/utility-types.html#maybereforgetter)`<string | undefined>`): The [Id](https://tinybase.org/api/common/type-aliases/identity/id/) of the [Cell](https://tinybase.org/api/store/type-aliases/store/cell/) whose values are used for the sorting, or `undefined` to by sort the [Row](https://tinybase.org/api/store/type-aliases/store/row/) [Id](https://tinybase.org/api/common/type-aliases/identity/id/) itself.
+
+- `descending`<span class="blue">?</span> ([`MaybeRefOrGetter`](https://vuejs.org/api/utility-types.html#maybereforgetter)`<boolean | undefined>`): Whether the sorting should be in descending order.
+
+- `offset`<span class="blue">?</span> ([`MaybeRefOrGetter`](https://vuejs.org/api/utility-types.html#maybereforgetter)`<number | undefined>`): The number of [Row](https://tinybase.org/api/store/type-aliases/store/row/) [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) to skip for pagination purposes, if any.
+
+- `limit`<span class="blue">?</span> ([`MaybeRefOrGetter`](https://vuejs.org/api/utility-types.html#maybereforgetter)`<number | undefined>`): The maximum number of [Row](https://tinybase.org/api/store/type-aliases/store/row/) [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) to return, or undefined for all.
+
+### Returns
+
+- `ComputedRef<`[`Ids`](https://tinybase.org/api/common/type-aliases/identity/ids/)`>`: A **readonly** reference to an array of the sorted Ids of every Row in the Table.
+
+### Example
+
+```ts
+// store
+export const store = createStore().setTables({
+  pets: {
+    fido: { species: 'dog' },
+    felix: { species: 'cat' },
+  },
+})
+```
+
+<div class="hide-default-store">
+
+```vue
+<script setup lang="ts">
+import { useSortedRowIds, injectStore } from 'vue-tinybase/custom-store'
+
+import { Store1Key } from './store'
+
+const store = injectStore(Store1Key)
+
+const rowIds = useSortedRowIds('pets', 'species', false, 0, undefined, store)
+// UI will show: ["felix", "fido"]
+
+store.setRow('pets', 'cujo', { species: 'wolf' })
+// UI will show: ["felix", "fido", "cujo"]
+</script>
+
+<template>
+  <div>{{ rowIds }}</div>
+</template>
+```
+
+</div>
+
+<div class="hide-custom-store">
+
+```vue
+<script setup lang="ts">
+import { useSortedRowIds, injectStore } from 'vue-tinybase'
+
+const store = injectStore()
+
+const rowIds = useSortedRowIds('pets', 'species', false, 0, undefined)
+// UI will show: ["felix", "fido"]
+
+store.setRow('pets', 'cujo', { species: 'wolf' })
+// UI will show: ["felix", "fido", "cujo"]
+</script>
+
+<template>
+  <div>{{ rowIds }}</div>
+</template>
+```
+
+</div>
+
 ## useTable {#use-table}
 
 The `useTable` composable returns a **readonly** reference to an object containing the data of a single [Table](https://tinybase.org/api/store/type-aliases/store/table/) in a [Store](https://tinybase.org/api/store/interfaces/store/store/), and registers a listener so that any changes to that result will cause a re-render.

packages/public/vue-tinybase/src/custom-store/store/composables/index.ts

@@ -1,19 +1,20 @@
-export { useHasCell } from './useHasCell.js'
-export { useHasTableCell } from './useHasTableCell.js'
-export { useHasValues } from './useHasValues.js'
-export { useRowIds } from './useRowIds.js'
-export { useTableIds } from './useTableIds.js'
-export { useValueIds } from './useValueIds.js'
 export { useCell } from './useCell.js'
-export { useHasRow } from './useHasRow.js'
-export { useHasTables } from './useHasTables.js'
-export { useRow } from './useRow.js'
-export { useTable } from './useTable.js'
-export { useTables } from './useTables.js'
-export { useValues } from './useValues.js'
 export { useCellIds } from './useCellIds.js'
+export { useHasCell } from './useHasCell.js'
+export { useHasRow } from './useHasRow.js'
 export { useHasTable } from './useHasTable.js'
+export { useHasTables } from './useHasTables.js'
+export { useHasTableCell } from './useHasTableCell.js'
 export { useHasValue } from './useHasValue.js'
+export { useHasValues } from './useHasValues.js'
+export { useRow } from './useRow.js'
 export { useRowCount } from './useRowCount.js'
+export { useRowIds } from './useRowIds.js'
+export { useSortedRowIds } from './useSortedRowIds.js'
+export { useTable } from './useTable.js'
 export { useTableCellIds } from './useTableCellIds.js'
+export { useTableIds } from './useTableIds.js'
+export { useTables } from './useTables.js'
 export { useValue } from './useValue.js'
+export { useValueIds } from './useValueIds.js'
+export { useValues } from './useValues.js'

packages/public/vue-tinybase/src/custom-store/store/composables/useSortedRowIds.ts

@@ -0,0 +1,45 @@
+import { toRef } from '@vue/reactivity'
+
+import { useReactiveComposable } from '../../../utils/useReactiveComposable.js'
+import { onSortedRowIdsChange } from '../events/onSortedRowIdsChange.js'
+
+import type { AnyStore, ExtractTablesSchemaFromStore } from '../../../types.js'
+import type { MaybeRefOrGetter } from '@vue/reactivity'
+import type { Ids } from 'tinybase/with-schemas/common'
+import type { CellIdFromSchema, TableIdFromSchema } from 'tinybase/with-schemas/internal/store'
+
+export function useSortedRowIds<
+  Store extends AnyStore,
+  TableId extends TableIdFromSchema<ExtractTablesSchemaFromStore<Store>>,
+>(
+  store: Store,
+  tableId: MaybeRefOrGetter<TableId>,
+  cellId?: MaybeRefOrGetter<CellIdFromSchema<ExtractTablesSchemaFromStore<Store>, TableId> | undefined>,
+  descending?: MaybeRefOrGetter<boolean | undefined>,
+  offset?: MaybeRefOrGetter<number | undefined>,
+  limit?: MaybeRefOrGetter<number | undefined>,
+) {
+  const tableIdRef = toRef(tableId)
+  const cellIdRef = toRef(cellId)
+  const descendingRef = toRef(descending)
+  const offsetRef = toRef(offset)
+  const limitRef = toRef(limit)
+
+  return useReactiveComposable<Ids>({
+    getData: () => store.getSortedRowIds(tableIdRef.value),
+    listener: ({ loadData }) =>
+      onSortedRowIdsChange(
+        store,
+        tableIdRef as any,
+        cellIdRef,
+        descendingRef,
+        offsetRef,
+        limitRef,
+        (_store, _tableId, _cellId, _descending, _offset, _limit, sortedRowIds) => loadData(sortedRowIds),
+        false,
+        {
+          immediate: false,
+        },
+      ),
+  })
+}

packages/public/vue-tinybase/src/custom-store/store/events/onSortedRowIdsChange.ts

@@ -12,8 +12,8 @@ export function onSortedRowIdsChange<
   Store extends AnyStore,
   TableId extends TableIdFromSchema<ExtractTablesSchemaFromStore<Store>>,
   CellIdOrUndefined extends CellIdFromSchema<ExtractTablesSchemaFromStore<Store>, TableId> | undefined,
-  Descending extends boolean,
-  Offset extends number,
+  Descending extends boolean | undefined,
+  Offset extends number | undefined,
   Limit extends number | undefined,
 >(
   store: Store,
@@ -22,7 +22,14 @@ export function onSortedRowIdsChange<
   descending: MaybeRefOrGetter<Descending>,
   offset: MaybeRefOrGetter<Offset>,
   limit: MaybeRefOrGetter<Limit>,
-  listener: SortedRowIdsListener<ExtractSchemasFromStore<Store>, TableId, CellIdOrUndefined, Descending, Offset, Limit>,
+  listener: SortedRowIdsListener<
+    ExtractSchemasFromStore<Store>,
+    TableId,
+    CellIdOrUndefined,
+    Descending extends undefined ? false : Descending,
+    Offset extends undefined ? 0 : Offset,
+    Limit
+  >,
   mutator?: MaybeRefOrGetter<boolean>,
   options?: UseListenerOptions,
 ) {
@@ -32,8 +39,8 @@ export function onSortedRowIdsChange<
       store.addSortedRowIdsListener(
         toValue(tableId),
         toValue(cellId),
-        toValue(descending),
-        toValue(offset),
+        toValue(descending) ?? false,
+        toValue(offset) ?? 0,
         toValue(limit),
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         listener as any,

packages/public/vue-tinybase/src/store/composables/index.ts

@@ -1,19 +1,20 @@
-export { useHasCell } from './useHasCell.js'
-export { useHasTableCell } from './useHasTableCell.js'
-export { useHasValues } from './useHasValues.js'
-export { useRowIds } from './useRowIds.js'
-export { useTableIds } from './useTableIds.js'
-export { useValueIds } from './useValueIds.js'
 export { useCell } from './useCell.js'
-export { useHasRow } from './useHasRow.js'
-export { useHasTables } from './useHasTables.js'
-export { useRow } from './useRow.js'
-export { useTable } from './useTable.js'
-export { useTables } from './useTables.js'
-export { useValues } from './useValues.js'
 export { useCellIds } from './useCellIds.js'
+export { useHasCell } from './useHasCell.js'
+export { useHasRow } from './useHasRow.js'
 export { useHasTable } from './useHasTable.js'
+export { useHasTables } from './useHasTables.js'
+export { useHasTableCell } from './useHasTableCell.js'
 export { useHasValue } from './useHasValue.js'
+export { useHasValues } from './useHasValues.js'
+export { useRow } from './useRow.js'
 export { useRowCount } from './useRowCount.js'
+export { useRowIds } from './useRowIds.js'
+export { useSortedRowIds } from './useSortedRowIds.js'
+export { useTable } from './useTable.js'
 export { useTableCellIds } from './useTableCellIds.js'
+export { useTableIds } from './useTableIds.js'
+export { useTables } from './useTables.js'
 export { useValue } from './useValue.js'
+export { useValueIds } from './useValueIds.js'
+export { useValues } from './useValues.js'

packages/public/vue-tinybase/src/store/composables/useSortedRowIds.ts

@@ -0,0 +1,17 @@
+import { injectStore } from '../../context/injectStore.js'
+import { useSortedRowIds as useSortedRowIdsCS } from '../../custom-store/store/composables/useSortedRowIds.js'
+
+import type { DefaultStore, DefaultStoreTablesSchema } from '../../types.js'
+import type { ComputedRef, MaybeRefOrGetter } from '@vue/reactivity'
+import type { Ids } from 'tinybase/with-schemas/common'
+import type { CellIdFromSchema, TableIdFromSchema } from 'tinybase/with-schemas/internal/store'
+
+export function useSortedRowIds<TableId extends TableIdFromSchema<DefaultStoreTablesSchema>>(
+  tableId: MaybeRefOrGetter<TableId>,
+  cellId?: MaybeRefOrGetter<CellIdFromSchema<DefaultStoreTablesSchema, TableId> | undefined>,
+  descending?: MaybeRefOrGetter<boolean | undefined>,
+  offset?: MaybeRefOrGetter<number | undefined>,
+  limit?: MaybeRefOrGetter<number | undefined>,
+): ComputedRef<Ids> {
+  return useSortedRowIdsCS<DefaultStore, TableId>(injectStore(), tableId, cellId, descending, offset, limit)
+}