ts-prims/lib/mjs/length.d.ts

Typescript Primitives

import type { Lte } from './util.js';
import type { Constraint } from './prim.js';
/**
 * Constrains a type to the given length `L`.
 *
 * Use this type in combination with `lengthConstraint` for runtime presence:
 *
 * ```ts
 * import { type prim, type length, Prim, lengthConstraint } from 'ts-prims'
 *
 * type text = prim<string, length<14>>
 * // type text = string & supertype<string> & length<14>
 *
 * const Text = Prim<text> (`text`, String, lengthConstraint(14))
 * ```
 *
 * This type is using a two-step approach to modeling string lengths that
 * allows for a wide range of lengths, while still being able to specify short
 * lengths with a high degree of precision. The `length` type is used when
 * coarse-grained control with a wide range of lengths is needed. For fine-
 * grained control with short strings only, use the derivative `chars` type.
 *
 * In the broad sense, the `Length` type contains 15 different lengths,
 * which are further subdivided into short, medium and long lengths.
 * The property `length` on the returned type is a union of the maximum
 * length `L` and all lengths less than `L`. The property `chars` is
 * always set to `Lte<64>` for forward compatibility with the `chars` type.
 *
 * @template L The length (`0` through `15`) to constrain the type to
 * @returns `{ length: Lte<L>, chars: Lte<64> }`
 *
 * @see {@link chars} For short lengths expressed in chars
 * @see {@link Length} The 16 fixed lengths in this framework
 * @see {@link Lte} For the `Lte` (less than or equal) type
 */
export type length<L extends Length> = {
    length: Lte<L>;
    chars: Lte<64>;
};
/**
 * The 16 fixed lengths in this framework.
 *
 * Lengths are further subdvided into 'short' lengths (`0` through `7`),
 * 'medium' lengths (`8` through `11`) and 'long' lengths (`12` through `15`)
 * for the purpose of selecting the most suitable string length for the
 * application.
 *
 * The `Chars` type allows for a more precise definition of string lengths
 * in chars, which is useful for short strings.
 *
 * Note that length `0` exists mostly for signaling purposes.
 *
 * @see {@link length} for the type constraining a string to a length
 * @see {@link lengthConstraint} for the runtime constraint
 * @see {@link chars} Constraint for short lengths expressed in chars
 * @see {@link Chars} For the short lengths expressed in chars
 * @see {@link ShortLength}
 * @see {@link MediumLength}
 * @see {@link LongLength}
 */
export type Length = ShortLength | MediumLength | LongLength;
/**
 * The short string {@link Length}s
 *
 * This type encapsulates the eight short string lengths.
 * The `chars` type further subdivides short length `0` .. `1`
 * into `65` individual char lengths (`0` .. `64`).
 *
 * @see {@link chars} Constraint for the short lengths expressed in chars
 */
export type ShortLength = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
/**
 * The medium string {@link Length}s
 *
 * This type encapsulates the four medium lengths.
 */
export type MediumLength = 8 | 9 | 10 | 11;
/**
 * The long string {@link Length}s
 *
 * This type encapsulates the four long lengths.
 */
export type LongLength = 12 | 13 | 14 | 15;
/** The lengths in chars of the short lengths */
export type ShortLengthChars = readonly [
    0,
    64,
    96,
    128,
    160,
    192,
    224,
    256
];
/** The lengths in chars of the short lengths */
export declare const shortLengthChars: ShortLengthChars;
/** The lengths in chars of the medium lengths */
export type MediumLengthChars = readonly [
    512,
    1024,
    2048,
    4096
];
/** The lengths in chars of the medium lengths */
export declare const mediumLengthChars: MediumLengthChars;
/** The lengths in chars of the long lengths */
export type LongLengthChars = readonly [
    16384,
    262144,
    16777216,
    4294967296
];
/** The lengths in chars of the high lengths */
export declare const longLengthChars: LongLengthChars;
/** The lengths in chars of all `Length`s */
export type LengthChars = readonly [
    ...ShortLengthChars,
    ...MediumLengthChars,
    ...LongLengthChars
];
/** The lengths in chars of all `Length`s */
export declare const lengthChars: LengthChars;
/** Expresses a length constraint as a function of `L` */
export type LengthConstraint = <L extends Length>(l: L) => Constraint;
/** Generates a runtime constraint for length `l` */
export declare const lengthConstraint: LengthConstraint;
//# sourceMappingURL=length.d.ts.map