@edumalin/platform 3.0.0

package/src/http/header/cookie/parse-cookie-header-value.ts

@@ -0,0 +1,53 @@
+import { entriesToObject, isDefined } from '@edumalin/platform/functional';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { httpError } from '../../http.error.js';
+
+/**
+ * Parses a cookie header value
+ *
+ * @param cookieHeaderValue Cookie header value
+ * @returns Name and value
+ */
+export function parseCookieHeaderValue(cookieHeaderValue: string): ReadonlyRecord<string, string> {
+  const entries = cookieHeaderValue.split(';').map(segmentToCookieNameValuePair).filter(isDefined);
+  return entriesToObject(entries);
+}
+
+/**
+ * Returns a cookie name-value pair, given a segment
+ *
+ * @param segment Segment
+ * @returns Cookie name-value pair
+ */
+function segmentToCookieNameValuePair(segment: string): readonly [cookieName: string, cookieValue: string] | undefined {
+  const separator = segment.indexOf('=');
+  if (separator === -1) {
+    return undefined;
+  }
+
+  const namePart = segment.substring(0, separator);
+  const name = decodeString(namePart).trim();
+  if (!name) {
+    return undefined;
+  }
+
+  const valuePart = segment.substring(separator + 1);
+  const value = decodeString(valuePart).trim();
+
+  return [name, value];
+}
+
+/**
+ * Returns a decoded string, or the original string if decoding failed
+ *
+ * @param value Value
+ * @returns Decoded value
+ */
+function decodeString(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw httpError.invalidCookieHeaderValue({ value });
+  }
+}

package/src/http/header/http-header.ts

@@ -0,0 +1,6 @@
+import { type HttpHeaderName } from './name/http-header-name.js';
+
+/**
+ * HTTP header
+ */
+export type HttpHeader = readonly [headerName: HttpHeaderName | (string & {}), headerValue: string];

package/src/http/header/name/as-http-header-name.ts

@@ -0,0 +1,13 @@
+import { type HttpHeaderName } from './http-header-name.js';
+import { validateHttpHeaderName } from './validate-http-header-name.js';
+
+/**
+ * Safely casts a string to an HTTP header name
+ *
+ * @param string String
+ * @returns HTTP header name
+ */
+export function asHttpHeaderName(string: string): HttpHeaderName {
+  validateHttpHeaderName(string);
+  return string;
+}

package/src/http/header/name/http-header-name.ts

@@ -0,0 +1,6 @@
+import { type httpHeaderNames } from './http-header-names.js';
+
+/**
+ * HTTP header name
+ */
+export type HttpHeaderName = (typeof httpHeaderNames)[number];

package/src/http/header/name/http-header-names.ts

@@ -0,0 +1,118 @@
+/**
+ * HTTP header names
+ */
+export const httpHeaderNames = [
+  'accept',
+  'accept-ch',
+  'accept-charset',
+  'accept-encoding',
+  'accept-language',
+  'accept-patch',
+  'accept-post',
+  'accept-ranges',
+  'access-control-allow-credentials',
+  'access-control-allow-headers',
+  'access-control-allow-methods',
+  'access-control-allow-origin',
+  'access-control-expose-headers',
+  'access-control-max-age',
+  'access-control-request-headers',
+  'access-control-request-method',
+  'age',
+  'allow',
+  'alt-svc',
+  'alt-used',
+  'authorization',
+  'cache-control',
+  'clear-site-data',
+  'connection',
+  'content-disposition',
+  'content-encoding',
+  'content-language',
+  'content-length',
+  'content-location',
+  'content-security-policy',
+  'content-security-policy-report-only',
+  'content-type',
+  'cookie',
+  'critical-ch',
+  'cross-origin-embedder-policy',
+  'cross-origin-opener-policy',
+  'cross-origin-resource-policy',
+  'date',
+  'device-memory',
+  'downlink',
+  'early-data',
+  'ect',
+  'etag',
+  'expect',
+  'expect-ct',
+  'expires',
+  'forwarded',
+  'from',
+  'host',
+  'if-match',
+  'if-modified-since',
+  'if-none-match',
+  'if-range',
+  'if-unmodified-since',
+  'keep-alive',
+  'last-modified',
+  'link',
+  'location',
+  'max-forwards',
+  'nel',
+  'origin',
+  'origin-agent-cluster',
+  'permissions-policy',
+  'pragma',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'range',
+  'referer',
+  'referrer-policy',
+  'retry-after',
+  'rtt',
+  'save-data',
+  'sec-ch-prefers-color-scheme',
+  'sec-ch-prefers-reduced-motion',
+  'sec-ch-prefers-reduced-transparency',
+  'sec-ch-ua',
+  'sec-ch-ua-arch',
+  'sec-ch-ua-bitness',
+  'sec-ch-ua-full-version-list',
+  'sec-ch-ua-mobile',
+  'sec-ch-ua-model',
+  'sec-ch-ua-platform',
+  'sec-ch-ua-platform-version',
+  'sec-fetch-dest',
+  'sec-fetch-mode',
+  'sec-fetch-site',
+  'sec-fetch-user',
+  'sec-gpc',
+  'sec-purpose',
+  'sec-websocket-accept',
+  'server',
+  'server-timing',
+  'service-worker-navigation-preload',
+  'set-cookie',
+  'sourcemap',
+  'strict-transport-security',
+  'supports-loading-mode',
+  'te',
+  'timing-allow-origin',
+  'trailer',
+  'upgrade',
+  'upgrade-insecure-requests',
+  'user-agent',
+  'vary',
+  'via',
+  'www-authenticate',
+  'x-content-type-options',
+  'x-dns-prefetch-control',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-frame-options',
+  'x-xss-protection',
+] as const;

package/src/http/header/name/is-http-header-name.ts

@@ -0,0 +1,11 @@
+import { type HttpHeaderName } from './http-header-name.js';
+
+/**
+ * Tests whether an HTTP header name is a recognized HTTP header name
+ *
+ * @param httpHeaderName HTTP header name
+ * @returns true if the HTTP header name is valid
+ */
+export function isHttpHeaderName(httpHeaderName: string): httpHeaderName is HttpHeaderName {
+  return httpHeaderName.length > 0;
+}

package/src/http/header/name/validate-http-header-name.ts

@@ -0,0 +1,14 @@
+import { httpError } from '../../http.error.js';
+import { type HttpHeaderName } from './http-header-name.js';
+import { isHttpHeaderName } from './is-http-header-name.js';
+
+/**
+ * Validates an HTTP header name is a recognized HTTP header name
+ *
+ * @param httpHeaderName HTTP header name
+ */
+export function validateHttpHeaderName(httpHeaderName: string): asserts httpHeaderName is HttpHeaderName {
+  if (!isHttpHeaderName(httpHeaderName)) {
+    throw httpError.invalidHttpHeaderName({ value: httpHeaderName });
+  }
+}

package/src/http/http.error.ts

@@ -0,0 +1,34 @@
+import { platformDomain } from '@edumalin/platform';
+import { createErrorType, errorProperties } from '@edumalin/platform/error';
+
+import { type InvalidCookieHeaderValueErrorProperties } from './error/invalid-cookie-header-value-error-properties.js';
+import { type InvalidCookieSameSiteOptionErrorProperties } from './error/invalid-cookie-same-site-option-error-properties.js';
+import { type InvalidHttpHeaderNameErrorProperties } from './error/invalid-http-header-name-error-properties.js';
+import { type InvalidHttpMethodErrorProperties } from './error/invalid-http-method-error-properties.js';
+import { type InvalidHttpStatusErrorProperties } from './error/invalid-http-status-error-properties.js';
+
+/**
+ * HTTP error
+ */
+export const httpError = createErrorType(platformDomain, {
+  /**
+   * Invalid cookie header value
+   */
+  invalidCookieHeaderValue: errorProperties<InvalidCookieHeaderValueErrorProperties>(),
+  /**
+   * Invalid cookie same-site option
+   */
+  invalidCookieSameSiteOption: errorProperties<InvalidCookieSameSiteOptionErrorProperties>(),
+  /**
+   * Invalid HTTP header name
+   */
+  invalidHttpHeaderName: errorProperties<InvalidHttpHeaderNameErrorProperties>(),
+  /**
+   * Invalid HTTP method
+   */
+  invalidHttpMethod: errorProperties<InvalidHttpMethodErrorProperties>(),
+  /**
+   * Invalid HTTP status
+   */
+  invalidHttpStatus: errorProperties<InvalidHttpStatusErrorProperties>(),
+});

package/src/http/index.ts

@@ -0,0 +1,31 @@
+export { asHttpHeaderName } from './header/name/as-http-header-name.js';
+export { asHttpMethod } from './method/as-http-method.js';
+export { byHttpHeaderName } from './header/by-http-header-name.js';
+export { createSetCookieHttpHeader } from './header/cookie/create-set-cookie-http-header.js';
+export { type HttpCookie } from './cookie/http-cookie.js';
+export { type HttpCookieSameSiteOption } from './cookie/same-site-option/http-cookie-same-site-option.js';
+export { httpCookieSameSiteOptions } from './cookie/same-site-option/http-cookie-same-site-options.js';
+export { httpError } from './http.error.js';
+export { type HttpHeader } from './header/http-header.js';
+export { type HttpHeaderName } from './header/name/http-header-name.js';
+export { type httpHeaderNames } from './header/name/http-header-names.js';
+export { type HttpMethod } from './method/http-method.js';
+export { httpMethods } from './method/http-methods.js';
+export { type HttpStatus } from './status/http-status.js';
+export { httpStatuses } from './status/http-statuses.js';
+export { type InvalidCookieHeaderValueErrorProperties } from './error/invalid-cookie-header-value-error-properties.js';
+export { type InvalidCookieSameSiteOptionErrorProperties } from './error/invalid-cookie-same-site-option-error-properties.js';
+export { type InvalidHttpHeaderNameErrorProperties } from './error/invalid-http-header-name-error-properties.js';
+export { type InvalidHttpMethodErrorProperties } from './error/invalid-http-method-error-properties.js';
+export { type InvalidHttpStatusErrorProperties } from './error/invalid-http-status-error-properties.js';
+export { isHttpCookieSameSiteOption } from './cookie/same-site-option/is-http-cookie-same-site-option.js';
+export { isHttpHeaderName } from './header/name/is-http-header-name.js';
+export { isHttpMethod } from './method/is-http-method.js';
+export { isHttpStatus } from './status/is-http-status.js';
+export { isSessionHttpCookie } from './cookie/is-session-http-cookie.js';
+export { parseAuthorizationHeaderValue } from './header/authorization/parse-authorization-header-value.js';
+export { parseCookieHeaderValue } from './header/cookie/parse-cookie-header-value.js';
+export { validateHttpCookieSameSiteOption } from './cookie/same-site-option/validate-http-cookie-same-site-option.js';
+export { validateHttpHeaderName } from './header/name/validate-http-header-name.js';
+export { validateHttpMethod } from './method/validate-http-method.js';
+export { validateHttpStatus } from './status/validate-http-status.js';

package/src/http/method/as-http-method.ts

@@ -0,0 +1,13 @@
+import { type HttpMethod } from './http-method.js';
+import { validateHttpMethod } from './validate-http-method.js';
+
+/**
+ * Safely casts a string to an HTTP method
+ *
+ * @param string String
+ * @returns HTTP method
+ */
+export function asHttpMethod(string: string): HttpMethod {
+  validateHttpMethod(string);
+  return string;
+}

package/src/http/method/http-method.ts

@@ -0,0 +1,6 @@
+import { type httpMethods } from './http-methods.js';
+
+/**
+ * HTTP method
+ */
+export type HttpMethod = (typeof httpMethods)[number];

package/src/http/method/http-methods.ts

@@ -0,0 +1,4 @@
+/**
+ * HTTP methods
+ */
+export const httpMethods = ['CONNECT', 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE'] as const;

package/src/http/method/is-http-method.ts

@@ -0,0 +1,14 @@
+import { httpMethods } from './http-methods.js';
+import { type HttpMethod } from './http-method.js';
+
+/**
+ * Tests whether a string is a known HTTP method
+ *
+ * @param httpMethod HTTP method string
+ * @returns true if the string is a known HTTP method
+ */
+export function isHttpMethod(httpMethod: string): httpMethod is HttpMethod {
+  return set.has(httpMethod);
+}
+
+const set: ReadonlySet<string> = new Set(httpMethods);

package/src/http/method/validate-http-method.ts

@@ -0,0 +1,14 @@
+import { httpError } from '../http.error.js';
+import { type HttpMethod } from './http-method.js';
+import { isHttpMethod } from './is-http-method.js';
+
+/**
+ * Validates that a string is a known HTTP method
+ *
+ * @param httpMethod HTTP method string
+ */
+export function validateHttpMethod(httpMethod: string): asserts httpMethod is HttpMethod {
+  if (!isHttpMethod(httpMethod)) {
+    throw httpError.invalidHttpMethod({ value: httpMethod });
+  }
+}

package/src/http/status/http-status.ts

@@ -0,0 +1,6 @@
+import { type httpStatuses } from './http-statuses.js';
+
+/**
+ * HTTP status
+ */
+export type HttpStatus = (typeof httpStatuses)[keyof typeof httpStatuses] | (number & {});

package/src/http/status/http-statuses.ts

@@ -0,0 +1,68 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+/**
+ * HTTP statuses
+ */
+export const httpStatuses = {
+  Continue: 100,
+  SwitchingProtocols: 101,
+  Processing: 102,
+  EarlyHints: 103,
+  Ok: 200,
+  Created: 201,
+  Accepted: 202,
+  NonAuthoritativeInformation: 203,
+  NoContent: 204,
+  ResetContent: 205,
+  PartialContent: 206,
+  MultiStatus: 207,
+  AlreadyReported: 208,
+  ImUsed: 226,
+  MultipleChoices: 300,
+  MovedPermanently: 301,
+  Found: 302,
+  SeeOther: 303,
+  NotModified: 304,
+  TemporaryRedirect: 307,
+  PermanentRedirect: 308,
+  BadRequest: 400,
+  Unauthorized: 401,
+  PaymentRequired: 402,
+  Forbidden: 403,
+  NotFound: 404,
+  MethodNotAllowed: 405,
+  NotAcceptable: 406,
+  ProxyAuthenticationRequired: 407,
+  RequestTimeout: 408,
+  Conflict: 409,
+  Gone: 410,
+  LengthRequired: 411,
+  PreconditionFailed: 412,
+  ContentTooLarge: 413,
+  UriTooLong: 414,
+  UnsupportedMediaType: 415,
+  RangeNotSatisfiable: 416,
+  ExpectationFAiled: 417,
+  ImATeapot: 418,
+  MisdirectedRequest: 421,
+  UnprocessableContent: 422,
+  Locked: 423,
+  FailedDependency: 424,
+  TooEarly: 425,
+  UpgradeRequired: 426,
+  PreconditionRequired: 428,
+  TooManyRequests: 429,
+  RequestHeaderFieldsTooLarge: 431,
+  UnavailableForLegalReasons: 451,
+  InternalServerError: 500,
+  NotImplemented: 501,
+  BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
+  HttpVersionNotSupported: 505,
+  VariantAlsoNegotiates: 506,
+  InsufficientStorage: 507,
+  LoopDetected: 508,
+  NotExtended: 510,
+  NetworkAuthenticationRequired: 511,
+} as const satisfies ReadonlyRecord<string, number>;

package/src/http/status/is-http-status.spec.ts

@@ -0,0 +1,20 @@
+import { objectToEntries } from '@edumalin/platform/functional';
+import { describe, expect, it } from 'vitest';
+
+import { httpStatuses } from './http-statuses.js';
+import { isHttpStatus } from './is-http-status.js';
+
+describe('Is HTTP status', () => {
+  it.each(objectToEntries(httpStatuses).map(([name, value]) => [value, name] as const))(
+    'returns true given HTTP status %d (%s)',
+    value => {
+      // given: an HTTP status value
+
+      // when: testing whether the number is an HTTP status code
+      const result = isHttpStatus(value);
+
+      // then: true is returned
+      expect(result).toBe(true);
+    }
+  );
+});

package/src/http/status/is-http-status.ts

@@ -0,0 +1,16 @@
+import { objectToValues } from '@edumalin/platform/functional';
+
+import { type HttpStatus } from './http-status.js';
+import { httpStatuses } from './http-statuses.js';
+
+/**
+ * Tests whether a number is a known HTTP status
+ *
+ * @param httpStatus HTTP status number
+ * @returns true if the string is a known HTTP status
+ */
+export function isHttpStatus(httpStatus: number): httpStatus is HttpStatus {
+  return set.has(httpStatus);
+}
+
+const set: ReadonlySet<number> = new Set(objectToValues(httpStatuses));

package/src/http/status/validate-http-status.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { validateHttpStatus } from './validate-http-status';
+
+describe('Validate HTTP status', () => {
+  it('does not throw for a valid status code', () => {
+    // given: a valid status code
+    const statusCode = 200;
+
+    // expect: validating the status code not to throw
+    expect(() => validateHttpStatus(statusCode)).not.toThrow();
+  });
+
+  it('throws for an invalid status code', () => {
+    // given: an invalid status code
+    const statusCode = 999;
+
+    // expect: validating the status code to throw
+    expect(() => validateHttpStatus(statusCode)).toThrow(`invalid HTTP status ${statusCode}"`);
+  });
+});

package/src/http/status/validate-http-status.ts

@@ -0,0 +1,14 @@
+import { httpError } from '../http.error.js';
+import { type HttpStatus } from './http-status.js';
+import { isHttpStatus } from './is-http-status.js';
+
+/**
+ * Validates that a string is a known HTTP status
+ *
+ * @param httpStatus HTTP status string
+ */
+export function validateHttpStatus(httpStatus: number): asserts httpStatus is HttpStatus {
+  if (!isHttpStatus(httpStatus)) {
+    throw httpError.invalidHttpStatus({ value: httpStatus });
+  }
+}

package/src/i18n/error/invalid-i18n-string-error-properties.ts

@@ -0,0 +1,6 @@
+/**
+ * Invalid i18n string error properties
+ */
+export interface InvalidI18nStringErrorProperties {
+  readonly value: unknown;
+}

package/src/i18n/i18n.error.ts

@@ -0,0 +1,14 @@
+import { platformDomain } from '@edumalin/platform';
+import { createErrorType, errorProperties } from '@edumalin/platform/error';
+
+import { type InvalidI18nStringErrorProperties } from './error/invalid-i18n-string-error-properties.js';
+
+/**
+ * i18n error
+ */
+export const i18nError = createErrorType(platformDomain, {
+  /**
+   * Invalid i18n string
+   */
+  invalidI18nString: errorProperties<InvalidI18nStringErrorProperties>(),
+});

package/src/i18n/index.ts

@@ -0,0 +1,12 @@
+export { asI18nString } from './string/as-i18n-string.js';
+export { compareI18nString } from './string/compare-i18n-strings.js';
+export { type CompareI18nStringsOptions } from './string/compare-i18n-strings-options.js';
+export { i18nError } from './i18n.error.js';
+export { type I18nString } from './string/i18n-string.js';
+export { i18nStringIncludes } from './string/i18n-string-includes.js';
+export { type I18nStringIncludesOptions } from './string/i18n-string-includes-options.js';
+export { type InvalidI18nStringErrorProperties } from './error/invalid-i18n-string-error-properties.js';
+export { isI18nString } from './string/is-i18n-string.js';
+export { isSameI18nString } from './string/is-same-i18n-string.js';
+export { mergeI18nStrings } from './string/merge-i18n-strings.js';
+export { validateI18nString } from './string/validate-i18n-string.js';

package/src/i18n/string/as-i18n-string.ts

@@ -0,0 +1,13 @@
+import { type I18nString } from './i18n-string.js';
+import { validateI18nString } from './validate-i18n-string.js';
+
+/**
+ * Safely casts a value to an i18n string
+ *
+ * @param value Value
+ * @returns i18n string
+ */
+export function asI18nString(value: unknown): I18nString {
+  validateI18nString(value);
+  return value;
+}

package/src/i18n/string/compare-i18n-strings-options.ts

@@ -0,0 +1,15 @@
+import { type LocaleCode } from '@edumalin/platform/locale';
+
+/**
+ * Compare i18n string options
+ */
+export interface CompareI18nStringsOptions {
+  /**
+   * Locale code
+   */
+  readonly localeCode: LocaleCode;
+  /**
+   * Usage
+   */
+  readonly usage?: 'search' | 'sort';
+}

package/src/i18n/string/compare-i18n-strings.ts

@@ -0,0 +1,19 @@
+import { type CompareI18nStringsOptions } from './compare-i18n-strings-options';
+import { type I18nString } from './i18n-string';
+
+/**
+ * Creates a function that compares i18n strings using a given locale code
+ *
+ * @param options I18n string comparison options
+ * @returns Function that compares i18n strings using a given locale code
+ */
+export function compareI18nString(options: CompareI18nStringsOptions): (lhs: I18nString, rhs: I18nString) => number {
+  const { localeCode, usage } = options;
+
+  return (lhs, rhs) => {
+    const lhsString = lhs[localeCode] ?? '';
+    const rhsString = rhs[localeCode] ?? '';
+
+    return lhsString.localeCompare(rhsString, localeCode, usage ? { usage } : undefined);
+  };
+}

package/src/i18n/string/i18n-string-includes-options.ts

@@ -0,0 +1,15 @@
+import { type LocaleCode } from '@edumalin/platform/locale';
+
+/**
+ * i18n string includes options
+ */
+export interface I18nStringIncludesOptions {
+  /**
+   * Ignore case when comparing
+   */
+  readonly ignoreCase?: boolean;
+  /**
+   * Locale code
+   */
+  readonly localeCode?: LocaleCode;
+}

package/src/i18n/string/i18n-string-includes.ts

@@ -0,0 +1,44 @@
+import { isDefined, objectToValues } from '@edumalin/platform/functional';
+
+import { type I18nString } from './i18n-string';
+import { type I18nStringIncludesOptions } from './i18n-string-includes-options';
+
+/**
+ * Creates a function that tests whether an i18n string includes a substring
+ *
+ * @param substring Substring
+ * @param localeCode Locale code
+ * @returns Function that tests whether an i18n string includes a substring
+ */
+export function i18nStringIncludes(
+  substring: string,
+  options?: I18nStringIncludesOptions
+): (i18nString: I18nString) => boolean {
+  const localeCode = options?.localeCode;
+  const ignoreCase = options?.ignoreCase ?? false;
+  const stringMatches = i18nStringValueIncluding(substring, ignoreCase);
+
+  return i18nString => {
+    if (localeCode) {
+      const string = i18nString[localeCode];
+      return string !== undefined ? stringMatches(string) : false;
+    }
+
+    return objectToValues(i18nString).filter(isDefined).some(stringMatches);
+  };
+}
+
+/**
+ * Creates a function that tests whether an i18n string value includes a substring
+ *
+ * @param substring Substring
+ * @param ignoreCase Whether to ignore case
+ * @returns Function that tests whether an i18n string value includes a substring
+ */
+function i18nStringValueIncluding(substring: string, ignoreCase: boolean): (targeString: string) => boolean {
+  const expectedSubstring = ignoreCase ? substring.toLocaleLowerCase() : substring;
+  return targetString => {
+    const string = ignoreCase ? targetString.toLocaleLowerCase() : targetString;
+    return string.includes(expectedSubstring);
+  };
+}

package/src/i18n/string/i18n-string.ts

@@ -0,0 +1,7 @@
+import { type LocaleCode } from '@edumalin/platform/locale';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+/**
+ * i18n string
+ */
+export type I18nString = Partial<ReadonlyRecord<LocaleCode, string>>;