musora-content-services 2.185.0 → 2.186.0

package/src/lib/sanity/examples.ts

@@ -25,19 +25,20 @@ const publishedSongs = (brand: string) =>
   f.combine(f.type('song'), f.statusIn(['published']), f.defined('railcontent_id'), f.brand(brand))
 
 export async function fetchSongTitles(brand: string) {
-  const result = await groq()
+  const result = await groq<Song[]>()
     .and(publishedSongs(brand))
     .order('published_on desc')
     .slice(0, 10)
     .select('_id', 'title', 'railcontent_id')
-    .run<Song[]>()
+    .default([])
+    .run()
 
   return result.fold(
     (error) => {
       console.error(`${error.name}: ${error.message}`, error.groq)
       return []
     },
-    (songs) => songs ?? []
+    (songs) => songs
   )
 }
 
@@ -105,27 +106,28 @@ interface Lesson {
 }
 
 export async function fetchLessonsWithoutPermissions(brand: string) {
-  const result = await groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>()
+  const result = await groq<Lesson[]>().and(f.brand(brand)).slice(0, 10).default([]).run()
 
   return result
     .map((lessons) =>
-      decorateAll<Lesson>(lessons ?? [], [pageTypeDecorator as FieldDecorator<Lesson>])
+      decorateAll<Lesson>(lessons, [pageTypeDecorator as FieldDecorator<Lesson>])
     )
     .recover([])
 }
 
 export async function fetchDecoratedLessons(brand: string) {
   const [result, permissions] = await Promise.all([
-    groq()
+    groq<Lesson[]>()
       .and(f.combine(f.typeIn(['course']), f.brand(brand)))
       .slice(0, 10)
-      .run<Lesson[]>(),
+      .default([])
+      .run(),
     fetchUserPermissions(),
   ])
 
   return result
     .map((lessons) =>
-      decorateAll<Lesson>(lessons ?? [], [
+      decorateAll<Lesson>(lessons, [
         accessDecorator(permissions) as FieldDecorator<Lesson>,
         lifetimeUpgradeDecorator(permissions) as FieldDecorator<Lesson>,
         pageTypeDecorator as FieldDecorator<Lesson>,
@@ -135,18 +137,15 @@ export async function fetchDecoratedLessons(brand: string) {
 }
 
 export async function fetchLessonsWithNavigation(brand: string) {
-  const [result, permissions] = await Promise.all([
-    groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>(),
-    fetchUserPermissions(),
-  ])
+  const lessons = groq<Lesson[]>().and(f.brand(brand)).slice(0, 10).default([]).run()
+  const permissions = await fetchUserPermissions()
 
-  const decorated = await result
+  return lessons
     .map((lessons) =>
-      decorateAll<Lesson>(lessons ?? [], [accessDecorator(permissions) as FieldDecorator<Lesson>])
+      decorateAll<Lesson>(lessons, [accessDecorator(permissions) as FieldDecorator<Lesson>])
     )
     .mapAsync((lessons) => decorateNavigateTo(lessons) as Promise<Lesson[]>)
-
-  return decorated.recover([])
+    .recover([])
 }
 
 export async function fetchWithACustomDecorator(brand: string) {
@@ -155,9 +154,9 @@ export async function fetchWithACustomDecorator(brand: string) {
     compute: (lesson) => lesson.permission_id === undefined,
   }
 
-  const result = await groq().and(f.brand(brand)).run<Lesson[]>()
+  const result = await groq<Lesson[]>().and(f.brand(brand)).default([]).run()
 
-  return result.map((lessons) => decorateAll<Lesson>(lessons ?? [], [isFree])).recover([])
+  return result.map((lessons) => decorateAll<Lesson>(lessons, [isFree])).recover([])
 }
 
 export async function fetchWhenPermissionsMayBeUnavailable(brand: string) {
@@ -167,7 +166,7 @@ export async function fetchWhenPermissionsMayBeUnavailable(brand: string) {
     )
 
   const [result, permissions] = await Promise.all([
-    groq().and(f.brand(brand)).run<Lesson[]>(),
+    groq<Lesson[]>().and(f.brand(brand)).default([]).run(),
     fetchUserPermissions()
       .then(Either.right<SanityQueryError, UserPermissions>)
       .catch(queryError),
@@ -176,7 +175,7 @@ export async function fetchWhenPermissionsMayBeUnavailable(brand: string) {
   return result
     .flatMap((lessons) =>
       permissions.map((userPermissions) =>
-        decorateAll<Lesson>(lessons ?? [], [
+        decorateAll<Lesson>(lessons, [
           accessDecorator(userPermissions) as FieldDecorator<Lesson>,
         ])
       )
@@ -188,17 +187,14 @@ export async function fetchWhenPermissionsMayBeUnavailable(brand: string) {
 }
 
 export async function decorateManuallyForPreciseTypes(brand: string) {
-  const [result, permissions] = await Promise.all([
-    groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>(),
-    fetchUserPermissions(),
-  ])
+  const lessons = groq<Lesson[]>().and(f.brand(brand)).slice(0, 10).default([]).run()
+  const permissions = await fetchUserPermissions()
 
-  const decorated = await result
-    .map((lessons) => decorateAccess(lessons ?? [], permissions))
+  return lessons
+    .map((lessons) => decorateAccess(lessons, permissions))
     .mapAsync((lessons) => decorateNavigateTo(lessons))
-
-  return decorated.fold(
-    () => [],
-    (lessons) => lessons.map((lesson) => [lesson.need_access, lesson.navigateTo] as const)
-  )
+    .fold(
+      () => [],
+      (lessons) => lessons.map((lesson) => [lesson.need_access, lesson.navigateTo] as const)
+    )
 }

package/src/lib/sanity/filter.ts

@@ -123,6 +123,15 @@ export class Filters {
     return `slug.current == "${escapeDoubleQuoted(slug)}"`
   }
 
+  /**
+   * @param {string[]} slugs - Array of slugs to filter by
+   * @returns {string} Filter expression
+   * @example Filters.slugIn(['a', 'b']) // "slug.current in ['a','b']"
+   */
+  static slugIn(slugs: string[]): string {
+    return `slug.current in ${arrayToStringRepresentation(slugs)}`
+  }
+
   /**
    * @param {number} id - The railcontent_id to filter by
    * @returns {string} Filter expression
@@ -218,6 +227,59 @@ export class Filters {
     return `published_on >= "${escapeDoubleQuoted(date)}"`
   }
 
+  /**
+   * @param {string} field - The date field to compare
+   * @param {string} date - ISO date string
+   * @returns {string} Filter expression
+   * @example Filters.dateBefore('ends_at', '2026-01-01') // 'ends_at <= "2026-01-01"'
+   */
+  static dateBefore(field: string, date: string): string {
+    return `${field} <= "${escapeDoubleQuoted(date)}"`
+  }
+
+  /**
+   * @param {string} field - The date field to compare
+   * @param {string} date - ISO date string
+   * @returns {string} Filter expression
+   * @example Filters.dateAfter('starts_at', '2026-01-01') // 'starts_at >= "2026-01-01"'
+   */
+  static dateAfter(field: string, date: string): string {
+    return `${field} >= "${escapeDoubleQuoted(date)}"`
+  }
+
+  /**
+   * Matches documents whose window covers the given date.
+   *
+   * @param {string} startField - The field holding the start of the window
+   * @param {string} endField - The field holding the end of the window
+   * @param {string} date - ISO date string
+   * @returns {string} Filter expression
+   * @example Filters.dateWithin('starts_at', 'ends_at', '2026-11-25')
+   */
+  static dateWithin(startField: string, endField: string, date: string): string {
+    return Filters.combine(Filters.dateBefore(startField, date), Filters.dateAfter(endField, date))
+  }
+
+  /**
+   * @param {string} field - The boolean field to check
+   * @param {boolean} [value=true] - The value to match
+   * @returns {string} Filter expression
+   * @example Filters.flag('active') // "active == true"
+   */
+  static flag(field: string, value: boolean = true): string {
+    return `${field} == ${value}`
+  }
+
+  /**
+   * @param {string} field - The field to compare
+   * @param {string} value - The value to match
+   * @returns {string} Filter expression
+   * @example Filters.fieldEquals('key', 'upgrade-banner') // 'key == "upgrade-banner"'
+   */
+  static fieldEquals(field: string, value: string): string {
+    return `${field} == "${escapeDoubleQuoted(value)}"`
+  }
+
   /**
    * @param {string} field - The field to check
    * @returns {string} Filter expression

package/src/lib/sanity/groq.ts

@@ -1,30 +1,54 @@
-import { Either } from '../ads/either'
+import { AsyncEither } from '../ads/async-either'
 import { FieldAccess } from './field-access'
-import { composite, query, QueryBuilder } from './query'
+import { composite, query, QueryBuilder, QueryBuilderState } from './query'
 import { QueryRunner, run, SanityQueryError } from './runner'
 
+type ElementOf<T> = T extends (infer U)[] ? U : T
+
+type Field<T> = (keyof ElementOf<T> & string) | (string & {})
+
 export interface RunnableQuery {
   build(): string
   toString(): string
-  run<T>(runner?: QueryRunner<T>): Promise<Either<SanityQueryError, T | null>>
+  run<T>(runner?: QueryRunner<T>): AsyncEither<SanityQueryError, T | null>
 }
 
-export interface GroqBuilder extends QueryBuilder, RunnableQuery {
-  selector(selector: string): GroqBuilder
-  and(expr: string): GroqBuilder
-  or(...exprs: string[]): GroqBuilder
-  order(expr: string): GroqBuilder
-  slice(offset: number, limit?: number): GroqBuilder
-  first(): GroqBuilder
-  select(...fields: string[]): GroqBuilder
-  access(field: string, fieldAccess?: FieldAccess): GroqBuilder
-  dereference(): GroqBuilder
-  postFilter(expr: string): GroqBuilder
+interface Chainable<T, Self> {
+  selector(selector: string): Self
+  and(expr: string): Self
+  or(...exprs: string[]): Self
+  order(expr: string): Self
+  slice(offset: number, limit?: number): Self
+  select(...fields: Field<T>[]): Self
+  access(field: Field<T>, fieldAccess?: FieldAccess): Self
+  dereference(): Self
+  postFilter(expr: string): Self
+  build(): string
+  toString(): string
+
+  _state(): QueryBuilderState
+}
+
+/**
+ * `Empty` is what `run` resolves to when the query matched nothing. {@link GroqBuilder.default}
+ * supplies a fallback and narrows it to `never`, which is the state a builder is assumed to be in
+ * unless it says otherwise: a builder that has not been given one is a `GroqBuilder<T, null>`.
+ */
+export interface GroqBuilder<T = unknown, Empty = never> extends Chainable<T, GroqBuilder<T, Empty>> {
+  /**
+   * Never read. Methods are checked bivariantly, so without a property here a builder with no
+   * fallback would silently satisfy a signature promising one.
+   */
+  readonly __empty?: Empty
+
+  first(): GroqBuilder<ElementOf<T>, Empty>
+  default(value: T): GroqBuilder<T, never>
+  run<U = T>(runner?: QueryRunner<U>): AsyncEither<SanityQueryError, U | Empty>
 }
 
 /**
  * @param {string} selector
- * @returns {GroqBuilder}
+ * @returns {GroqBuilder<T>}
  * @example
  * const result = await groq()
  *   .and(f.type('song'))
@@ -32,13 +56,30 @@ export interface GroqBuilder extends QueryBuilder, RunnableQuery {
  *   .slice(0, 10)
  *   .select('_id', 'title')
  *   .run<Song[]>()
+ * @example
+ * // naming the type up front keeps it off every call in the chain
+ * const songs = await groq<Song[]>().and(f.type('song')).default([]).run()
  */
-const groqBuilder = (selector?: string): GroqBuilder => {
+const groqBuilder = <T = unknown>(selector?: string): GroqBuilder<T, null> => {
   const builder = query(selector)
+  let fallback: { value: unknown } | undefined
+
+  const runnable = Object.assign(builder, {
+    default: (value: unknown) => {
+      fallback = { value }
+      return runnable
+    },
+    run: <U = T>(runner?: QueryRunner<U>) => {
+      const result = run<U>(builder.build(), runner)
+      const fallbackAtRunTime = fallback
+
+      return fallbackAtRunTime
+        ? result.map((value) => value ?? (fallbackAtRunTime.value as U))
+        : result
+    },
+  })
 
-  return Object.assign(builder, {
-    run: <T>(runner?: QueryRunner<T>) => run<T>(builder.build(), runner),
-  }) as GroqBuilder
+  return runnable as unknown as GroqBuilder<T, null>
 }
 
 /**

package/src/lib/sanity/runner.ts

@@ -1,3 +1,4 @@
+import { AsyncEither } from '../ads/async-either'
 import { Either } from '../ads/either'
 import { SanityClient } from '../../infrastructure/sanity/SanityClient'
 
@@ -44,7 +45,7 @@ const defaultRunner = <T>(): QueryRunner<T> =>
 /**
  * @param {string} groq
  * @param {QueryRunner<T>} runner
- * @returns {Promise<Either<SanityQueryError, T | null>>}
+ * @returns {AsyncEither<SanityQueryError, T | null>}
  * @example
  * const result = await run<Song[]>(query().and(f.type('song')).build())
  * result.fold(
@@ -61,4 +62,4 @@ const defaultRunner = <T>(): QueryRunner<T> =>
 export const run = <T>(
   groq: string,
   runner: QueryRunner<T> = defaultRunner<T>()
-): Promise<Either<SanityQueryError, T | null>> => runner(groq)
+): AsyncEither<SanityQueryError, T | null> => AsyncEither.of(runner(groq))

package/src/lib/sanity/types/marketing.d.ts

@@ -92,3 +92,36 @@ export type FaqDocument = {
     answer?: string
   }[]
 }
+
+export type PromotionalCampaignDocument = {
+  _id: string
+  _type: "promotional-campaign"
+  _createdAt: string
+  _updatedAt: string
+  _rev: string
+  /** Campaign Name */
+  name: string
+  slug: { _type: "slug"; current: string }
+  /** Starts At */
+  starts_at: string
+  /** Ends At */
+  ends_at: string
+  /** Active? */
+  active?: boolean
+  /** Placements */
+  placements: {
+    _key: string
+    /** Placement Key */
+    key: string
+    title?: string
+    body?: string
+    /** Resolved to a CDN url by the promotions query projection. */
+    dark_mode_image?: string
+    /** Resolved to a CDN url by the promotions query projection. */
+    light_mode_image?: string
+    /** CTA Label */
+    cta_label?: string
+    /** Dismissible? */
+    dismissible?: boolean
+  }[]
+}

package/src/services/content/artist.ts

@@ -37,12 +37,11 @@ export async function fetchArtists(
 ): Promise<Artists> {
   const type = f.type('artist')
   const postFilter = `lesson_count > 0`
-  const { sort = 'lower(name)', offset = 0, limit = 20 } = options
+  const { sort = 'lower(name)', offset = 0, limit } = options
 
   const data = query()
     .and(type)
     .order(getSortOrder(sort, brand))
-    .slice(offset, limit)
     .select(
       'name',
       `"slug": slug.current`,
@@ -51,6 +50,8 @@ export async function fetchArtists(
     )
     .postFilter(postFilter)
 
+  if (limit) data.slice(offset, limit)
+
   const q = `{
     "data": ${data},
   }`
@@ -140,7 +141,7 @@ export async function fetchArtistLessons(
     f.notDeprecated(),
     f.referencesIDWithFilter(f.combine(f.type('artist'), f.slug(slug))),
     f.brand(brand),
-    f.permissions({showMembershipRestrictedContent: true}),
+    f.permissions({ showMembershipRestrictedContent: true }),
     f.searchMatch('title', searchTerm),
     f.includedFields(includedFields),
     f.progressIds(progressIds)

package/src/services/content/genre.ts

@@ -37,12 +37,11 @@ export async function fetchGenres(
 ): Promise<Genres> {
   const type = f.type('genre')
   const postFilter = `lesson_count > 0`
-  const { sort = 'lower(name)', offset = 0, limit = 20 } = options
+  const { sort = 'lower(name)', offset = 0, limit } = options
 
   const data = query()
     .and(type)
     .order(getSortOrder(sort, brand))
-    .slice(offset, limit)
     .select(
       'name',
       `"slug": slug.current`,
@@ -51,6 +50,8 @@ export async function fetchGenres(
     )
     .postFilter(postFilter)
 
+  if (limit) data.slice(offset, limit)
+
   const q = `{
     "data": ${data},
   }`
@@ -139,7 +140,7 @@ export async function fetchGenreLessons(
     f.notDeprecated(),
     f.referencesIDWithFilter(f.combine(f.type('genre'), f.slug(slug))),
     f.brand(brand),
-    f.permissions({showMembershipRestrictedContent: true}),
+    f.permissions({ showMembershipRestrictedContent: true }),
     f.searchMatch('title', searchTerm),
     f.includedFields(includedFields),
     f.progressIds(progressIds)

package/src/services/content/instructor.ts

@@ -38,12 +38,11 @@ export async function fetchInstructors(
 ): Promise<Instructors> {
   const type = f.type('instructor')
   const postFilter = `lesson_count > 0`
-  const { sort = 'lower(name)', offset = 0, limit = 20 } = options
+  const { sort = 'lower(name)', offset = 0, limit } = options
 
   const data = query()
     .and(type)
     .order(getSortOrder(sort, brand))
-    .slice(offset, limit)
     .select(
       'name',
       `"slug": slug.current`,
@@ -52,6 +51,8 @@ export async function fetchInstructors(
     )
     .postFilter(postFilter)
 
+  if (limit) data.slice(offset, limit)
+
   const q = `{
     "data": ${data},
   }`
@@ -129,7 +130,7 @@ export async function fetchInstructorLessons(
     offset = 0,
     limit = 20,
     includedFields = [],
-    contentType = null
+    contentType = null,
   }: InstructorLessonsOptions = {}
 ): Promise<InstructorLessons> {
   sort = getSortOrder(sort, brand)
@@ -140,7 +141,7 @@ export async function fetchInstructorLessons(
     f.notDeprecated(),
     f.referencesIDWithFilter(f.combine(f.type('instructor'), f.slug(slug))),
     f.brand(brand),
-    f.permissions({showMembershipRestrictedContent: true}),
+    f.permissions({ showMembershipRestrictedContent: true }),
     f.searchMatch('title', searchTerm),
     f.includedFields(includedFields)
   )