fp-ts-std/dist/types/URLSearchParams.d.ts

The missing pseudo-standard library for fp-ts.

/**
 * Various functions to aid in working with JavaScript's `URLSearchParams`
 * interface. It can be thought of similarly to `Map<string, Array<string>>`.
 *
 * @since 0.2.0
 */
import * as NEA from "fp-ts/NonEmptyArray";
import type { Option } from "fp-ts/Option";
import { type Predicate } from "fp-ts/Predicate";
import type { Refinement } from "fp-ts/Refinement";
type NonEmptyArray<A> = NEA.NonEmptyArray<A>;
import type { Endomorphism } from "fp-ts/Endomorphism";
import type * as Eq_ from "fp-ts/Eq";
type Eq<A> = Eq_.Eq<A>;
import type * as Monoid_ from "fp-ts/Monoid";
import type { Semigroup as SemigroupT } from "fp-ts/Semigroup";
type Monoid<A> = Monoid_.Monoid<A>;
/**
 * An empty `URLSearchParams`.
 *
 * @example
 * import { empty } from 'fp-ts-std/URLSearchParams'
 *
 * assert.deepStrictEqual(empty, new URLSearchParams())
 *
 * @category 3 Functions
 * @since 0.2.0
 */
export declare const empty: URLSearchParams;
/**
 * Test if there are any search params.
 *
 * @example
 * import { isEmpty } from 'fp-ts-std/URLSearchParams'
 *
 * assert.strictEqual(isEmpty(new URLSearchParams()), true)
 * assert.strictEqual(isEmpty(new URLSearchParams({ k: 'v' })), false)
 *
 * @category 3 Functions
 * @since 0.16.0
 */
export declare const isEmpty: Predicate<URLSearchParams>;
/**
 * Parse a `URLSearchParams` from a string.
 *
 * @example
 * import { fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = 'a=b&c=d'
 *
 * assert.deepStrictEqual(fromString(x), new URLSearchParams(x))
 *
 * @category 3 Functions
 * @since 0.2.0
 */
export declare const fromString: (x: string) => URLSearchParams;
/**
 * Returns a query string suitable for use in a URL, absent a question mark.
 *
 * @example
 * import { toString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = new URLSearchParams('a=b&c=d')
 *
 * assert.strictEqual(toString(x), 'a=b&c=d')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const toString: (x: URLSearchParams) => string;
/**
 * Like `toString`, but includes a leading question mark if the params are
 * non-empty.
 *
 * @example
 * import { toString, toLeadingString } from 'fp-ts-std/URLSearchParams'
 *
 * assert.strictEqual(toString(new URLSearchParams('')), '')
 * assert.strictEqual(toString(new URLSearchParams('a=b')), 'a=b')
 *
 * assert.strictEqual(toLeadingString(new URLSearchParams('')), '')
 * assert.strictEqual(toLeadingString(new URLSearchParams('a=b')), '?a=b')
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const toLeadingString: (xs: URLSearchParams) => string;
/**
 * Parse a `URLSearchParams` from an array of tuples.
 *
 * @example
 * import { fromTuples } from 'fp-ts-std/URLSearchParams'
 *
 * const x: Array<[string, string]> = [['a', 'b'], ['c', 'd']]
 *
 * assert.deepStrictEqual(fromTuples(x), new URLSearchParams(x))
 *
 * @category 3 Functions
 * @since 0.2.0
 */
export declare const fromTuples: (x: Array<[string, string]>) => URLSearchParams;
/**
 * Construct a `URLSearchParams` from a single key/value pair.
 *
 * @example
 * import { singleton } from 'fp-ts-std/URLSearchParams'
 *
 * assert.deepStrictEqual(singleton('k')('v'), new URLSearchParams({ k: 'v' }))
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const singleton: (k: string) => (v: string) => URLSearchParams;
/**
 * Losslessly convert a `URLSearchParams` to an array of tuples.
 *
 * @example
 * import { toTuples } from 'fp-ts-std/URLSearchParams'
 *
 * const x = new URLSearchParams('a=b&c=d&a=e')
 *
 * assert.deepStrictEqual(toTuples(x), [['a', 'b'], ['c', 'd'], ['a', 'e']])
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const toTuples: (x: URLSearchParams) => Array<[string, string]>;
/**
 * Parse a `URLSearchParams` from a record.
 *
 * @example
 * import { fromRecord } from 'fp-ts-std/URLSearchParams'
 *
 * const r = { a: ['b', 'c'], d: ['e'] }
 * const s = 'a=b&a=c&d=e'
 *
 * assert.deepStrictEqual(fromRecord(r), new URLSearchParams(s))
 *
 * @category 3 Functions
 * @since 0.2.0
 */
export declare const fromRecord: (x: Record<string, Array<string>>) => URLSearchParams;
/**
 * Convert a `URLSearchParams` to a record, grouping values by keys.
 *
 * @example
 * import { toRecord } from 'fp-ts-std/URLSearchParams'
 *
 * const x = new URLSearchParams('a=b&c=d&a=e')
 *
 * assert.deepStrictEqual(toRecord(x), { a: ['b', 'e'], c: ['d'] })
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const toRecord: (x: URLSearchParams) => Record<string, NonEmptyArray<string>>;
/**
 * An `Eq` instance for `URLSearchParams` in which equivalence is determined
 * without respect to order.
 *
 * @example
 * import { Eq, fromString as f } from 'fp-ts-std/URLSearchParams'
 *
 * assert.strictEqual(Eq.equals(f('a=1&b=2&a=3'), f('b=2&a=3&a=1')), true)
 * assert.strictEqual(Eq.equals(f('a=1&b=2&a=3'), f('a=1&b=2')), false)
 *
 * @category 1 Typeclass Instances
 * @since 0.18.0
 */
export declare const Eq: Eq<URLSearchParams>;
/**
 * Clone a `URLSearchParams`.
 *
 * @example
 * import { clone, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = fromString('a=b&c=d')
 *
 * assert.strictEqual(x === clone(x), false)
 * assert.deepStrictEqual(x, clone(x))
 *
 * @category 3 Functions
 * @since 0.2.0
 */
export declare const clone: (x: URLSearchParams) => URLSearchParams;
/**
 * Refine a foreign value to `URLSearchParams`.
 *
 * @example
 * import { isURLSearchParams, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = fromString('a=b&c=d')
 *
 * assert.deepStrictEqual(isURLSearchParams(x), true)
 * assert.deepStrictEqual(isURLSearchParams({ not: { a: 'urlsearchparams' } }), false)
 *
 * @category 3 Functions
 * @since 0.1.0
 */
export declare const isURLSearchParams: Refinement<unknown, URLSearchParams>;
/**
 * Attempt to get the first match for a URL parameter from a `URLSearchParams`.
 *
 * @example
 * import { lookupFirst, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d1&c=d2')
 *
 * assert.deepStrictEqual(lookupFirst('c')(x), O.some('d1'))
 * assert.deepStrictEqual(lookupFirst('e')(x), O.none)
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const lookupFirst: (k: string) => (ps: URLSearchParams) => Option<string>;
/**
 * Attempt to get the first match for a URL parameter from a `URLSearchParams`.
 *
 * @example
 * import { getParam, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d1&c=d2')
 *
 * assert.deepStrictEqual(getParam('c')(x), O.some('d1'))
 * assert.deepStrictEqual(getParam('e')(x), O.none)
 *
 * @deprecated Prefer `lookupFirst`.
 * @category 5 Zone of Death
 * @since 0.1.0
 */
export declare const getParam: (k: string) => (ps: URLSearchParams) => Option<string>;
/**
 * Attempt to get all matches for a URL parameter from a `URLSearchParams`.
 *
 * @example
 * import { lookup, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d1&c=d2')
 *
 * assert.deepStrictEqual(lookup('a')(x), O.some(['b']))
 * assert.deepStrictEqual(lookup('c')(x), O.some(['d1', 'd2']))
 * assert.deepStrictEqual(lookup('e')(x), O.none)
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const lookup: (k: string) => (ps: URLSearchParams) => Option<NonEmptyArray<string>>;
/**
 * Attempt to get all matches for a URL parameter from a `URLSearchParams`.
 *
 * @example
 * import { getAllForParam, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d1&c=d2')
 *
 * assert.deepStrictEqual(getAllForParam('a')(x), O.some(['b']))
 * assert.deepStrictEqual(getAllForParam('c')(x), O.some(['d1', 'd2']))
 * assert.deepStrictEqual(getAllForParam('e')(x), O.none)
 *
 * @deprecated Prefer `lookup`.
 * @category 5 Zone of Death
 * @since 0.16.0
 */
export declare const getAllForParam: (k: string) => (ps: URLSearchParams) => Option<NonEmptyArray<string>>;
/**
 * Insert or replace a URL parameter in a `URLSearchParams`.
 *
 * @example
 * import { upsertAt, lookupFirst, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d')
 * const y = upsertAt('c')('e')(x)
 *
 * const f = lookupFirst('c')
 *
 * assert.deepStrictEqual(f(x), O.some('d'))
 * assert.deepStrictEqual(f(y), O.some('e'))
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const upsertAt: (k: string) => (v: string) => Endomorphism<URLSearchParams>;
/**
 * Set a URL parameter in a `URLSearchParams`.
 *
 * @example
 * import { setParam, lookupFirst, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d')
 * const y = setParam('c')('e')(x)
 *
 * const f = lookupFirst('c')
 *
 * assert.deepStrictEqual(f(x), O.some('d'))
 * assert.deepStrictEqual(f(y), O.some('e'))
 *
 * @deprecated Prefer `upsertAt`.
 * @category 5 Zone of Death
 * @since 0.1.0
 */
export declare const setParam: (k: string) => (v: string) => Endomorphism<URLSearchParams>;
/**
 * Append a URL parameter in a `URLSearchParams`.
 *
 * @example
 * import { appendAt, lookup, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d')
 * const y = appendAt('c')('e')(x)
 *
 * const f = lookup('c')
 *
 * assert.deepStrictEqual(f(x), O.some(['d']))
 * assert.deepStrictEqual(f(y), O.some(['d', 'e']))
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const appendAt: (k: string) => (v: string) => Endomorphism<URLSearchParams>;
/**
 * Delete all URL parameters with the specified key.
 *
 * @example
 * import { deleteAt, lookup, fromString } from 'fp-ts-std/URLSearchParams'
 * import * as O from 'fp-ts/Option'
 *
 * const x = fromString('a=b&c=d&a=e')
 * const y = deleteAt('a')(x)
 *
 * const f = lookup('a')
 *
 * assert.deepStrictEqual(f(x), O.some(['b', 'e']))
 * assert.deepStrictEqual(f(y), O.none)
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const deleteAt: (k: string) => Endomorphism<URLSearchParams>;
/**
 * Get an unsorted, potentially duplicative array of the keys in a
 * `URLSearchParams`.
 *
 * @example
 * import { keys, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = fromString('a=b&c=d&a=e')
 *
 * assert.deepStrictEqual(keys(x), ['a', 'c', 'a'])
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const keys: (x: URLSearchParams) => Array<string>;
/**
 * Get a flattened array of all the values in a `URLSearchParams`.
 *
 * @example
 * import { values, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = fromString('a=b&c=d&a=e')
 *
 * assert.deepStrictEqual(values(x), ['b', 'd', 'e'])
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const values: (x: URLSearchParams) => Array<string>;
/**
 * Get the number of potentially duplicative key/value pairs in a
 * `URLSearchParams`.
 *
 * @example
 * import { size, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const x = fromString('a=b&c=d&a=e')
 *
 * assert.strictEqual(size(x), 3)
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const size: (x: URLSearchParams) => number;
/**
 * Concat two `URLSearchParams` according to `f` in case of conflicts. The
 * `Array` in the return type of `f` encodes the possibility to set the key
 * once, multiple times, or not at all. Output order is unspecified.
 *
 * @example
 * import { concatBy, fromString, toString } from 'fp-ts-std/URLSearchParams'
 * import { fst } from 'fp-ts/Tuple'
 * import { constant } from 'fp-ts/function'
 *
 * const concatFirst = concatBy(constant(fst))
 *
 * const xs = fromString('a=1&b=2&a=3')
 * const ys = fromString('b=1&c=2')
 *
 * assert.deepStrictEqual(concatFirst(xs)(ys), fromString('a=1&a=3&b=2&c=2'))
 * assert.deepStrictEqual(concatFirst(ys)(xs), fromString('b=1&c=2&a=1&a=3'))
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const concatBy: (f: (k: string) => (vs: [NonEmptyArray<string>, NonEmptyArray<string>]) => Array<string>) => (xs: URLSearchParams) => Endomorphism<URLSearchParams>;
/**
 * A `Semigroup` instance for `URLSearchParams` in which all key/value pairs
 * are preserved.
 *
 * @example
 * import { Semigroup, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const xs = fromString("a=1&b=2&a=3")
 * const ys = fromString("b=4&c=5")
 *
 * const f = Semigroup.concat
 *
 * assert.deepStrictEqual(f(xs, ys), fromString("a=1&a=3&b=4&b=2&c=5"))
 * assert.deepStrictEqual(f(ys, xs), fromString("b=2&b=4&c=5&a=1&a=3"))
 *
 * @category 1 Typeclass Instances
 * @since 0.18.0
 */
export declare const Semigroup: SemigroupT<URLSearchParams>;
/**
 * A `Monoid` instance for `URLSearchParams` in which all key/value pairs are
 * preserved.
 *
 * @example
 * import { Monoid, empty } from 'fp-ts-std/URLSearchParams'
 *
 * assert.deepStrictEqual(Monoid.empty, empty)
 *
 * @category 1 Typeclass Instances
 * @since 0.18.0
 */
export declare const Monoid: Monoid<URLSearchParams>;
/**
 * Convert a `Map` to a `URLSearchParams`.
 *
 * @example
 * import { fromMap, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const m: Map<string, Array<string>> = new Map([ ['a', ['b', 'c']], ['d', ['e', 'f']] ])
 * const s = 'a=b&a=c&d=e&d=f'
 *
 * assert.deepStrictEqual(fromMap(m), fromString(s))
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const fromMap: (x: Map<string, Array<string>>) => URLSearchParams;
/**
 * Convert a `URLSearchParams` to a `Map`, grouping values by keys.
 *
 * @example
 * import { toMap, fromString } from 'fp-ts-std/URLSearchParams'
 *
 * const u = fromString("a=1&b=3&a=2&b=4")
 * const m = new Map([ ['a', ['1', '2']], ['b', ['3', '4']] ])
 *
 * assert.deepStrictEqual(toMap(u), m)
 *
 * @category 3 Functions
 * @since 0.18.0
 */
export declare const toMap: (x: URLSearchParams) => Map<string, NonEmptyArray<string>>;
export {};
//# sourceMappingURL=URLSearchParams.d.ts.map