feat(checkpoints): add useCheckpointIds composable

Author: nickmessing

Diff for: packages/private/docs/api/checkpoints/composables.md

@@ -1,6 +1,6 @@
 # Composables {#composables}
 
-Checkpoinnts composables.
+Checkpoints composables.
 
 ## useCheckpoint {#use-checkpoint}
 
@@ -20,15 +20,15 @@ When first accessed, this composable will create a listener so that changes to t
 
 ### Returns
 
-- `ComputedRef<string | undefined>`: A **readonly** reference to the string label for the requested checkpoint, an empty string if it was never set, or `undefined` if the checkpoint does not exist..
+- `ComputedRef<string | undefined>`: A **readonly** reference to the string label for the requested checkpoint, an empty string if it was never set, or `undefined` if the checkpoint does not exist.
 
 ### Example
 
 <div class="hide-default-store">
 
 ```vue
 <script setup lang="ts">
-import { useCell, injectStore, useCheckpoint } from 'vue-tinybase/custom-store'
+import { injectStore, injectCheckpoints, useCheckpoint } from 'vue-tinybase/custom-store'
 
 import { Store1Key, Checkpoints1Key } from './store'
 
@@ -54,7 +54,7 @@ checkpoints.addCheckpoint('sale')
 
 ```vue
 <script setup lang="ts">
-import { useCell, injectStore, useCheckpoint, injectCheckpoints } from 'vue-tinybase'
+import { injectStore, injectCheckpoints, useCheckpoint } from 'vue-tinybase'
 
 const store = injectStore()
 
@@ -74,3 +74,78 @@ checkpoints.addCheckpoint('sale')
 ```
 
 </div>
+
+## useCheckpointIds {#use-checkpoint-ids}
+
+The `useCheckpointIds` composable returns an array of the checkpoint [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) being managed by this [Checkpoints](https://tinybase.org/api/checkpoints/interfaces/checkpoints/checkpoints/) object, 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 checkpoint [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.
+
+<div class="hide-default-store">
+
+### Parameters
+
+- `checkpoints` ([`Checkpoints`](https://tinybase.org/api/checkpoints/interfaces/checkpoints/checkpoints/)): The [`Checkpoints`](https://tinybase.org/api/checkpoints/interfaces/checkpoints/checkpoints/) object to be accessed.
+
+</div>
+
+### Returns
+
+- `ComputedRef<`[`CheckpointIds`](https://tinybase.org/api/checkpoints/type-aliases/identity/checkpointids/)`>`: A **readonly** reference to the [CheckpointIds](https://tinybase.org/api/checkpoints/type-aliases/identity/checkpointids/) array, containing the checkpoint [Ids](https://tinybase.org/api/common/type-aliases/identity/ids/) managed by this [Checkpoints](https://tinybase.org/api/checkpoints/interfaces/checkpoints/checkpoints/) object.
+
+### Example
+
+<div class="hide-default-store">
+
+```vue
+<script setup lang="ts">
+import { injectStore, injectCheckpoints, useCheckpointIds } from 'vue-tinybase/custom-store'
+
+import { Store1Key, Checkpoints1Key } from './store'
+
+const store = injectStore(Store1Key)
+const checkpoints = injectCheckpoints(Checkpoints1Key)
+
+const checkpointIds = useCheckpointIds(checkpoints)
+// UI will show: [[],"0",[]]
+
+store.setCell('pets', 'fido', 'sold', true)
+// UI will show: [["0"],null,[]]
+
+checkpoints.addCheckpoint('sale')
+// UI will show: [["0"],"1",[]]
+</script>
+
+<template>
+  <div>{{ checkpointIds }}</div>
+</template>
+```
+
+</div>
+
+<div class="hide-custom-store">
+
+```vue
+<script setup lang="ts">
+import { injectStore, injectCheckpoints, useCheckpointIds } from 'vue-tinybase'
+
+const store = injectStore()
+
+const checkpoints = injectCheckpoints()
+
+const checkpointIds = useCheckpointIds()
+// UI will show: [[],"0",[]]
+
+store.setCell('pets', 'fido', 'sold', true)
+// UI will show: [["0"],null,[]]
+
+checkpoints.addCheckpoint('sale')
+// UI will show: [["0"],"1",[]]
+</script>
+
+<template>
+  <div>{{ checkpointIds }}</div>
+</template>
+```
+
+</div>

Diff for: packages/public/vue-tinybase/src/@types/custom-store/checkpoints/composables.ts

@@ -1,7 +1,20 @@
-import type { UseCheckpointFunction as UseCheckpointFunctionWithSchemas } from './with-schemas/composables.js'
-import type { UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas } from './without-schemas/composables.js'
+import type {
+  UseCheckpointFunction as UseCheckpointFunctionWithSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithSchemas,
+} from './with-schemas/composables.js'
+import type {
+  UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithoutSchemas,
+} from './without-schemas/composables.js'
 
 export type UseCheckpointFunction = UseCheckpointFunctionWithSchemas & UseCheckpointFunctionWithoutSchemas
+export type UseCheckpointIdsFunction = UseCheckpointIdsFunctionWithSchemas & UseCheckpointIdsFunctionWithoutSchemas
 
-export type { UseCheckpointFunction as UseCheckpointFunctionWithSchemas } from './with-schemas/composables.js'
-export type { UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas } from './without-schemas/composables.js'
+export type {
+  UseCheckpointFunction as UseCheckpointFunctionWithSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithSchemas,
+} from './with-schemas/composables.js'
+export type {
+  UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithoutSchemas,
+} from './without-schemas/composables.js'

Diff for: packages/public/vue-tinybase/src/@types/custom-store/checkpoints/with-schemas/composables.ts

@@ -1,7 +1,9 @@
 import type { ComputedRef, MaybeRefOrGetter } from '@vue/reactivity'
-import type { Checkpoints, Id } from 'tinybase/with-schemas'
+import type { Checkpoints, Id, CheckpointIds } from 'tinybase/with-schemas'
 
 export type UseCheckpointFunction = (
   checkpoints: Checkpoints<any>,
   checkpointId: MaybeRefOrGetter<Id>,
 ) => ComputedRef<string | undefined>
+
+export type UseCheckpointIdsFunction = (checkpoints: Checkpoints<any>) => ComputedRef<CheckpointIds>

Diff for: packages/public/vue-tinybase/src/@types/custom-store/checkpoints/without-schemas/composables.ts

@@ -1,7 +1,9 @@
 import type { ComputedRef, MaybeRefOrGetter } from '@vue/reactivity'
-import type { Checkpoints, Id } from 'tinybase'
+import type { CheckpointIds, Checkpoints, Id } from 'tinybase'
 
 export type UseCheckpointFunction = (
   checkpoints: Checkpoints,
   checkpointId: MaybeRefOrGetter<Id>,
 ) => ComputedRef<string | undefined>
+
+export type UseCheckpointIdsFunction = (checkpoints: Checkpoints) => ComputedRef<CheckpointIds>

Diff for: packages/public/vue-tinybase/src/@types/default-store/checkpoints/composables.ts

@@ -1,7 +1,20 @@
-import type { UseCheckpointFunction as UseCheckpointFunctionWithSchemas } from './with-schemas/composables.js'
-import type { UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas } from './without-schemas/composables.js'
+import type {
+  UseCheckpointFunction as UseCheckpointFunctionWithSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithSchemas,
+} from './with-schemas/composables.js'
+import type {
+  UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithoutSchemas,
+} from './without-schemas/composables.js'
 
 export type UseCheckpointFunction = UseCheckpointFunctionWithSchemas & UseCheckpointFunctionWithoutSchemas
+export type UseCheckpointIdsFunction = UseCheckpointIdsFunctionWithSchemas & UseCheckpointIdsFunctionWithoutSchemas
 
-export type { UseCheckpointFunction as UseCheckpointFunctionWithSchemas } from './with-schemas/composables.js'
-export type { UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas } from './without-schemas/composables.js'
+export type {
+  UseCheckpointFunction as UseCheckpointFunctionWithSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithSchemas,
+} from './with-schemas/composables.js'
+export type {
+  UseCheckpointFunction as UseCheckpointFunctionWithoutSchemas,
+  UseCheckpointIdsFunction as UseCheckpointIdsFunctionWithoutSchemas,
+} from './without-schemas/composables.js'

Diff for: packages/public/vue-tinybase/src/@types/default-store/checkpoints/with-schemas/composables.ts

@@ -1,4 +1,6 @@
 import type { ComputedRef, MaybeRefOrGetter } from '@vue/reactivity'
-import type { Id } from 'tinybase/with-schemas'
+import type { Id, CheckpointIds } from 'tinybase/with-schemas'
 
 export type UseCheckpointFunction = (checkpointId: MaybeRefOrGetter<Id>) => ComputedRef<string | undefined>
+
+export type UseCheckpointIdsFunction = () => ComputedRef<CheckpointIds>

Diff for: packages/public/vue-tinybase/src/@types/default-store/checkpoints/without-schemas/composables.ts

@@ -1,4 +1,6 @@
 import type { ComputedRef, MaybeRefOrGetter } from '@vue/reactivity'
-import type { Id } from 'tinybase'
+import type { Id, CheckpointIds } from 'tinybase'
 
 export type UseCheckpointFunction = (checkpointId: MaybeRefOrGetter<Id>) => ComputedRef<string | undefined>
+
+export type UseCheckpointIdsFunction = () => ComputedRef<CheckpointIds>

Diff for: packages/public/vue-tinybase/src/custom-store/checkpoints/composables.test.ts

@@ -3,7 +3,7 @@ import { createStore, createCheckpoints } from 'tinybase'
 import { expect, test } from 'vitest'
 import { defineComponent, h, nextTick } from 'vue'
 
-import { useCheckpoint } from './composables.js'
+import { useCheckpoint, useCheckpointIds } from './composables.js'
 
 test('[custom-store/checkpoints/composables] useCheckpoint', async () => {
   const store = createStore()
@@ -27,3 +27,26 @@ test('[custom-store/checkpoints/composables] useCheckpoint', async () => {
 
   expect(wrapper.text()).toBe('sale')
 })
+
+test('[custom-store/checkpoints/composables] useCheckpointIds', async () => {
+  const store = createStore()
+  const checkpoints = createCheckpoints(store)
+
+  const Component = defineComponent({
+    setup() {
+      const checkpoint = useCheckpointIds(checkpoints)
+
+      return () => h('div', [JSON.stringify(checkpoint.value)])
+    },
+  })
+
+  const wrapper = mount(Component)
+  expect(wrapper.text()).toBe('[[],"0",[]]')
+
+  store.setCell('pets', 'fido', 'sold', true)
+  checkpoints.addCheckpoint('sale')
+
+  await nextTick()
+
+  expect(wrapper.text()).toBe('[["0"],"1",[]]')
+})

Diff for: packages/public/vue-tinybase/src/custom-store/checkpoints/composables.ts

@@ -1,8 +1,11 @@
 import { ReturnType, useListenable } from '../../common/useListenable.js'
 
-import type { UseCheckpointFunction } from '../../@types/custom-store/index.js'
+import type { UseCheckpointFunction, UseCheckpointIdsFunction } from '../../@types/custom-store/index.js'
 import type { MaybeRefOrGetter } from '@vue/reactivity'
 import type { Checkpoints, Id } from 'tinybase'
 
 export const useCheckpoint = ((checkpoints: Checkpoints, checkpointId: MaybeRefOrGetter<Id>) =>
   useListenable(checkpoints, 'Checkpoint', ReturnType.CellOrValue, [checkpointId])) as UseCheckpointFunction
+
+export const useCheckpointIds = ((checkpoints: Checkpoints) =>
+  useListenable(checkpoints, 'CheckpointIds', ReturnType.Checkpoints)) as UseCheckpointIdsFunction

Diff for: packages/public/vue-tinybase/src/default-store/checkpoints/composables.test.ts

@@ -5,7 +5,7 @@ import { defineComponent, h, nextTick } from 'vue'
 
 import { providerWrapper } from '../../test-utils/store.js'
 
-import { useCheckpoint } from './composables.js'
+import { useCheckpoint, useCheckpointIds } from './composables.js'
 
 test('[default-store/checkpoints/composables] useCheckpoint', async () => {
   const store = createStore()
@@ -29,3 +29,26 @@ test('[default-store/checkpoints/composables] useCheckpoint', async () => {
 
   expect(wrapper.text()).toBe('sale')
 })
+
+test('[default-store/checkpoints/composables] useCheckpointIds', async () => {
+  const store = createStore()
+  const checkpoints = createCheckpoints(store)
+
+  const Component = defineComponent({
+    setup() {
+      const checkpoint = useCheckpointIds()
+
+      return () => h('div', [JSON.stringify(checkpoint.value)])
+    },
+  })
+
+  const wrapper = mount(providerWrapper(Component, undefined, { checkpoints }))
+  expect(wrapper.text()).toBe('[[],"0",[]]')
+
+  store.setCell('pets', 'fido', 'sold', true)
+  checkpoints.addCheckpoint('sale')
+
+  await nextTick()
+
+  expect(wrapper.text()).toBe('[["0"],"1",[]]')
+})

Diff for: packages/public/vue-tinybase/src/default-store/checkpoints/composables.ts

@@ -2,9 +2,12 @@ import { ReturnType, useListenable } from '../../common/useListenable.js'
 
 import { injectCheckpoints } from './context.js'
 
-import type { UseCheckpointFunction } from '../../@types/default-store/index.js'
+import type { UseCheckpointFunction, UseCheckpointIdsFunction } from '../../@types/default-store/index.js'
 import type { MaybeRefOrGetter } from '@vue/reactivity'
 import type { Id } from 'tinybase'
 
 export const useCheckpoint = ((checkpointId: MaybeRefOrGetter<Id>) =>
   useListenable(injectCheckpoints(), 'Checkpoint', ReturnType.CellOrValue, [checkpointId])) as UseCheckpointFunction
+
+export const useCheckpointIds = (() =>
+  useListenable(injectCheckpoints(), 'CheckpointIds', ReturnType.Checkpoints)) as UseCheckpointIdsFunction