@sanity/client 0.0.0-dev.0

package/src/data/encodeQueryString.ts

@@ -0,0 +1,29 @@
+import type {Any, QueryParams} from '../types'
+
+export const encodeQueryString = ({
+  query,
+  params = {},
+  options = {},
+}: {
+  query: string
+  params?: QueryParams
+  options?: Any
+}) => {
+  const searchParams = new URLSearchParams()
+  // We generally want tag at the start of the query string
+  const {tag, ...opts} = options
+  if (tag) searchParams.set('tag', tag)
+  searchParams.set('query', query)
+
+  // Iterate params, the keys are prefixed with `$` and their values JSON stringified
+  for (const [key, value] of Object.entries(params)) {
+    searchParams.set(`$${key}`, JSON.stringify(value))
+  }
+  // Options are passed as-is
+  for (const [key, value] of Object.entries(opts)) {
+    // Skip falsy values
+    if (value) searchParams.set(key, `${value}`)
+  }
+
+  return `?${searchParams}`
+}

package/src/data/listen.ts

@@ -0,0 +1,196 @@
+import polyfilledEventSource from '@sanity/eventsource'
+import {Observable} from 'rxjs'
+
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {Any, ListenEvent, ListenOptions, MutationEvent, QueryParams} from '../types'
+import defaults from '../util/defaults'
+import {pick} from '../util/pick'
+import {_getDataUrl} from './dataMethods'
+import {encodeQueryString} from './encodeQueryString'
+
+// Limit is 16K for a _request_, eg including headers. Have to account for an
+// unknown range of headers, but an average EventSource request from Chrome seems
+// to have around 700 bytes of cruft, so let us account for 1.2K to be "safe"
+const MAX_URL_LENGTH = 16000 - 1200
+const EventSource = polyfilledEventSource
+
+const possibleOptions = [
+  'includePreviousRevision',
+  'includeResult',
+  'visibility',
+  'effectFormat',
+  'tag',
+]
+
+const defaultOptions = {
+  includeResult: true,
+}
+
+/**
+ * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
+ *
+ * @param query - GROQ-filter to listen to changes for
+ * @param params - Optional query parameters
+ * @param options - Listener options
+ * @internal
+ */
+export function _listen<R extends Record<string, Any> = Record<string, Any>>(
+  this: SanityClient | ObservableSanityClient,
+  query: string,
+  params?: QueryParams
+): Observable<MutationEvent<R>>
+/**
+ * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
+ *
+ * @param query - GROQ-filter to listen to changes for
+ * @param params - Optional query parameters
+ * @param options - Listener options
+ * @internal
+ */
+export function _listen<R extends Record<string, Any> = Record<string, Any>>(
+  this: SanityClient | ObservableSanityClient,
+  query: string,
+  params?: QueryParams,
+  options?: ListenOptions
+): Observable<ListenEvent<R>>
+/** @internal */
+export function _listen<R extends Record<string, Any> = Record<string, Any>>(
+  this: SanityClient | ObservableSanityClient,
+  query: string,
+  params?: QueryParams,
+  opts: ListenOptions = {}
+): Observable<MutationEvent<R> | ListenEvent<R>> {
+  const {url, token, withCredentials, requestTagPrefix} = this.config()
+  const tag = opts.tag && requestTagPrefix ? [requestTagPrefix, opts.tag].join('.') : opts.tag
+  const options = {...defaults(opts, defaultOptions), tag}
+  const listenOpts = pick(options, possibleOptions)
+  const qs = encodeQueryString({query, params, options: {tag, ...listenOpts}})
+
+  const uri = `${url}${_getDataUrl(this, 'listen', qs)}`
+  if (uri.length > MAX_URL_LENGTH) {
+    return new Observable((observer) => observer.error(new Error('Query too large for listener')))
+  }
+
+  const listenFor = options.events ? options.events : ['mutation']
+  const shouldEmitReconnect = listenFor.indexOf('reconnect') !== -1
+
+  const esOptions: EventSourceInit & {headers?: Record<string, string>} = {}
+  if (token || withCredentials) {
+    esOptions.withCredentials = true
+  }
+
+  if (token) {
+    esOptions.headers = {
+      Authorization: `Bearer ${token}`,
+    }
+  }
+
+  return new Observable((observer) => {
+    let es = getEventSource()
+    let reconnectTimer: NodeJS.Timeout
+    let stopped = false
+
+    function onError() {
+      if (stopped) {
+        return
+      }
+
+      emitReconnect()
+
+      // Allow event handlers of `emitReconnect` to cancel/close the reconnect attempt
+      if (stopped) {
+        return
+      }
+
+      // Unless we've explicitly stopped the ES (in which case `stopped` should be true),
+      // we should never be in a disconnected state. By default, EventSource will reconnect
+      // automatically, in which case it sets readyState to `CONNECTING`, but in some cases
+      // (like when a laptop lid is closed), it closes the connection. In these cases we need
+      // to explicitly reconnect.
+      if (es.readyState === EventSource.CLOSED) {
+        unsubscribe()
+        clearTimeout(reconnectTimer)
+        reconnectTimer = setTimeout(open, 100)
+      }
+    }
+
+    function onChannelError(err: Any) {
+      observer.error(cooerceError(err))
+    }
+
+    function onMessage(evt: Any) {
+      const event = parseEvent(evt)
+      return event instanceof Error ? observer.error(event) : observer.next(event)
+    }
+
+    function onDisconnect() {
+      stopped = true
+      unsubscribe()
+      observer.complete()
+    }
+
+    function unsubscribe() {
+      es.removeEventListener('error', onError, false)
+      es.removeEventListener('channelError', onChannelError, false)
+      es.removeEventListener('disconnect', onDisconnect, false)
+      listenFor.forEach((type: string) => es.removeEventListener(type, onMessage, false))
+      es.close()
+    }
+
+    function emitReconnect() {
+      if (shouldEmitReconnect) {
+        observer.next({type: 'reconnect'})
+      }
+    }
+
+    function getEventSource() {
+      const evs = new EventSource(uri, esOptions)
+      evs.addEventListener('error', onError, false)
+      evs.addEventListener('channelError', onChannelError, false)
+      evs.addEventListener('disconnect', onDisconnect, false)
+      listenFor.forEach((type: string) => evs.addEventListener(type, onMessage, false))
+      return evs
+    }
+
+    function open() {
+      es = getEventSource()
+    }
+
+    function stop() {
+      stopped = true
+      unsubscribe()
+    }
+
+    return stop
+  })
+}
+
+function parseEvent(event: Any) {
+  try {
+    const data = (event.data && JSON.parse(event.data)) || {}
+    return Object.assign({type: event.type}, data)
+  } catch (err) {
+    return err
+  }
+}
+
+function cooerceError(err: Any) {
+  if (err instanceof Error) {
+    return err
+  }
+
+  const evt = parseEvent(err)
+  return evt instanceof Error ? evt : new Error(extractErrorMessage(evt))
+}
+
+function extractErrorMessage(err: Any) {
+  if (!err.error) {
+    return err.message || 'Unknown listener error'
+  }
+
+  if (err.error.description) {
+    return err.error.description
+  }
+
+  return typeof err.error === 'string' ? err.error : JSON.stringify(err.error, null, 2)
+}

package/src/data/patch.ts

@@ -0,0 +1,345 @@
+import {type Observable} from 'rxjs'
+
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {
+  AllDocumentIdsMutationOptions,
+  AllDocumentsMutationOptions,
+  Any,
+  AttributeSet,
+  BaseMutationOptions,
+  FirstDocumentIdMutationOptions,
+  FirstDocumentMutationOptions,
+  MultipleMutationResult,
+  PatchMutationOperation,
+  PatchOperations,
+  PatchSelection,
+  SanityDocument,
+  SingleMutationResult,
+} from '../types'
+import {getSelection} from '../util/getSelection'
+import {validateInsert, validateObject} from '../validators'
+
+/** @internal */
+export class BasePatch {
+  protected selection: PatchSelection
+  protected operations: PatchOperations
+  constructor(selection: PatchSelection, operations: PatchOperations = {}) {
+    this.selection = selection
+    this.operations = operations
+  }
+
+  /**
+   * Sets the given attributes to the document. Does NOT merge objects.
+   * The operation is added to the current patch, ready to be commited by `commit()`
+   *
+   * @param attrs - Attributes to set. To set a deep attribute, use JSONMatch, eg: \{"nested.prop": "value"\}
+   */
+  set(attrs: AttributeSet): this {
+    return this._assign('set', attrs)
+  }
+
+  /**
+   * Sets the given attributes to the document if they are not currently set. Does NOT merge objects.
+   * The operation is added to the current patch, ready to be commited by `commit()`
+   *
+   * @param attrs - Attributes to set. To set a deep attribute, use JSONMatch, eg: \{"nested.prop": "value"\}
+   */
+  setIfMissing(attrs: AttributeSet): this {
+    return this._assign('setIfMissing', attrs)
+  }
+
+  /**
+   * Performs a "diff-match-patch" operation on the string attributes provided.
+   * The operation is added to the current patch, ready to be commited by `commit()`
+   *
+   * @param attrs - Attributes to perform operation on. To set a deep attribute, use JSONMatch, eg: \{"nested.prop": "dmp"\}
+   */
+  diffMatchPatch(attrs: AttributeSet): this {
+    validateObject('diffMatchPatch', attrs)
+    return this._assign('diffMatchPatch', attrs)
+  }
+
+  /**
+   * Unsets the attribute paths provided.
+   * The operation is added to the current patch, ready to be commited by `commit()`
+   *
+   * @param attrs - Attribute paths to unset.
+   */
+  unset(attrs: string[]): this {
+    if (!Array.isArray(attrs)) {
+      throw new Error('unset(attrs) takes an array of attributes to unset, non-array given')
+    }
+
+    this.operations = Object.assign({}, this.operations, {unset: attrs})
+    return this
+  }
+
+  /**
+   * Increment a numeric value. Each entry in the argument is either an attribute or a JSON path. The value may be a positive or negative integer or floating-point value. The operation will fail if target value is not a numeric value, or doesn't exist.
+   *
+   * @param attrs - Object of attribute paths to increment, values representing the number to increment by.
+   */
+  inc(attrs: {[key: string]: number}): this {
+    return this._assign('inc', attrs)
+  }
+
+  /**
+   * Decrement a numeric value. Each entry in the argument is either an attribute or a JSON path. The value may be a positive or negative integer or floating-point value. The operation will fail if target value is not a numeric value, or doesn't exist.
+   *
+   * @param attrs - Object of attribute paths to decrement, values representing the number to decrement by.
+   */
+  dec(attrs: {[key: string]: number}): this {
+    return this._assign('dec', attrs)
+  }
+
+  /**
+   * Provides methods for modifying arrays, by inserting, appending and replacing elements via a JSONPath expression.
+   *
+   * @param at - Location to insert at, relative to the given selector, or 'replace' the matched path
+   * @param selector - JSONPath expression, eg `comments[-1]` or `blocks[_key=="abc123"]`
+   * @param items - Array of items to insert/replace
+   */
+  insert(at: 'before' | 'after' | 'replace', selector: string, items: Any[]): this {
+    validateInsert(at, selector, items)
+    return this._assign('insert', {[at]: selector, items})
+  }
+
+  /**
+   * Append the given items to the array at the given JSONPath
+   *
+   * @param selector - Attribute/path to append to, eg `comments` or `person.hobbies`
+   * @param items - Array of items to append to the array
+   */
+  append(selector: string, items: Any[]): this {
+    return this.insert('after', `${selector}[-1]`, items)
+  }
+
+  /**
+   * Prepend the given items to the array at the given JSONPath
+   *
+   * @param selector - Attribute/path to prepend to, eg `comments` or `person.hobbies`
+   * @param items - Array of items to prepend to the array
+   */
+  prepend(selector: string, items: Any[]): this {
+    return this.insert('before', `${selector}[0]`, items)
+  }
+
+  /**
+   * Change the contents of an array by removing existing elements and/or adding new elements.
+   *
+   * @param selector - Attribute or JSONPath expression for array
+   * @param start - Index at which to start changing the array (with origin 0). If greater than the length of the array, actual starting index will be set to the length of the array. If negative, will begin that many elements from the end of the array (with origin -1) and will be set to 0 if absolute value is greater than the length of the array.x
+   * @param deleteCount - An integer indicating the number of old array elements to remove.
+   * @param items - The elements to add to the array, beginning at the start index. If you don't specify any elements, splice() will only remove elements from the array.
+   */
+  splice(selector: string, start: number, deleteCount?: number, items?: Any[]): this {
+    // Negative indexes doesn't mean the same in Sanity as they do in JS;
+    // -1 means "actually at the end of the array", which allows inserting
+    // at the end of the array without knowing its length. We therefore have
+    // to substract negative indexes by one to match JS. If you want Sanity-
+    // behaviour, just use `insert('replace', selector, items)` directly
+    const delAll = typeof deleteCount === 'undefined' || deleteCount === -1
+    const startIndex = start < 0 ? start - 1 : start
+    const delCount = delAll ? -1 : Math.max(0, start + deleteCount)
+    const delRange = startIndex < 0 && delCount >= 0 ? '' : delCount
+    const rangeSelector = `${selector}[${startIndex}:${delRange}]`
+    return this.insert('replace', rangeSelector, items || [])
+  }
+
+  /**
+   * Adds a revision clause, preventing the document from being patched if the `_rev` property does not match the given value
+   *
+   * @param rev - Revision to lock the patch to
+   */
+  ifRevisionId(rev: string): this {
+    this.operations.ifRevisionID = rev
+    return this
+  }
+
+  /**
+   * Return a plain JSON representation of the patch
+   */
+  serialize(): PatchMutationOperation {
+    return {...getSelection(this.selection), ...this.operations}
+  }
+
+  /**
+   * Return a plain JSON representation of the patch
+   */
+  toJSON(): PatchMutationOperation {
+    return this.serialize()
+  }
+
+  /**
+   * Clears the patch of all operations
+   */
+  reset(): this {
+    this.operations = {}
+    return this
+  }
+
+  protected _assign(op: keyof PatchOperations, props: Any, merge = true): this {
+    validateObject(op, props)
+    this.operations = Object.assign({}, this.operations, {
+      [op]: Object.assign({}, (merge && this.operations[op]) || {}, props),
+    })
+    return this
+  }
+
+  protected _set(op: keyof PatchOperations, props: Any): this {
+    return this._assign(op, props, false)
+  }
+}
+
+/** @public */
+export class ObservablePatch extends BasePatch {
+  #client?: ObservableSanityClient
+
+  constructor(
+    selection: PatchSelection,
+    operations?: PatchOperations,
+    client?: ObservableSanityClient
+  ) {
+    super(selection, operations)
+    this.#client = client
+  }
+
+  /**
+   * Clones the patch
+   */
+  clone(): ObservablePatch {
+    return new ObservablePatch(this.selection, {...this.operations}, this.#client)
+  }
+
+  /**
+   * Commit the patch, returning an observable that produces the first patched document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options: FirstDocumentMutationOptions
+  ): Observable<SanityDocument<R>>
+  /**
+   * Commit the patch, returning an observable that produces an array of the mutated documents
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options: AllDocumentsMutationOptions
+  ): Observable<SanityDocument<R>[]>
+  /**
+   * Commit the patch, returning an observable that produces a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: FirstDocumentIdMutationOptions): Observable<SingleMutationResult>
+  /**
+   * Commit the patch, returning an observable that produces a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: AllDocumentIdsMutationOptions): Observable<MultipleMutationResult>
+  /**
+   * Commit the patch, returning an observable that produces the first patched document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?: BaseMutationOptions
+  ): Observable<SanityDocument<R>>
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?:
+      | FirstDocumentMutationOptions
+      | AllDocumentsMutationOptions
+      | FirstDocumentIdMutationOptions
+      | AllDocumentIdsMutationOptions
+      | BaseMutationOptions
+  ): Observable<
+    SanityDocument<R> | SanityDocument<R>[] | SingleMutationResult | MultipleMutationResult
+  > {
+    if (!this.#client) {
+      throw new Error(
+        'No `client` passed to patch, either provide one or pass the ' +
+          'patch to a clients `mutate()` method'
+      )
+    }
+
+    const returnFirst = typeof this.selection === 'string'
+    const opts = Object.assign({returnFirst, returnDocuments: true}, options)
+    return this.#client.mutate<R>({patch: this.serialize()} as Any, opts)
+  }
+}
+
+/** @public */
+export class Patch extends BasePatch {
+  #client?: SanityClient
+  constructor(selection: PatchSelection, operations?: PatchOperations, client?: SanityClient) {
+    super(selection, operations)
+    this.#client = client
+  }
+
+  /**
+   * Clones the patch
+   */
+  clone(): Patch {
+    return new Patch(this.selection, {...this.operations}, this.#client)
+  }
+
+  /**
+   * Commit the patch, returning a promise that resolves to the first patched document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options: FirstDocumentMutationOptions
+  ): Promise<SanityDocument<R>>
+  /**
+   * Commit the patch, returning a promise that resolves to an array of the mutated documents
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options: AllDocumentsMutationOptions
+  ): Promise<SanityDocument<R>[]>
+  /**
+   * Commit the patch, returning a promise that resolves to a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: FirstDocumentIdMutationOptions): Promise<SingleMutationResult>
+  /**
+   * Commit the patch, returning a promise that resolves to a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: AllDocumentIdsMutationOptions): Promise<MultipleMutationResult>
+  /**
+   * Commit the patch, returning a promise that resolves to the first patched document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?: BaseMutationOptions
+  ): Promise<SanityDocument<R>>
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?:
+      | FirstDocumentMutationOptions
+      | AllDocumentsMutationOptions
+      | FirstDocumentIdMutationOptions
+      | AllDocumentIdsMutationOptions
+      | BaseMutationOptions
+  ): Promise<
+    SanityDocument<R> | SanityDocument<R>[] | SingleMutationResult | MultipleMutationResult
+  > {
+    if (!this.#client) {
+      throw new Error(
+        'No `client` passed to patch, either provide one or pass the ' +
+          'patch to a clients `mutate()` method'
+      )
+    }
+
+    const returnFirst = typeof this.selection === 'string'
+    const opts = Object.assign({returnFirst, returnDocuments: true}, options)
+    return this.#client.mutate<R>({patch: this.serialize()} as Any, opts)
+  }
+}