musora-content-services 2.162.1 → 2.163.0

package/.agent/decisions/2026-05-19-content-progress-ts-part-2.md

@@ -0,0 +1,53 @@
+---
+date: 2026-05-19
+branch: refactor/content-progress-ts-part-2
+pr: https://github.com/railroadmedia/musora-content-services/pull/978
+status: open
+tags: [[chore]]
+---
+
+# Split progress module into typed sub-modules with Progress namespace
+
+## Context
+
+`src/services/progress/index.ts` started as a flat file during the initial migration of `contentProgress.js` to TypeScript. As the migration continued it became clear the file would grow significantly, mixing query helpers, read operations, collection queries, and shared types. Naming also conflicted with the legacy JS exports still living in `contentProgress.js` during the transition.
+
+## Decision
+
+Split `progress/index.ts` into focused sub-modules:
+
+- `state.ts` — point queries for progress state, playback position, last interacted
+- `collections.ts` — bulk queries (allStarted, allCompleted, allStartedOrCompleted)
+- `types.ts` — shared interfaces (GetAllQueryOptions, QueryMetadata, StartedOrCompletedOptions)
+- `internal/queries.ts` — private DB helpers (getById, getByIds, getByRecordIds)
+
+`index.ts` becomes a 5-line file that spreads both modules into a `Progress` namespace object:
+
+```ts
+export const Progress = { ...state, ...collections }
+```
+
+**Naming convention: nouns for reads, verbs for writes.**
+Query functions drop their `get`/`find`/`getAll` prefixes since the namespace provides context (`Progress.state`, `Progress.allStarted`). Write operations not yet migrated will keep verb names when they land (`Progress.recordWatchSession`, `Progress.markCompleted`).
+
+`resumeTimeByIds` was renamed to `playbackPositionByIds` — `resumeTime` read as a verb phrase in camelCase and was semantically ambiguous.
+
+`navigate-to.ts` updated to consume `Progress.*` instead of named imports from the old flat index.
+
+## Alternatives Considered
+
+**Drop `get` prefix only (standalone names):** Rejected because `findIncompleteLesson` has a `find` prefix with semantic meaning (sync local search, not a DB fetch). Mixing bare nouns with `find*` names produces an inconsistent surface. The namespace approach sidesteps the verb question entirely.
+
+**Nested read/write namespace (`Progress.get.*` / `Progress.set.*`):** Cleaner separation on paper but adds nesting for what is currently a read-only module. The simpler convention (nouns=reads, verbs=writes in flat namespace) was chosen to avoid premature structure.
+
+## Process Notes
+
+- `getByIds` and `getById` in `internal/queries.ts` originally had `collection` as the second parameter. The user's linter moved it to last as an optional param — this required updating all call sites in `state.ts` and cascading arg-order fixes in navigate-to.ts and tests.
+- LSP diagnostics repeatedly fired false positives after the param reorder, claiming `string` was not assignable to `CollectionParameter`. `npx tsc --noEmit` was consistently the source of truth — all those diagnostics were stale cache.
+- `findIncompleteLesson` param order was changed by the linter to `(progressOnItems, contentType, currentContentId?)` — both `navigate-to.ts` and the test file required arg-order updates.
+
+## Consequences
+
+- External callers import `Progress` and call `Progress.state(id)`, `Progress.allStarted()`, etc. — no ambiguity with `contentProgress.js` exports during the remaining migration
+- Write operations remain in `contentProgress.js` until a follow-up PR migrates them into the `Progress` namespace with verb names
+- The `internal/` directory convention signals private helpers not intended for direct import outside the progress module

package/.claude/settings.local.json

@@ -1,41 +1,12 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npx jest *)",
-      "Bash(npx tsc *)",
-      "Skill(counselors)",
-      "Bash(counselors ls *)",
-      "Bash(counselors groups *)",
-      "Bash(counselors run *)",
+      "Bash(rg:*)",
+      "Bash(npm run lint:*)",
+      "Bash(ls:*)",
       "Bash(npm test *)",
-      "Bash(gh pr *)",
-      "Bash(gh api *)",
-      "Bash(mkdir -p /tmp/pr-review-v2)",
-      "Read(//tmp/pr-review-v2/**)",
-      "Bash(cat /home/alesevero/railenvironment/applications/musora-content-services/AGENTS.md)",
-      "Bash(echo \"no AGENTS.md\")",
-      "Bash(echo \"exit=$?\")",
-      "Bash(git checkout *)",
-      "Skill(pr)",
-      "Skill(create-decision)"
-    ]
-  },
-  "model": "sonnet",
-  "effortLevel": "medium",
-  "enabledMcpjsonServers": [
-    "atlassian",
-    "figma",
-    "google-workspace",
-    "snowflake",
-    "aws",
-    "hex",
-    "sanity",
-    "mysql",
-    "slack",
-    "langfuse",
-    "chrome-devtools",
-    "railway",
-    "github",
-    "asana"
-  ]
+      "Bash(npx jest *)"
+    ],
+    "deny": []
+  }
 }

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.163.0](https://github.com/railroadmedia/musora-content-services/compare/v2.162.1...v2.163.0) (2026-06-04)
+
+
+### Features
+
+* add need access logic branch for LPs ([#993](https://github.com/railroadmedia/musora-content-services/issues/993)) ([1d935aa](https://github.com/railroadmedia/musora-content-services/commit/1d935aaf147b45cd01bc1d438424f5322991aa69))
+* **TP-1195:** optimize live event loading ([#971](https://github.com/railroadmedia/musora-content-services/issues/971)) ([8daa616](https://github.com/railroadmedia/musora-content-services/commit/8daa6160c5bc1ee005093719beef1dd9e83ac3c8))
+
+
+### Bug Fixes
+
+* dont set resume-time to null ([#992](https://github.com/railroadmedia/musora-content-services/issues/992)) ([d7f0f3e](https://github.com/railroadmedia/musora-content-services/commit/d7f0f3e6aab53dcb332a9c149dd0a33f95bc1d75))
+
 ### [2.162.1](https://github.com/railroadmedia/musora-content-services/compare/v2.162.0...v2.162.1) (2026-06-04)
 
 ## [2.162.0](https://github.com/railroadmedia/musora-content-services/compare/v2.161.4...v2.162.0) (2026-06-03)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.162.1",
+  "version": "2.163.0",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",

package/src/contentTypeConfig.js

@@ -695,7 +695,9 @@ export let contentTypeConfig = {
     }`,
   ],
   'new-and-scheduled': {
-    fields: ['show_in_new_feed', isLiveField()],
+    fields: [
+      'show_in_new_feed',
+    ],
     includeChildFields: true,
   },
 }

package/src/lib/sanity/decorators/examples.ts

@@ -212,7 +212,7 @@ export async function navigateToParallelWithProgress() {
 
   const items = navigateRows as ContentWithNavAndProgress[]
   const decorators: FieldDecoratorAsync<ContentWithNavAndProgress>[] = [
-    navigateToDecorator as FieldDecoratorAsync<ContentWithNavAndProgress>,
+    navigateToDecorator() as FieldDecoratorAsync<ContentWithNavAndProgress>,
     {
       field: 'progress_percent',
       compute: (item) => fetchProgress(item.id),

package/src/lib/sanity/decorators/navigate-to.ts

@@ -1,15 +1,10 @@
 import { decorateAllAsync, type Decoratable, type FieldDecoratorAsync } from './base'
-import {
-  findIncompleteLesson,
-  getLastInteractedOf,
-  getProgressState,
-  getProgressStateByIds,
-} from '../../../services/contentProgress.js'
 import {
   COLLECTION_TYPE,
   CollectionParameter,
   STATE,
 } from '../../../services/sync/models/ContentProgress'
+import { Progress } from '@/services/progress'
 
 export const NAVIGATE_TO_FIELD = 'navigateTo' as const
 
@@ -18,7 +13,7 @@ const NAVIGABLE_TYPES = [
   'guided-course',
   'course-collection',
   'song-tutorial',
-  'learning-path-v2',
+  COLLECTION_TYPE.LEARNING_PATH,
   'skill-pack',
 ] as const
 
@@ -68,38 +63,66 @@ function buildNavigateTo(
   }
 }
 
-async function computeNavigateTo(content: NavigateToDecoratable): Promise<NavigateTo | null> {
+interface NavigateContext {
+  states: Map<number, string>
+}
+
+async function prefetchStates(items: NavigateToDecoratable[]): Promise<NavigateContext> {
+  const ids = new Set<number>()
+  for (const item of items) {
+    if (!item || !NAVIGABLE_TYPES.includes(item.type as (typeof NAVIGABLE_TYPES)[number])) continue
+    ids.add(item.id)
+    for (const child of item.children ?? []) {
+      ids.add(child.id)
+      if (TWO_DEPTH_TYPES.includes(item.type)) {
+        for (const grandchild of child.children ?? []) {
+          ids.add(grandchild.id)
+        }
+      }
+    }
+  }
+  if (ids.size === 0) return { states: new Map() }
+  const states = await Progress.stateByIds(Array.from(ids))
+  return { states }
+}
+
+async function computeNavigateTo(
+  content: NavigateToDecoratable,
+  ctx?: NavigateContext
+): Promise<NavigateTo | null> {
   if (!NAVIGABLE_TYPES.includes(content.type as (typeof NAVIGABLE_TYPES)[number])) return null
 
   const children = content.children
   if (!children || children.length === 0) return null
 
-  const contentState = await getProgressState(content.id)
+  const contentState = ctx?.states.get(content.id) ?? (await Progress.state(content.id))
   if (contentState !== STATE.STARTED) {
     const firstChild = children[0]
     const childNav = TWO_DEPTH_TYPES.includes(content.type)
-      ? await computeNavigateTo(firstChild)
+      ? await computeNavigateTo(firstChild, ctx)
       : null
     return buildNavigateTo(firstChild, childNav)
   }
 
   const childrenIds = children.map((c) => c.id)
   const childrenById = new Map(children.map((c) => [c.id, c]))
-  const childrenStates = (await getProgressStateByIds(childrenIds)) as Map<number, STATE>
-  const lastInteractedId = (await getLastInteractedOf(childrenIds)) as number
+  const childrenStates = ctx
+    ? new Map(childrenIds.map((id) => [id, ctx.states.get(id) ?? '']))
+    : await Progress.stateByIds(childrenIds)
+  const lastInteractedId = await Progress.lastInteractedOf(childrenIds)
 
   if (COURSE_FLOW_TYPES.includes(content.type)) {
     const lastInteractedStatus = childrenStates.get(lastInteractedId)
     const targetId =
       lastInteractedStatus === STATE.STARTED
         ? lastInteractedId
-        : findIncompleteLesson(childrenStates, lastInteractedId, content.type)
+        : Progress.incompleteLesson(childrenStates, content.type, lastInteractedId)
     const target = childrenById.get(targetId)
     return target ? buildNavigateTo(target) : null
   }
 
   if (GUIDED_FLOW_TYPES.includes(content.type)) {
-    const targetId = findIncompleteLesson(childrenStates, lastInteractedId, content.type)
+    const targetId = Progress.incompleteLesson(childrenStates, content.type, lastInteractedId)
     const target = childrenById.get(targetId)
     return target ? buildNavigateTo(target) : null
   }
@@ -107,21 +130,21 @@ async function computeNavigateTo(content: NavigateToDecoratable): Promise<Naviga
   if (TWO_DEPTH_TYPES.includes(content.type)) {
     const lastChild = childrenById.get(lastInteractedId)
     if (!lastChild) return null
-    const childNav = await computeNavigateTo(lastChild)
+    const childNav = await computeNavigateTo(lastChild, ctx)
     return buildNavigateTo(lastChild, childNav)
   }
 
   return null
 }
 
-export const navigateToDecorator: FieldDecoratorAsync<
-  NavigateToDecoratable,
-  typeof NAVIGATE_TO_FIELD,
-  NavigateTo | null
-> = {
-  field: NAVIGATE_TO_FIELD,
-  compute: computeNavigateTo,
-  recurse: false,
+export function navigateToDecorator(
+  ctx?: NavigateContext
+): FieldDecoratorAsync<NavigateToDecoratable, typeof NAVIGATE_TO_FIELD, NavigateTo | null> {
+  return {
+    field: NAVIGATE_TO_FIELD,
+    compute: (item) => computeNavigateTo(item, ctx),
+    recurse: false,
+  }
 }
 
 export function decorateNavigateTo<T extends NavigateToDecoratable>(
@@ -130,10 +153,12 @@ export function decorateNavigateTo<T extends NavigateToDecoratable>(
 export function decorateNavigateTo<T extends NavigateToDecoratable>(
   items: T
 ): Promise<WithNavigateTo<T>>
-export function decorateNavigateTo<T extends NavigateToDecoratable>(
+export async function decorateNavigateTo<T extends NavigateToDecoratable>(
   items: T | T[]
 ): Promise<WithNavigateTo<T> | WithNavigateTo<T>[]> {
-  return decorateAllAsync(items as NavigateToDecoratable, [navigateToDecorator]) as Promise<
+  const list = Array.isArray(items) ? items : [items]
+  const ctx = await prefetchStates(list)
+  return decorateAllAsync(items as NavigateToDecoratable, [navigateToDecorator(ctx)]) as Promise<
     WithNavigateTo<T> | WithNavigateTo<T>[]
   >
 }

package/src/services/content-org/learning-paths.ts

@@ -222,7 +222,7 @@ export async function resetAllLearningPaths() {
  * @param {number} learningPathId - The learning path ID
  * @returns {Promise<Object>} Learning path with enriched lesson data
  */
-export async function getEnrichedLearningPath(learningPathId) {
+export async function getEnrichedLearningPath(learningPathId: number) {
   let response = (await addContextToLearningPaths(
     fetchByRailContentId,
     learningPathId,

package/src/services/contentProgress.js

@@ -841,7 +841,7 @@ export function filterOutLearningPathsForDuplication(progresses, collection) {
 
 export async function duplicateProgressForIds(entries) {
   return Promise.all(Object.entries(entries).map(([id, pct]) => {
-    return saveContentProgress(parseInt(id), null, pct, null, { skipPush: true, accessedDirectly: false })
+    return saveContentProgress(parseInt(id), null, pct, undefined, { skipPush: true, accessedDirectly: false })
   }))
 }
 

package/src/services/permissions/PermissionsV2Adapter.ts

@@ -19,6 +19,7 @@ import {
 } from './permissions'
 import {arrayToRawRepresentation, arrayToStringRepresentation} from '../../filterBuilder.js'
 import {basicMembershipTier, plusMembershipTier} from "../../contentTypeConfig";
+import { COLLECTION_TYPE } from '../sync/models/ContentProgress'
 
 /**
  * V2 Permissions Adapter for the new permissions system.
@@ -55,6 +56,9 @@ export class PermissionsV2Adapter extends PermissionsAdapter {
 
     // Content with no permissions is accessible to all
     if (contentPermissions.size === 0) {
+      if (content?.type === COLLECTION_TYPE.LEARNING_PATH && content?.children?.length) {
+        return content.children.every(child => child.need_access)
+      }
       return false
     }
 

package/src/services/progress/collections.ts

@@ -0,0 +1,33 @@
+import { db } from '../sync'
+import { ProgressQueryOptions, StartedOrCompletedOptions } from './types'
+
+const SIXTY_DAYS_IN_SECONDS = 60 * 24 * 60 * 60
+
+const defaultQueryOptions: ProgressQueryOptions = {
+  onlyIds: true,
+  include: {
+    aLaCarte: true,
+    learningPaths: false,
+  },
+}
+
+export const allStarted = async (limit: number | null = null, options?: ProgressQueryOptions) =>
+  db.contentProgress.started(limit, options ?? defaultQueryOptions)
+
+export const allCompleted = async (limit: number | null = null, options?: ProgressQueryOptions) =>
+  db.contentProgress.completed(limit, options ?? defaultQueryOptions)
+
+export const allCompletedByIds = async (contentIds: number[]) =>
+  db.contentProgress.completedByContentIds(contentIds)
+
+export const allStartedOrCompleted = async (
+  limit?: number,
+  options: StartedOrCompletedOptions = {}
+) =>
+  db.contentProgress
+    .startedOrCompleted({
+      ...options,
+      limit,
+      updatedAfter: Math.floor(Date.now() / 1000) - SIXTY_DAYS_IN_SECONDS,
+    })
+    .then((r) => r.data)

package/src/services/progress/index.ts

@@ -0,0 +1,6 @@
+import * as state from './state'
+import * as collections from './collections'
+
+export const Progress = { ...state, ...collections }
+
+export type { ProgressContentFilter, ProgressQueryOptions, StartedOrCompletedOptions } from './types'

package/src/services/progress/internal/queries.ts

@@ -0,0 +1,43 @@
+import { db } from '../../sync'
+import { CollectionParameter } from '../../sync/models/ContentProgress'
+
+export const getByIds = async <V>(
+  contentIds: number[],
+  dataKey: string,
+  defaultValue: V,
+  collection?: CollectionParameter
+): Promise<Map<number, V>> => {
+  if (contentIds.length === 0) return new Map()
+
+  const progress = new Map(contentIds.map((id) => [id, defaultValue]))
+  await db.contentProgress.getSomeProgressByContentIds(contentIds, collection).then((r) => {
+    r.data.forEach((p) => {
+      progress.set(p.content_id, p[dataKey] ?? defaultValue)
+    })
+  })
+  return progress
+}
+
+export const getById = async <V>(
+  contentId: number,
+  dataKey: string,
+  defaultValue: V,
+  collection?: CollectionParameter
+): Promise<V> => {
+  if (!contentId) return defaultValue
+  return db.contentProgress
+    .getOneProgressByContentId(contentId, collection)
+    .then((r) => r.data?.[dataKey] ?? defaultValue)
+}
+
+export const getByRecordIds = async <V>(ids: string[], dataKey: string, defaultValue: V) => {
+  const progress = Object.fromEntries(ids.map((id) => [id, defaultValue]))
+
+  await db.contentProgress.getSomeProgressByRecordIds(ids).then((r) => {
+    r.data.forEach((p) => {
+      progress[p.id] = p[dataKey] ?? defaultValue
+    })
+  })
+
+  return progress
+}

package/src/services/progress/state.ts

@@ -0,0 +1,50 @@
+import { db } from '../sync'
+import { COLLECTION_TYPE, CollectionParameter } from '../sync/models/ContentProgress'
+import { getById, getByIds, getByRecordIds } from './internal/queries'
+
+export const state = async (contentId: number, collection?: CollectionParameter) =>
+  getById(contentId, 'state', '', collection)
+
+export const stateByIds = async (contentIds: number[], collection?: CollectionParameter) =>
+  getByIds(contentIds, 'state', '', collection)
+
+export const stateByRecordIds = async (ids: string[]) => getByRecordIds(ids, 'state', '')
+
+export const playbackPositionByIds = async (contentIds: number[], collection?: CollectionParameter) =>
+  getByIds(contentIds, 'resume_time_seconds', 0, collection)
+
+export const playbackPositionByRecordIds = async (ids: string[]) =>
+  getByRecordIds(ids, 'resume_time_seconds', 0)
+
+export const lastInteractedOf = (
+  contentIds: number[],
+  collection?: CollectionParameter
+): Promise<number | undefined> =>
+  db.contentProgress
+    .mostRecentlyUpdatedId(contentIds, collection)
+    .then((r) => (r.data ? parseInt(r.data, 10) : undefined))
+
+export const incompleteLesson = (
+  progressOnItems: Map<number, string>,
+  contentType: string,
+  currentContentId?: number
+): number | null | undefined => {
+  const ids = Array.from(progressOnItems.keys())
+  const getProgress = (id: number) => progressOnItems.get(id)
+
+  if (contentType === 'guided-course' || contentType === COLLECTION_TYPE.LEARNING_PATH) {
+    return ids.find((id) => getProgress(id) !== 'completed') || ids.at(0)
+  }
+
+  const currentIndex = ids.indexOf(Number(currentContentId))
+  const startIndex = currentIndex === -1 ? 0 : currentIndex + 1
+
+  for (let i = startIndex; i < ids.length; i++) {
+    const id = ids[i]
+    if (getProgress(id) !== 'completed') {
+      return id
+    }
+  }
+
+  return ids[0]
+}

package/src/services/progress/types.ts

@@ -0,0 +1,16 @@
+export interface ProgressContentFilter {
+  aLaCarte?: boolean
+  learningPaths?: boolean
+}
+
+export interface ProgressQueryOptions {
+  onlyIds?: boolean
+  include?: ProgressContentFilter
+}
+
+export interface StartedOrCompletedOptions {
+  brand?: string
+  contentTypes?: string[]
+  parentId?: number
+  include?: ProgressContentFilter
+}

package/src/services/sanity.js

@@ -1193,13 +1193,11 @@ export async function fetchLiveEvent(brand, forcedContentId = null) {
     default:
       break
   }
-  let startDateTemp = new Date()
-  let endDateTemp = new Date()
 
-  startDateTemp = new Date(
-    startDateTemp.setMinutes(startDateTemp.getMinutes() + LIVE_EXTRA_MINUTES)
-  )
-  endDateTemp = new Date(endDateTemp.setMinutes(endDateTemp.getMinutes() - LIVE_EXTRA_MINUTES))
+  const now = new Date()
+
+  const startOfYesterday = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - 1)).toISOString()
+  const endOfTomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 2)).toISOString()
 
   const liveEventFields = getLiveFields().concat(
     `'event_coach_calendar_id': coalesce(calendar_id, '${defaultCalendarID}')`
@@ -1212,15 +1210,25 @@ export async function fetchLiveEvent(brand, forcedContentId = null) {
       : `status == 'scheduled'
       && (brand == '${brand}' || live_global_event == true)
       && defined(live_event_start_time)
-      && live_event_start_time <= '${getSanityDate(startDateTemp, false)}'
-      && live_event_end_time >= '${getSanityDate(endDateTemp, false)}'`
+      && live_event_start_time >= '${startOfYesterday}'
+      && live_event_start_time < '${endOfTomorrow}'`
 
   const filter = await new FilterBuilder(baseFilter, { bypassPermissions: true }).buildFilter()
 
-  // This query finds the first scheduled event (sorted by start_time) that ends after now()
-  const query = `*[${filter}]{${fieldsString}} | order(live_event_start_time)[0...1]`
+  const events = await fetchSanity(
+    `*[${filter}]{${fieldsString}} | order(live_event_start_time asc)`,
+    true,
+    { processNeedAccess: false }
+  )
 
-  return await fetchSanity(query, false, { processNeedAccess: true })
+  const clientNow = new Date()
+  const windowStart = new Date(clientNow.getTime() - LIVE_EXTRA_MINUTES * 60000).toISOString()
+  const windowEnd = new Date(clientNow.getTime() + LIVE_EXTRA_MINUTES * 60000).toISOString()
+
+  return events?.find(event =>
+    event.live_event_end_time >= windowStart &&
+    event.live_event_start_time <= windowEnd
+  ) ?? null
 }
 
 /**
@@ -1667,8 +1675,8 @@ function contentResultsDecorator(results, fieldName, callback) {
           processChildren(contentItem)
         })
       } else {
-        result[fieldName] = callback(result)
         processChildren(result)
+        result[fieldName] = callback(result)
       }
     })
   } else if (results.entity && Array.isArray(results.entity)) {
@@ -1705,8 +1713,8 @@ function contentResultsDecorator(results, fieldName, callback) {
       }
     })
   } else {
+    processChildren(results)
     results[fieldName] = callback(results)
-    processChildren(results) // this on was always true
   }
 
   return results
@@ -2224,7 +2232,14 @@ export async function fetchScheduledAndNewReleases(
     return []
   }
 
-  return reorderScheduledAndNewReleases(r, limit)
+  const reordered = reorderScheduledAndNewReleases(r, limit)
+  const computedNow = new Date()
+  return reordered.map(item => ({
+    ...item,
+    isLive: item.live_event_start_time && item.live_event_end_time
+      ? new Date(item.live_event_start_time) <= computedNow && new Date(item.live_event_end_time) >= computedNow
+      : false,
+  }))
 }
 
 function reorderScheduledAndNewReleases(r, limit) {

package/test/unit/lib/sanity/decorators/navigate-to.test.ts

@@ -16,25 +16,10 @@ jest.mock('../../../../../src/services/sync/repository-proxy', () => {
         return Promise.resolve({ data: mockLastInteracted })
       }),
     },
-    practices: {
-      queryAll: jest.fn().mockResolvedValue({ data: [] }),
-      getAll: jest.fn().mockResolvedValue({ data: [] }),
-    },
   }
   return { default: mockFns, ...mockFns }
 })
 
-jest.mock('../../../../../src/services/content-org/learning-paths', () => ({
-  getDailySession: jest.fn().mockResolvedValue(null),
-  onLearningPathCompletedActions: jest.fn().mockResolvedValue(undefined),
-}))
-
-jest.mock('../../../../../src/services/sanity.js', () => ({
-  getHierarchy: jest.fn().mockResolvedValue({ metadata: {}, parents: {}, children: {} }),
-  getHierarchies: jest.fn().mockResolvedValue({ metadata: {}, parents: {}, children: {} }),
-  getSanityDate: jest.fn((date: Date) => date.toISOString()),
-}))
-
 import { initializeTestService } from '../../../../initializeTests.js'
 import {
   NAVIGATE_TO_FIELD,
@@ -75,11 +60,32 @@ beforeEach(() => {
 })
 
 describe('navigate-to decorator', () => {
-  describe('navigateToDecorator (const)', () => {
+  describe('navigateToDecorator (factory)', () => {
     test('field is navigateTo', () => {
-      expect(navigateToDecorator.field).toBe('navigateTo')
+      expect(navigateToDecorator().field).toBe('navigateTo')
       expect(NAVIGATE_TO_FIELD).toBe('navigateTo')
     })
+
+    test('recurse is false', () => {
+      expect(navigateToDecorator().recurse).toBe(false)
+    })
+
+    test('without ctx — navigates single item via DB', async () => {
+      const item = parent(1, 'course', [child(101), child(102)])
+      const result = await navigateToDecorator().compute(item)
+      expect(result).toMatchObject({ id: 101, child: null })
+    })
+
+    test('with ctx — uses ctx states, not DB', async () => {
+      // DB says course is started; ctx overrides to not-started → should go to first child
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 50, updated_at: 1000 },
+      ]
+      const ctx = { states: new Map<number, string>([[1, '']]) }
+      const item = parent(1, 'course', [child(101), child(102)])
+      const result = await navigateToDecorator(ctx).compute(item)
+      expect(result).toMatchObject({ id: 101 })
+    })
   })
 
   describe('decorateNavigateTo', () => {
@@ -179,6 +185,21 @@ describe('navigate-to decorator', () => {
       })
     })
 
+    test('two-depth: started course-collection, last-interacted course has completed lessons → first incomplete lesson, not lesson[0]', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 50, updated_at: 1000 },
+        { content_id: 101, state: 'started', progress_percent: 50, updated_at: 900 },
+        { content_id: 201, state: 'completed', progress_percent: 100, updated_at: 800 },
+        { content_id: 202, state: '', progress_percent: 0, updated_at: 0 },
+        { content_id: 203, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 101
+      const course = parent(101, 'course', [child(201), child(202), child(203)])
+      const collection = parent(1, 'course-collection', [course])
+      const result = await decorateNavigateTo(collection)
+      expect(result.navigateTo).toMatchObject({ id: 101, child: { id: 202 } })
+    })
+
     test('decorates every item in an array', async () => {
       const items = [parent(1, 'course', [child(101)]), parent(2, 'lesson', [child(201)])]
       const result = await decorateNavigateTo(items)
@@ -192,18 +213,6 @@ describe('navigate-to decorator', () => {
       expect(result).toBe(items)
     })
 
-    test('navigateToDecorator.compute fires once per top-level item, never on descendants', async () => {
-      const spy = jest.spyOn(navigateToDecorator, 'compute')
-      const courseChild = parent(101, 'course', [child(201), child(202)])
-      const collection = parent(1, 'course-collection', [courseChild, parent(102, 'course', [])])
-      const standalone = parent(2, 'course', [child(301)])
-      await decorateNavigateTo([collection, standalone])
-      expect(spy).toHaveBeenCalledTimes(2)
-      expect(spy).toHaveBeenCalledWith(collection)
-      expect(spy).toHaveBeenCalledWith(standalone)
-      spy.mockRestore()
-    })
-
     test('descendants of decorated items do not receive navigateTo field', async () => {
       const item = parent(1, 'course', [child(101), child(102)])
       const result = await decorateNavigateTo(item)
@@ -237,6 +246,92 @@ describe('navigate-to decorator', () => {
       expect(result.navigateTo).toMatchObject({ id: 102 })
     })
 
+    test('guided-course STARTED, lastInteracted not in children → first incomplete', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 40, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: '', progress_percent: 0, updated_at: 0 },
+        { content_id: 103, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'guided-course', [child(101), child(102), child(103)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 102 })
+    })
+
+    test('guided-course STARTED, lastInteracted not in children, all complete → first child', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 100, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: 'completed', progress_percent: 100, updated_at: 1000 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'guided-course', [child(101), child(102)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 101 })
+    })
+
+    test('learning-path-v2 STARTED, lastInteracted not in children → first incomplete', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 40, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, COLLECTION_TYPE.LEARNING_PATH, [child(101), child(102)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 102 })
+    })
+
+    test('course STARTED, lastInteracted not in children → first incomplete', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 40, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: '', progress_percent: 0, updated_at: 0 },
+        { content_id: 103, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'course', [child(101), child(102), child(103)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 102 })
+    })
+
+    test('skill-pack STARTED, lastInteracted not in children → first incomplete', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 40, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'skill-pack', [child(101), child(102)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 102 })
+    })
+
+    test('song-tutorial STARTED, lastInteracted not in children → first incomplete', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 40, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: '', progress_percent: 0, updated_at: 0 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'song-tutorial', [child(101), child(102)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 102 })
+    })
+
+    test('course STARTED, lastInteracted not in children, all complete → first child', async () => {
+      mockProgressRecords = [
+        { content_id: 1, state: 'started', progress_percent: 100, updated_at: 1000 },
+        { content_id: 101, state: 'completed', progress_percent: 100, updated_at: 900 },
+        { content_id: 102, state: 'completed', progress_percent: 100, updated_at: 1000 },
+      ]
+      mockLastInteracted = 999
+      const item = parent(1, 'course', [child(101), child(102)])
+      const result = await decorateNavigateTo(item)
+      expect(result.navigateTo).toMatchObject({ id: 101 })
+    })
+
     test('two-depth started but lastInteracted child not in collection → null', async () => {
       mockProgressRecords = [
         { content_id: 1, state: 'started', progress_percent: 50, updated_at: 1000 },

package/test/unit/services/progress.test.ts

@@ -0,0 +1,300 @@
+let mockProgressRecords: any[] = []
+let mockRecordsById: Record<string, any> = {}
+let mockLastInteracted: string | null = null
+let mockStarted: any = { data: [] }
+let mockCompleted: any = { data: [] }
+let mockCompletedByContentIds: any = { data: [] }
+let mockStartedOrCompleted: any = { data: [] }
+
+const repoMocks = {
+  contentProgress: {
+    getOneProgressByContentId: jest.fn().mockImplementation((contentId: number) => {
+      const record = mockProgressRecords.find((r) => r.content_id === contentId)
+      return Promise.resolve({ data: record || null })
+    }),
+    getSomeProgressByContentIds: jest.fn().mockImplementation((contentIds: number[]) => {
+      const records = mockProgressRecords.filter((r) => contentIds.includes(r.content_id))
+      return Promise.resolve({ data: records })
+    }),
+    getSomeProgressByRecordIds: jest.fn().mockImplementation((ids: string[]) => {
+      const records = ids.map((id) => mockRecordsById[id]).filter(Boolean)
+      return Promise.resolve({ data: records })
+    }),
+    mostRecentlyUpdatedId: jest.fn().mockImplementation(() => {
+      return Promise.resolve({ data: mockLastInteracted })
+    }),
+    started: jest.fn().mockImplementation(() => Promise.resolve(mockStarted)),
+    completed: jest.fn().mockImplementation(() => Promise.resolve(mockCompleted)),
+    completedByContentIds: jest
+      .fn()
+      .mockImplementation(() => Promise.resolve(mockCompletedByContentIds)),
+    startedOrCompleted: jest.fn().mockImplementation(() => Promise.resolve(mockStartedOrCompleted)),
+  },
+}
+
+jest.mock('../../../src/services/sync/repository-proxy', () => ({
+  __esModule: true,
+  default: repoMocks,
+  ...repoMocks,
+}))
+
+import { Progress } from '../../../src/services/progress'
+import { COLLECTION_TYPE } from '../../../src/services/sync/models/ContentProgress'
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  mockProgressRecords = []
+  mockRecordsById = {}
+  mockLastInteracted = null
+  mockStarted = { data: [] }
+  mockCompleted = { data: [] }
+  mockCompletedByContentIds = { data: [] }
+  mockStartedOrCompleted = { data: [] }
+})
+
+describe('Progress.state', () => {
+  test('returns state from record', async () => {
+    mockProgressRecords = [{ content_id: 100, state: 'started' }]
+    expect(await Progress.state(100)).toBe('started')
+  })
+
+  test('returns empty string when record missing', async () => {
+    expect(await Progress.state(999)).toBe('')
+  })
+
+  test('returns empty string when contentId is 0', async () => {
+    expect(await Progress.state(0)).toBe('')
+    expect(repoMocks.contentProgress.getOneProgressByContentId).not.toHaveBeenCalled()
+  })
+
+  test('forwards collection argument', async () => {
+    const collection = { id: 5, type: COLLECTION_TYPE.LEARNING_PATH }
+    await Progress.state(100, collection)
+    expect(repoMocks.contentProgress.getOneProgressByContentId).toHaveBeenCalledWith(
+      100,
+      collection
+    )
+  })
+})
+
+describe('Progress.stateByIds', () => {
+  test('returns Map with states for found ids and defaults for missing', async () => {
+    mockProgressRecords = [
+      { content_id: 100, state: 'started' },
+      { content_id: 300, state: 'completed' },
+    ]
+    const result = await Progress.stateByIds([100, 300, 999])
+    expect(result.get(100)).toBe('started')
+    expect(result.get(300)).toBe('completed')
+    expect(result.get(999)).toBe('')
+  })
+
+  test('returns empty Map for empty input without hitting db', async () => {
+    const result = await Progress.stateByIds([])
+    expect(result.size).toBe(0)
+    expect(repoMocks.contentProgress.getSomeProgressByContentIds).not.toHaveBeenCalled()
+  })
+
+  test('forwards collection argument', async () => {
+    const collection = { id: 7, type: COLLECTION_TYPE.PLAYLIST }
+    await Progress.stateByIds([1, 2], collection)
+    expect(repoMocks.contentProgress.getSomeProgressByContentIds).toHaveBeenCalledWith(
+      [1, 2],
+      collection
+    )
+  })
+})
+
+describe('Progress.stateByRecordIds', () => {
+  test('returns object with states keyed by record id', async () => {
+    mockRecordsById = {
+      '100:self:0': { id: '100:self:0', state: 'started' },
+      '300:self:0': { id: '300:self:0', state: 'completed' },
+    }
+    const result = await Progress.stateByRecordIds(['100:self:0', '300:self:0', '999:self:0'])
+    expect(result['100:self:0']).toBe('started')
+    expect(result['300:self:0']).toBe('completed')
+    expect(result['999:self:0']).toBe('')
+  })
+})
+
+describe('Progress.playbackPositionByIds', () => {
+  test('returns Map with resume_time_seconds for found ids and 0 default', async () => {
+    mockProgressRecords = [
+      { content_id: 1, resume_time_seconds: 42 },
+      { content_id: 2, resume_time_seconds: 0 },
+    ]
+    const result = await Progress.playbackPositionByIds([1, 2, 3])
+    expect(result.get(1)).toBe(42)
+    expect(result.get(2)).toBe(0)
+    expect(result.get(3)).toBe(0)
+  })
+
+  test('returns default 0 when field is null', async () => {
+    mockProgressRecords = [{ content_id: 1, resume_time_seconds: null }]
+    const result = await Progress.playbackPositionByIds([1])
+    expect(result.get(1)).toBe(0)
+  })
+})
+
+describe('Progress.playbackPositionByRecordIds', () => {
+  test('returns object with resume_time_seconds keyed by record id', async () => {
+    mockRecordsById = {
+      '100:self:0': { id: '100:self:0', resume_time_seconds: 120 },
+      '300:self:0': { id: '300:self:0', resume_time_seconds: 0 },
+    }
+    const result = await Progress.playbackPositionByRecordIds(['100:self:0', '300:self:0', '999:self:0'])
+    expect(result['100:self:0']).toBe(120)
+    expect(result['300:self:0']).toBe(0)
+    expect(result['999:self:0']).toBe(0)
+  })
+
+  test('returns default 0 when field is null', async () => {
+    mockRecordsById = { '100:self:0': { id: '100:self:0', resume_time_seconds: null } }
+    const result = await Progress.playbackPositionByRecordIds(['100:self:0'])
+    expect(result['100:self:0']).toBe(0)
+  })
+})
+
+describe('Progress.lastInteractedOf', () => {
+  test('parses numeric string to integer', async () => {
+    mockLastInteracted = '101'
+    expect(await Progress.lastInteractedOf([100, 101])).toBe(101)
+  })
+
+  test('returns undefined when repository returns null', async () => {
+    mockLastInteracted = null
+    expect(await Progress.lastInteractedOf([100, 101])).toBeUndefined()
+  })
+
+  test('forwards args to repository', async () => {
+    const collection = { id: 9, type: COLLECTION_TYPE.LEARNING_PATH }
+    await Progress.lastInteractedOf([1, 2, 3], collection)
+    expect(repoMocks.contentProgress.mostRecentlyUpdatedId).toHaveBeenCalledWith(
+      [1, 2, 3],
+      collection
+    )
+  })
+})
+
+describe('Progress.incompleteLesson', () => {
+  test('guided-course returns first non-completed id', () => {
+    const states = new Map<number, string>([
+      [1, 'completed'],
+      [2, 'started'],
+      [3, ''],
+    ])
+    expect(Progress.incompleteLesson(states, 'guided-course', 999)).toBe(2)
+  })
+
+  test('learning-path returns first non-completed id', () => {
+    const states = new Map<number, string>([
+      [1, 'completed'],
+      [2, 'completed'],
+      [3, 'started'],
+    ])
+    expect(Progress.incompleteLesson(states, COLLECTION_TYPE.LEARNING_PATH, 999)).toBe(3)
+  })
+
+  test('guided-course falls back to first id when all completed', () => {
+    const states = new Map<number, string>([
+      [10, 'completed'],
+      [20, 'completed'],
+    ])
+    expect(Progress.incompleteLesson(states, 'guided-course', 999)).toBe(10)
+  })
+
+  test('other type: returns next non-completed after currentContentId', () => {
+    const states = new Map<number, string>([
+      [1, 'completed'],
+      [2, 'started'],
+      [3, 'completed'],
+      [4, 'started'],
+    ])
+    expect(Progress.incompleteLesson(states, 'course', 2)).toBe(4)
+  })
+
+  test('other type: wraps to first id when no incomplete after current', () => {
+    const states = new Map<number, string>([
+      [1, 'started'],
+      [2, 'started'],
+      [3, 'completed'],
+    ])
+    expect(Progress.incompleteLesson(states, 'course', 3)).toBe(1)
+  })
+
+  test('other type: scans from start when currentContentId not in map → first incomplete', () => {
+    const states = new Map<number, string>([
+      [1, 'completed'],
+      [2, 'started'],
+    ])
+    expect(Progress.incompleteLesson(states, 'course', 999)).toBe(2)
+  })
+
+  test('other type: scans from start when currentContentId not in map and all complete → first id', () => {
+    const states = new Map<number, string>([
+      [1, 'completed'],
+      [2, 'completed'],
+    ])
+    expect(Progress.incompleteLesson(states, 'course', 999)).toBe(1)
+  })
+})
+
+describe('Progress.allStarted', () => {
+  test('delegates to repo and applies default options', async () => {
+    mockStarted = { data: [1, 2, 3] }
+    const result = await Progress.allStarted()
+    expect(result).toEqual({ data: [1, 2, 3] })
+    expect(repoMocks.contentProgress.started).toHaveBeenCalledWith(null, {
+      onlyIds: true,
+      include: { aLaCarte: true, learningPaths: false },
+    })
+  })
+
+  test('forwards custom limit and options', async () => {
+    const opts = { onlyIds: false, include: { aLaCarte: false, learningPaths: true } }
+    await Progress.allStarted(10, opts)
+    expect(repoMocks.contentProgress.started).toHaveBeenCalledWith(10, opts)
+  })
+})
+
+describe('Progress.allCompleted', () => {
+  test('delegates to repo with default options', async () => {
+    mockCompleted = { data: [9] }
+    const result = await Progress.allCompleted()
+    expect(result).toEqual({ data: [9] })
+    expect(repoMocks.contentProgress.completed).toHaveBeenCalledWith(null, {
+      onlyIds: true,
+      include: { aLaCarte: true, learningPaths: false },
+    })
+  })
+})
+
+describe('Progress.allCompletedByIds', () => {
+  test('delegates to repo with passed contentIds', async () => {
+    mockCompletedByContentIds = { data: [{ content_id: 5 }] }
+    const result = await Progress.allCompletedByIds([5, 6])
+    expect(result).toEqual({ data: [{ content_id: 5 }] })
+    expect(repoMocks.contentProgress.completedByContentIds).toHaveBeenCalledWith([5, 6])
+  })
+})
+
+describe('Progress.allStartedOrCompleted', () => {
+  test('unwraps r.data from repo response', async () => {
+    mockStartedOrCompleted = { data: [{ content_id: 1 }, { content_id: 2 }] }
+    const result = await Progress.allStartedOrCompleted()
+    expect(result).toEqual([{ content_id: 1 }, { content_id: 2 }])
+  })
+
+  test('passes limit and updatedAfter window (60 days)', async () => {
+    const before = Math.floor(Date.now() / 1000) - 60 * 24 * 60 * 60
+    await Progress.allStartedOrCompleted(25, { brand: 'drumeo' })
+    const after = Math.floor(Date.now() / 1000) - 60 * 24 * 60 * 60
+
+    const args = repoMocks.contentProgress.startedOrCompleted.mock.calls[0][0]
+    expect(args.limit).toBe(25)
+    expect(args.brand).toBe('drumeo')
+    expect(args.updatedAfter).toBeGreaterThanOrEqual(before)
+    expect(args.updatedAfter).toBeLessThanOrEqual(after)
+  })
+})

package/usage/sanity/decorators/examples.ts

@@ -0,0 +1,237 @@
+import {
+  decorateAll,
+  decorateAllAsync,
+  decorateAsync,
+  type FieldDecorator,
+  type FieldDecoratorAsync,
+} from '../../../src/lib/sanity/decorators/base'
+import {
+  accessDecorator,
+  decorateAccess,
+  type AccessDecoratable,
+} from '../../../src/lib/sanity/decorators/need-access'
+import {
+  pageTypeDecorator,
+  decoratePageType,
+  type PageTypeDecoratable,
+} from '../../../src/lib/sanity/decorators/page-type'
+import {
+  decorateNavigateTo,
+  navigateToDecorator,
+  WithNavigateTo,
+  type NavigateToDecoratable,
+} from '../../../src/lib/sanity/decorators/navigate-to'
+import type { UserPermissions } from '../../../src/services/permissions'
+
+interface ContentRow extends AccessDecoratable, PageTypeDecoratable {
+  id: number
+  type?: string
+  permission_id?: number[]
+  children?: ContentRow[]
+}
+
+const perms: UserPermissions = {
+  permissions: [78, 91],
+  isAdmin: false,
+  isModerator: false,
+  isABasicMember: true,
+}
+
+const rows: ContentRow[] = [
+  {
+    id: 1,
+    type: 'course',
+    permission_id: [78],
+    children: [
+      { id: 2, type: 'song', permission_id: [91] },
+      { id: 3, type: 'play-along' },
+    ],
+  },
+]
+
+export function singleDecoratorViaWrapper() {
+  const decorated = decorateAccess(rows, perms)
+  decorated[0].need_access satisfies boolean
+  return decorated
+}
+
+export function chainedWrappers() {
+  const withAccess = decorateAccess(rows, perms)
+  const withBoth = decoratePageType(withAccess)
+  withBoth[0].need_access satisfies boolean
+  withBoth[0].page_type satisfies 'song' | 'lesson'
+  return withBoth
+}
+
+export function composedSingleWalk() {
+  type Composed = AccessDecoratable & PageTypeDecoratable
+  const decorators: FieldDecorator<Composed>[] = [
+    accessDecorator(perms) as FieldDecorator<Composed>,
+    pageTypeDecorator as FieldDecorator<Composed>,
+  ]
+  return decorateAll(rows, decorators)
+}
+
+export function conditionalComposition(opts: { withAccess: boolean; withPageType: boolean }) {
+  type Composed = AccessDecoratable & PageTypeDecoratable
+  const decorators: FieldDecorator<Composed>[] = []
+  if (opts.withAccess) {
+    decorators.push(accessDecorator(perms) as FieldDecorator<Composed>)
+  }
+  if (opts.withPageType) {
+    decorators.push(pageTypeDecorator as FieldDecorator<Composed>)
+  }
+  return decorateAll(rows, decorators)
+}
+
+interface ProgressDecoratable extends AccessDecoratable {
+  progress_percent?: number
+  is_liked?: boolean
+}
+
+async function fetchProgress(id: number): Promise<number> {
+  return id * 10
+}
+
+async function fetchLiked(id: number): Promise<boolean> {
+  return id % 2 === 0
+}
+
+export async function singleAsyncDecorator() {
+  const decorated = (await decorateAsync(rows, 'progress_percent', (item) =>
+    fetchProgress(item.id as number)
+  )) as ProgressDecoratable[]
+  decorated[0].progress_percent satisfies number | undefined
+  return decorated
+}
+
+export async function parallelAsyncDecorators() {
+  const decorators: FieldDecoratorAsync<ProgressDecoratable>[] = [
+    {
+      field: 'progress_percent',
+      compute: (item) => fetchProgress(item.id as number),
+    },
+    {
+      field: 'is_liked',
+      compute: (item) => fetchLiked(item.id as number),
+    },
+  ]
+  const decorated = (await decorateAllAsync(
+    rows as ProgressDecoratable[],
+    decorators
+  )) as ProgressDecoratable[]
+  decorated[0].progress_percent satisfies number | undefined
+  decorated[0].is_liked satisfies boolean | undefined
+  return decorated
+}
+
+export async function mixedSyncThenAsync() {
+  const withAccess = decorateAll(rows, [
+    accessDecorator(perms) as FieldDecorator<ProgressDecoratable>,
+  ]) as ProgressDecoratable[]
+  return decorateAllAsync(withAccess, [
+    {
+      field: 'progress_percent',
+      compute: (item) => fetchProgress(item.id as number),
+    },
+    {
+      field: 'is_liked',
+      compute: (item) => fetchLiked(item.id as number),
+    },
+  ])
+}
+
+const courseLesson = (id: number): NavigateToDecoratable => ({
+  id,
+  type: 'course-lesson',
+  brand: 'drumeo',
+  thumbnail: '',
+  published_on: null,
+  status: 'published',
+})
+
+const navigateRows: NavigateToDecoratable[] = [
+  {
+    id: 1,
+    type: 'course',
+    brand: 'drumeo',
+    thumbnail: '',
+    published_on: null,
+    status: 'published',
+    children: [courseLesson(101), courseLesson(102), courseLesson(103)],
+  },
+  {
+    id: 2,
+    type: 'course-collection',
+    brand: 'drumeo',
+    thumbnail: '',
+    published_on: null,
+    status: 'published',
+    children: [
+      {
+        id: 201,
+        type: 'course',
+        brand: 'drumeo',
+        thumbnail: '',
+        published_on: null,
+        status: 'published',
+        children: [courseLesson(301), courseLesson(302)],
+      },
+    ],
+  },
+]
+
+export async function singleAsyncNavigateTo() {
+  const decorated = await decorateNavigateTo(navigateRows)
+  void decorated[0].navigateTo
+  void decorated[1].navigateTo?.child
+  return decorated
+}
+
+export async function navigateToOnSingleItem() {
+  const decorated = await decorateNavigateTo(navigateRows[0])
+  void decorated.navigateTo
+  return decorated
+}
+
+export async function navigateToComposedWithAccess() {
+  interface ContentWithNav extends NavigateToDecoratable, AccessDecoratable {
+    permission_id?: number[]
+    children?: ContentWithNav[]
+  }
+
+  const items: ContentWithNav[] = navigateRows.map((row) => ({
+    ...row,
+    permission_id: [78],
+  }))
+
+  const withAccess = decorateAccess(items, perms)
+  const withBoth = await decorateNavigateTo(withAccess)
+
+  withBoth[0].need_access satisfies boolean
+  void withBoth[0].navigateTo
+  return withBoth
+}
+
+export async function navigateToParallelWithProgress() {
+  interface ContentWithNavAndProgress extends NavigateToDecoratable {
+    progress_percent?: number
+  }
+
+  const items = navigateRows as ContentWithNavAndProgress[]
+  const decorators: FieldDecoratorAsync<ContentWithNavAndProgress>[] = [
+    navigateToDecorator as FieldDecoratorAsync<ContentWithNavAndProgress>,
+    {
+      field: 'progress_percent',
+      compute: (item) => fetchProgress(item.id),
+    },
+  ]
+  const decorated = (await decorateAllAsync(
+    items,
+    decorators
+  )) as WithNavigateTo<ContentWithNavAndProgress>[]
+
+  void decorated[0].navigateTo
+  decorated[0].progress_percent satisfies number | undefined
+  return decorated
+}