musora-content-services 2.185.1 → 2.186.1

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/awards/internal/award-definitions.js

@@ -132,6 +132,10 @@ class AwardDefinitionsService {
 
       const awards = await fetchSanity(query, true, { processNeedAccess: false, processPageType: false })
 
+      if (!awards) {
+        return
+      }
+
       this.definitions.clear()
       this.contentIndex.clear()