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

The missing pseudo-standard library for fp-ts.

/**
 * A wrapper around the `URL` interface for URL paths absent an origin, which
 * `URL` doesn't natively support.
 *
 * A path is made up of three parts: the pathname, the search params, and the
 * hash.
 *
 * @since 0.17.0
 */
import type { Endomorphism } from "fp-ts/Endomorphism";
import * as Eq_ from "fp-ts/Eq";
import type { Refinement } from "fp-ts/Refinement";
import type { Newtype } from "newtype-ts";
import * as URL from "./URL";
type Eq<A> = Eq_.Eq<A>;
type URLPathSymbol = {
    readonly URLPathSymbol: unique symbol;
};
/**
 * Newtype wrapper around `URL`.
 *
 * @example
 * import { URLPath, fromPathname } from 'fp-ts-std/URLPath'
 *
 * const path: URLPath = fromPathname('/foo/bar')
 *
 * @category 0 Types
 * @since 0.17.0
 */
export type URLPath = Newtype<URLPathSymbol, URL>;
/**
 * Check if a foreign value is a `URLPath`.
 *
 * @example
 * import { isURLPath, fromPathname } from 'fp-ts-std/URLPath'
 *
 * assert.strictEqual(isURLPath(new URL('https://samhh.com/foo')), false)
 * assert.strictEqual(isURLPath(fromPathname('/foo')), true)
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const isURLPath: Refinement<unknown, URLPath>;
/**
 * Clone a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { clone, fromPathname, getPathname } from 'fp-ts-std/URLPath'
 *
 * const x = fromPathname('/foo')
 * const y = clone(x)
 * ;(x as unknown as URL).pathname = '/bar'
 *
 * assert.strictEqual(getPathname(x), '/bar')
 * assert.strictEqual(getPathname(y), '/foo')
 *
 * @category 3 Functions
 * @since 0.19.0
 */
export declare const clone: Endomorphism<URLPath>;
/**
 * Convert a `URL` to a `URLPath`. Anything prior to the path such as the origin
 * will be lost.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, toString } from 'fp-ts-std/URLPath'
 *
 * const x = fromURL(new URL('https://samhh.com/foo?bar=baz'))
 *
 * assert.strictEqual(toString(x), '/foo?bar=baz')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const fromURL: (x: URL) => URLPath;
/**
 * Convert a `URLPath` to a `URL` with the provided `origin`. Any other parts of
 * `origin` will be lost.
 *
 * @example
 * import { constant } from 'fp-ts/function';
 * import * as E from 'fp-ts/Either';
 * import { toURL, fromPathname } from 'fp-ts-std/URLPath'
 *
 * const f = toURL
 * const x = fromPathname('/foo')
 *
 * assert.deepStrictEqual(
 *   f(new URL('https://samhh.com'))(x),
 *   new URL('https://samhh.com/foo'),
 * )
 *
 * assert.deepStrictEqual(
 *   f(new URL('https://samhh.com/bar'))(x),
 *   new URL('https://samhh.com/foo'),
 * )
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const toURL: (origin: URL) => (path: URLPath) => URL;
/**
 * Build a `URLPath` from a string containing any parts.
 *
 * Absolute URL strings will be parsed as if they were relative URL strings.
 *
 * Consider also `fromPathname` where only a pathname needs to be parsed.
 *
 * @example
 * import { pipe, constant } from 'fp-ts/function';
 * import * as E from 'fp-ts/Either';
 * import { fromString, fromPathname, setHash } from 'fp-ts-std/URLPath'
 *
 * assert.deepStrictEqual(
 *   fromString('/foo#bar'),
 *   pipe('/foo', fromPathname, setHash('bar')),
 * )
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const fromString: (x: string) => URLPath;
/**
 * Build a `URLPath` from a path. Characters such as `?` will be encoded.
 *
 * @example
 * import { flow } from 'fp-ts/function'
 * import { fromPathname, getPathname } from 'fp-ts-std/URLPath'
 *
 * const f = flow(fromPathname, getPathname)
 *
 * assert.strictEqual(f('/foo?bar=baz'), '/foo%3Fbar=baz')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const fromPathname: (x: string) => URLPath;
/**
 * Deconstruct a `URLPath` to a string.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { toString, fromPathname, setParams, setHash } from 'fp-ts-std/URLPath'
 *
 * const x = pipe(
 *   fromPathname('/foo'),
 *   setParams(new URLSearchParams('bar=2000')),
 *   setHash('baz')
 * )
 *
 * assert.strictEqual(toString(x), '/foo?bar=2000#baz')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const toString: (x: URLPath) => string;
/**
 * Get the pathname component of a `URLPath`.
 *
 * @example
 * import { flow } from 'fp-ts/function'
 * import { fromPathname, getPathname } from 'fp-ts-std/URLPath'
 *
 * const f = flow(fromPathname, getPathname)
 *
 * assert.strictEqual(f('/foo'), '/foo')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const getPathname: (x: URLPath) => string;
/**
 * Modify the pathname component of a `URLPath`.
 *
 * @example
 * import { flow } from 'fp-ts/function'
 * import { fromPathname, modifyPathname, getPathname } from 'fp-ts-std/URLPath'
 *
 * const f = flow(fromPathname, modifyPathname(s => s + 'bar'), getPathname)
 *
 * assert.strictEqual(f('/foo'), '/foobar')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const modifyPathname: (f: Endomorphism<string>) => Endomorphism<URLPath>;
/**
 * Set the pathname component of a `URLPath`.
 *
 * @example
 * import { flow } from 'fp-ts/function'
 * import { fromPathname, setPathname, getPathname } from 'fp-ts-std/URLPath'
 *
 * const f = flow(fromPathname, setPathname('/bar'), getPathname)
 *
 * assert.strictEqual(f('/foo'), '/bar')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const setPathname: (x: string) => Endomorphism<URLPath>;
/**
 * Get the search params component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, getParams } from 'fp-ts-std/URLPath'
 *
 * const x = pipe(new URL('https://samhh.com/foo?a=b&c=d'), fromURL)
 *
 * assert.strictEqual(getParams(x).toString(), (new URLSearchParams('?a=b&c=d')).toString())
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const getParams: (x: URLPath) => URLSearchParams;
/**
 * Modify the search params component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, modifyParams, getParams } from 'fp-ts-std/URLPath'
 * import { setParam } from 'fp-ts-std/URLSearchParams'
 *
 * const x = pipe(
 *   new URL('https://samhh.com/foo?a=b&c=d'),
 *   fromURL,
 *   modifyParams(setParam('a')('e')),
 * )
 *
 * assert.deepStrictEqual(getParams(x).toString(), (new URLSearchParams('?a=e&c=d')).toString())
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const modifyParams: (f: Endomorphism<URLSearchParams>) => Endomorphism<URLPath>;
/**
 * Set the search params component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, setParams, getParams } from 'fp-ts-std/URLPath'
 *
 * const ps = new URLSearchParams('?c=d')
 *
 * const x = pipe(
 *   new URL('https://samhh.com/foo?a=b'),
 *   fromURL,
 *   setParams(ps),
 * )
 *
 * assert.deepStrictEqual(getParams(x).toString(), ps.toString())
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const setParams: (x: URLSearchParams) => Endomorphism<URLPath>;
/**
 * Get the hash component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, getHash } from 'fp-ts-std/URLPath'
 *
 * const x = pipe(new URL('https://samhh.com#anchor'), fromURL)
 *
 * assert.strictEqual(getHash(x), '#anchor')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const getHash: (x: URLPath) => string;
/**
 * Modify the hash component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, modifyHash, getHash } from 'fp-ts-std/URLPath'
 *
 * const x = pipe(
 *   new URL('https://samhh.com#anchor'),
 *   fromURL,
 *   modifyHash(s => s + '!'),
 * )
 *
 * assert.strictEqual(getHash(x), '#anchor!')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const modifyHash: (f: Endomorphism<string>) => Endomorphism<URLPath>;
/**
 * Set the hash component of a `URLPath`.
 *
 * @example
 * import { pipe } from 'fp-ts/function'
 * import { fromURL, setHash, getHash } from 'fp-ts-std/URLPath'
 *
 * const x = pipe(
 *   new URL('https://samhh.com#anchor'),
 *   fromURL,
 *   setHash('ciao'),
 * )
 *
 * assert.strictEqual(getHash(x), '#ciao')
 *
 * @category 3 Functions
 * @since 0.17.0
 */
export declare const setHash: (x: string) => Endomorphism<URLPath>;
/**
 * A holistic `Eq` instance for `URLPath`.
 *
 * @example
 * import { Eq, fromPathname } from 'fp-ts-std/URLPath'
 *
 * assert.strictEqual(Eq.equals(fromPathname("/foo"), fromPathname("/foo")), true)
 * assert.strictEqual(Eq.equals(fromPathname("/foo"), fromPathname("/bar")), false)
 *
 * @category 1 Typeclass Instances
 * @since 0.18.0
 */
export declare const Eq: Eq<URLPath>;
export {};
//# sourceMappingURL=URLPath.d.ts.map