@edumalin/platform 3.0.0

package/src/http/client/response/http-client-response-to-json.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { mock } from 'vitest-mock-extended';
+import { firstValueFrom } from 'rxjs';
+
+import { fetchResponseSymbol } from './fetch-response-symbol.js';
+import { type HttpClientResponse } from './http-client-response.js';
+import { httpClientResponseToJson } from './http-client-response-to-json.js';
+
+describe('HTTP client response to JSON', () => {
+  it('waits for the response body to be available as a JSON object', async () => {
+    // given: a response
+    const responseJson: TestJson = { value: 42 };
+    const response = mock<Response>();
+    const httpClientResponse = mock<HttpClientResponse>({ [fetchResponseSymbol]: response });
+    response.json.mockImplementationOnce(() => Promise.resolve(responseJson));
+
+    // when: creating a function that returns a response as JSON
+    const func = httpClientResponseToJson<TestJson>();
+    // and: calling it
+    const result$ = func(httpClientResponse);
+
+    // expect: the result to be the payload as a JSON object
+    const result = await firstValueFrom(result$);
+    expect(response.json).toHaveBeenCalledTimes(1);
+    expect(result).toBe(responseJson);
+    // and: the emitted value type to be the specified type
+    expectTypeOf(result).toEqualTypeOf<TestJson>();
+  });
+
+  it('defaults to Record<string, unknown> when no type is specified', async () => {
+    // given: a response
+    const response = mock<Response>();
+    const httpClientResponse = mock<HttpClientResponse>({ [fetchResponseSymbol]: response });
+    response.json.mockImplementationOnce(() => Promise.resolve(42));
+
+    // when: creating a function that returns a response as JSON
+    const func = httpClientResponseToJson();
+    // and: calling it
+    const result$ = func(httpClientResponse);
+
+    // expect: the type to have defaulted to Record<string, unknown>
+    const result = await firstValueFrom(result$);
+    expectTypeOf(result).toBeUnknown();
+  });
+});
+
+interface TestJson {
+  readonly value: number;
+}

package/src/http/client/response/http-client-response-to-json.ts

@@ -0,0 +1,26 @@
+import { asObservable } from '@edumalin/platform/reactive';
+import { defer, mergeMap } from 'rxjs';
+
+import { fetchResponseSymbol } from './fetch-response-symbol.js';
+import { type HttpClientResponse } from './http-client-response.js';
+
+/**
+ * Creates a function that returns an HTTP client response as an observable object
+ *
+ * @param validator Optional object validator
+ * @returns Function that returns a response as an observable object
+ * @template T Response payload interface
+ */
+export function httpClientResponseToJson<T = unknown>(
+  validator?: (json: unknown) => T | Observable<T>
+): (response: HttpClientResponse) => Observable<T> {
+  return validator !== undefined
+    ? response =>
+        defer(() => response[fetchResponseSymbol].json()).pipe(
+          mergeMap(json => {
+            const result = validator(json);
+            return asObservable(result);
+          })
+        )
+    : response => defer(() => response[fetchResponseSymbol].json());
+}

package/src/http/client/response/http-client-response-to-text.spec.ts

@@ -0,0 +1,27 @@
+import { firstValueFrom } from 'rxjs';
+import { describe, expect, it } from 'vitest';
+import { mock } from 'vitest-mock-extended';
+
+import { fetchResponseSymbol } from './fetch-response-symbol.js';
+import { type HttpClientResponse } from './http-client-response.js';
+import { httpClientResponseToText } from './http-client-response-to-text.js';
+
+describe('HTTP client response to text', () => {
+  it('waits for the response body to be available as a string', async () => {
+    // given: a response
+    const responseText = 'test';
+    const response = mock<Response>();
+    const httpClientResponse = mock<HttpClientResponse>({ [fetchResponseSymbol]: response });
+    response.text.mockImplementationOnce(() => Promise.resolve(responseText));
+
+    // when: creating a function that returns a response as text
+    const func = httpClientResponseToText();
+    // and: calling it
+    const $ = func(httpClientResponse);
+
+    // expect: the result to be the payload as a string
+    const result = await firstValueFrom($);
+    expect(response.text).toHaveBeenCalledTimes(1);
+    expect(result).toBe(responseText);
+  });
+});

package/src/http/client/response/http-client-response-to-text.ts

@@ -0,0 +1,13 @@
+import { defer } from 'rxjs';
+
+import { fetchResponseSymbol } from './fetch-response-symbol.js';
+import { type HttpClientResponse } from './http-client-response.js';
+
+/**
+ * Creates a function that returns an HTTP client response as an observable string
+ *
+ * @returns Function that returns an HTTP client response as an observable string
+ */
+export function httpClientResponseToText(): (response: HttpClientResponse) => Observable<string> {
+  return response => defer(() => response[fetchResponseSymbol].text());
+}

package/src/http/client/response/http-client-response.ts

@@ -0,0 +1,21 @@
+import { type HttpHeader, type HttpStatus } from '@edumalin/platform/http';
+
+import { type fetchResponseSymbol } from './fetch-response-symbol.js';
+
+/**
+ * HTTP client response
+ */
+export interface HttpClientResponse {
+  /**
+   * Headers
+   */
+  readonly headers: ReadonlyArray<HttpHeader>;
+  /**
+   * Status code
+   */
+  readonly status: HttpStatus;
+  /**
+   * fetch response
+   */
+  readonly [fetchResponseSymbol]: Response;
+}

package/src/http/client/response/response-to-http-client-response.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+import { responseToHttpClientResponse } from './response-to-http-client-response.js';
+
+describe('Response to HTTP client response', () => {
+  it('exists', () => {
+    expect(responseToHttpClientResponse).toBeDefined();
+  });
+
+  it.todo('works');
+});

package/src/http/client/response/response-to-http-client-response.ts

@@ -0,0 +1,19 @@
+import { fetchHeaderToHttpHeader } from '../header/fetch-header-to-http-header.js';
+import { fetchResponseSymbol } from './fetch-response-symbol.js';
+import { type HttpClientResponse } from './http-client-response.js';
+
+/**
+ * Returns an HTTP client response, given a fetch response
+ *
+ * @param response fetch response
+ * @returns HTTP client response
+ */
+export function responseToHttpClientResponse(response: Response): HttpClientResponse {
+  const { status } = response;
+  const headers = Array.from(response.headers.entries(), fetchHeaderToHttpHeader);
+  return {
+    headers,
+    status,
+    [fetchResponseSymbol]: response,
+  };
+}

package/src/http/client/response/url-to-http-client-response.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+import { urlToHttpClientResponse } from './url-to-http-client-response.js';
+
+describe('URL to HTTP client response', () => {
+  it('exists', () => {
+    expect(urlToHttpClientResponse).toBeDefined();
+  });
+
+  it.todo('works');
+});

package/src/http/client/response/url-to-http-client-response.ts

@@ -0,0 +1,18 @@
+import { type HttpClient } from '../http-client.js';
+import { type HttpClientRequest } from '../request/http-client-request.js';
+import { type HttpClientResponse } from './http-client-response.js';
+
+/**
+ * Creates a function that returns an HTTP client response, given an URL
+ *
+ * @param httpClient HTTP client
+ * @param httpClientRequest HTTP client request, without the URL
+ * @returns Function that returns an HTTP client response, given an URL
+ */
+export function urlToHttpClientResponse(
+  httpClient: HttpClient,
+  httpClientRequest?: Omit<HttpClientRequest, 'url'>
+): (url: URL) => Observable<HttpClientResponse> {
+  const defaultOptions = httpClientRequest ?? {};
+  return url => httpClient({ ...defaultOptions, url });
+}

package/src/http/client/testing/create-test-http-client.ts

@@ -0,0 +1,32 @@
+import { objectWithProperties } from '@edumalin/platform/functional';
+import { type HttpClientRequest, type HttpClientResponse } from '@edumalin/platform/http/client';
+import { of } from 'rxjs';
+
+import { type TestHttpClient } from './test-http-client.js';
+import { type TestHttpClientOptions } from './test-http-client-options.js';
+
+/**
+ * Creates a test HTTP client
+ *
+ * @param clientOptions Client options
+ * @returns Test HTTP client
+ */
+export function createTestHttpClient(clientOptions?: TestHttpClientOptions): TestHttpClient {
+  const httpClientRequests: Array<HttpClientRequest> = [];
+  const response = clientOptions?.response;
+
+  const func: (request: HttpClientRequest) => Observable<HttpClientResponse> = request => {
+    httpClientRequests.push(request);
+    // TODO: implement
+    return of(response as HttpClientResponse);
+  };
+
+  const clear = () => {
+    httpClientRequests.splice(0, httpClientRequests.length);
+  };
+
+  return objectWithProperties({
+    httpClientRequests,
+    clear,
+  })(func);
+}

package/src/http/client/testing/index.ts

@@ -0,0 +1,3 @@
+export { createTestHttpClient } from './create-test-http-client.js';
+export { type TestHttpClient } from './test-http-client.js';
+export { type TestHttpClientOptions } from './test-http-client-options.js';

package/src/http/client/testing/test-http-client-options.ts

@@ -0,0 +1,6 @@
+/**
+ * Test HTTP client options
+ */
+export interface TestHttpClientOptions {
+  readonly response?: unknown;
+}

package/src/http/client/testing/test-http-client.ts

@@ -0,0 +1,15 @@
+import { type HttpClient, type HttpClientRequest } from '@edumalin/platform/http/client';
+
+/**
+ * Test HTTP client
+ */
+export interface TestHttpClient extends HttpClient {
+  /**
+   * HTTP client requests
+   */
+  readonly httpClientRequests: ReadonlyArray<HttpClientRequest>;
+  /**
+   * Clears recorded information
+   */
+  clear(): void;
+}

package/src/http/cookie/http-cookie.ts

@@ -0,0 +1,52 @@
+import { type HttpCookieSameSiteOption } from './same-site-option/http-cookie-same-site-option.js';
+
+/**
+ * HTTP cookie
+ */
+export interface HttpCookie {
+  /**
+   * Domain the cookie is applicable to
+   */
+  readonly domain?: string;
+  /**
+   * Maximum lifetime of the cookie as a timestamp
+   */
+  readonly expires?: Temporal.ZonedDateTime;
+  /**
+   * Whether the cookie is HTTP-only, i.e. it cannot be accessed from JavaScript
+   */
+  readonly httpOnly: boolean;
+  /**
+   * Maximum age for the cookie, in seconds
+   *
+   * @note A zero or negative value expires the cookie immediately
+   * @note If both `expires` and `maxAge` are set, `maxAge` has precedence
+   */
+  readonly maxAge?: number;
+  /**
+   * Cookie name
+   */
+  readonly name: string;
+  /**
+   * Whether the cookie should be stored using partitioned storage
+   *
+   * @experimental {@link https://developer.mozilla.org/en-US/docs/Web/Privacy/Partitioned_cookies Partitioned cookies}
+   */
+  readonly partitioned?: boolean;
+  /**
+   * Path the cookie is applicable to
+   */
+  readonly path: string;
+  /**
+   * Same-site option
+   */
+  readonly sameSite?: HttpCookieSameSiteOption;
+  /**
+   * Whether the cookie is secure, i.e. it requires an HTTPS connection
+   */
+  readonly secure: boolean;
+  /**
+   * Cookie value
+   */
+  readonly value: string;
+}

package/src/http/cookie/is-session-http-cookie.ts

@@ -0,0 +1,14 @@
+import { type HttpCookie } from './http-cookie.js';
+
+/**
+ * Tests whether an HTTP cookie is a session cookie
+ *
+ * An HTTP cookie is a session cookie when it does not have any expiration information
+ *
+ * @param httpCookie HTTP cookie
+ * @returns true if the HTTP cookie is a session cookie
+ */
+export function isSessionHttpCookie(httpCookie: HttpCookie): boolean {
+  const { expires, maxAge } = httpCookie;
+  return expires === undefined && maxAge === undefined;
+}

package/src/http/cookie/same-site-option/http-cookie-same-site-option.ts

@@ -0,0 +1,6 @@
+import { type httpCookieSameSiteOptions } from './http-cookie-same-site-options.js';
+
+/**
+ * HTTP cookie same-site option
+ */
+export type HttpCookieSameSiteOption = (typeof httpCookieSameSiteOptions)[number];

package/src/http/cookie/same-site-option/http-cookie-same-site-options.ts

@@ -0,0 +1,4 @@
+/**
+ * HTTP cookie same-site options
+ */
+export const httpCookieSameSiteOptions = ['Lax', 'None', 'Strict'] as const;

package/src/http/cookie/same-site-option/is-http-cookie-same-site-option.ts

@@ -0,0 +1,17 @@
+import { type HttpCookieSameSiteOption } from './http-cookie-same-site-option.js';
+import { httpCookieSameSiteOptions } from './http-cookie-same-site-options.js';
+
+/**
+ * Tests whether a string is an HTTP cookie same site option
+ *
+ * @param value Value
+ * @returns true if the string is an HTTP cookie same site option
+ */
+export function isHttpCookieSameSiteOption(value: string): value is HttpCookieSameSiteOption {
+  return set.has(value);
+}
+
+/**
+ * Set
+ */
+const set: ReadonlySet<string> = new Set(httpCookieSameSiteOptions);

package/src/http/cookie/same-site-option/validate-http-cookie-same-site-option.ts

@@ -0,0 +1,14 @@
+import { httpError } from '../../http.error.js';
+import { type HttpCookieSameSiteOption } from './http-cookie-same-site-option.js';
+import { isHttpCookieSameSiteOption } from './is-http-cookie-same-site-option.js';
+
+/**
+ * Validates that a string is an HTTP cookie same site option
+ *
+ * @param value Value
+ */
+export function validateHttpCookieSameSiteOption(value: string): asserts value is HttpCookieSameSiteOption {
+  if (!isHttpCookieSameSiteOption(value)) {
+    throw httpError.invalidCookieSameSiteOption({ value });
+  }
+}

package/src/http/error/invalid-cookie-header-value-error-properties.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid cookie header value error properties
+ */
+export interface InvalidCookieHeaderValueErrorProperties {
+  /**
+   * Value
+   */
+  readonly value: string;
+}

package/src/http/error/invalid-cookie-same-site-option-error-properties.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid cookie same-site option error properties
+ */
+export interface InvalidCookieSameSiteOptionErrorProperties {
+  /**
+   * Value
+   */
+  readonly value: string;
+}

package/src/http/error/invalid-http-header-name-error-properties.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid HTTP header name error properties
+ */
+export interface InvalidHttpHeaderNameErrorProperties {
+  /**
+   * Value
+   */
+  readonly value: string;
+}

package/src/http/error/invalid-http-method-error-properties.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid HTTP method error properties
+ */
+export interface InvalidHttpMethodErrorProperties {
+  /**
+   * Value
+   */
+  readonly value: string;
+}

package/src/http/error/invalid-http-status-error-properties.ts

@@ -0,0 +1,9 @@
+/**
+ * Invalid HTTP status error properties
+ */
+export interface InvalidHttpStatusErrorProperties {
+  /**
+   * Value
+   */
+  readonly value: number;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Parses an authorization header value
+ *
+ * @param authorizationHeaderValue Authorization header value
+ * @returns Authorization information
+ */
+export function parseAuthorizationHeaderValue(
+  authorizationHeaderValue: string
+): readonly [authScheme: string, value: string] | undefined {
+  type AuthorizationHeaderMatch = readonly [matches: string, authScheme: string, value: string];
+  const matches = authorizationRegExp.exec(authorizationHeaderValue) as AuthorizationHeaderMatch | null;
+  if (!matches) {
+    return undefined;
+  }
+
+  const [, authScheme, value] = matches;
+
+  return [authScheme, value];
+}
+
+/**
+ * Authorization regular expression
+ */
+const authorizationRegExp = /^([^\s]+) (.+)$/;

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

@@ -0,0 +1,12 @@
+import { type HttpHeader } from './http-header.js';
+import { type HttpHeaderName } from './name/http-header-name.js';
+
+/**
+ * Creates a function that returns true when a HTTP header matches a given HTTP header name
+ *
+ * @param headerName HTTP header name
+ * @returns Function that returns true when a HTTP header matches the given HTTP header name
+ */
+export function byHttpHeaderName(headerName: HttpHeaderName | (string & {})): (httpHeader: HttpHeader) => boolean {
+  return ([name]) => name.toLocaleLowerCase() === headerName.toLocaleLowerCase();
+}

package/src/http/header/cookie/create-set-cookie-http-header.ts

@@ -0,0 +1,34 @@
+import { type HttpCookie } from '../../cookie/http-cookie.js';
+import { type HttpHeader } from '../http-header.js';
+
+/**
+ * Returns a Set-Cookie HTTP header
+ *
+ * @param httpCookie HTTP cookie
+ * @returns Set-Cookie HTTP header
+ */
+export function createSetCookieHttpHeader(
+  httpCookie: Pick<HttpCookie, 'name' | 'value'> & Partial<Omit<HttpCookie, 'name' | 'value'>>
+): HttpHeader {
+  const nameValuePair = httpCookieToHttpHeaderNameValuePair(httpCookie);
+  const { domain, expires, httpOnly, maxAge, partitioned, path, sameSite, secure } = httpCookie;
+  const properties = [
+    nameValuePair,
+    ...(domain !== undefined ? [`Domain=${domain}`] : []),
+    // TODO: convert expires to an HTTP date
+    ...(expires !== undefined ? [`Expires=${expires}`] : []),
+    ...(httpOnly ? [`HttpOnly`] : []),
+    ...(maxAge !== undefined ? [`Max-Age=${maxAge}`] : []),
+    ...(partitioned ? ['Partitioned'] : []),
+    ...(path !== undefined ? [`Path=${path}`] : []),
+    ...(sameSite !== undefined ? [`SameSite=${sameSite}`] : []),
+    ...(secure ? [`Secure`] : []),
+  ];
+  const value = properties.join('; ');
+  return ['set-cookie', value];
+}
+
+function httpCookieToHttpHeaderNameValuePair(httpCookie: Pick<HttpCookie, 'name' | 'value'>): string {
+  const { name, value } = httpCookie;
+  return `${name}=${value}`;
+}

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

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseCookieHeaderValue } from './parse-cookie-header-value';
+
+describe('Parse cookie header value', () => {
+  it('can parse a header with a single cookie', () => {
+    // given: a single cookie
+    const cookieName = 'test';
+    const cookieValue = 'abc123';
+    // and: a header value
+    const headerValue = `${cookieName}=${cookieValue}`;
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: a single cookie was parsed
+    expect(cookies).toEqual({
+      [cookieName]: cookieValue,
+    });
+  });
+
+  it('can parse a header with multiple cookies', () => {
+    // given: multiple cookies
+    const cookie1Name = 'test';
+    const cookie1Value = 'abc123';
+    const cookie2Name = 'theme';
+    const cookie2Value = 'dark';
+    const cookie3Name = 'language';
+    const cookie3Value = 'en';
+    // and: a header value
+    const headerValue = [
+      `${cookie1Name}=${cookie1Value}`,
+      `${cookie2Name}=${cookie2Value}`,
+      `${cookie3Name}=${cookie3Value}`,
+    ].join('; ');
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: all cookies were parsed
+    expect(cookies).toEqual({
+      [cookie1Name]: cookie1Value,
+      [cookie2Name]: cookie2Value,
+      [cookie3Name]: cookie3Value,
+    });
+  });
+
+  it('can trim whitespace around cookie names and values', () => {
+    // given: a single cookie
+    const cookieName = 'test';
+    const cookieValue = 'abc123';
+    // and: a header value with surrounding white spaces
+    const headerValue = `  ${cookieName} =   ${cookieValue} `;
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: a single cookie was parsed
+    expect(cookies).toEqual({
+      [cookieName]: cookieValue,
+    });
+  });
+
+  it('can preserve equals signs inside cookie values', () => {
+    // given: a single cookie with an equals sign in its value
+    const cookieName = 'test';
+    const cookieValue = 'key=value';
+    // and: a header value
+    const headerValue = `${cookieName}=${cookieValue}`;
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: a single cookie was parsed
+    expect(cookies).toEqual({
+      [cookieName]: cookieValue,
+    });
+  });
+
+  it('can handle an empty header', () => {
+    // given: an empty header value
+    const headerValue = '';
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: an empty record is returned
+    expect(cookies).toEqual({});
+  });
+
+  it('can handle cookies with empty values', () => {
+    // given: a list of cookies where some don't have a value
+    const cookie1Name = 'test';
+    const cookie1Value = '';
+    const cookie2Name = 'theme';
+    const cookie2Value = 'dark';
+    // and: a header value
+    const headerValue = [`${cookie1Name}=${cookie1Value}`, `${cookie2Name}=${cookie2Value}`].join('; ');
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: all cookies were parsed
+    expect(cookies).toEqual({
+      [cookie1Name]: cookie1Value,
+      [cookie2Name]: cookie2Value,
+    });
+  });
+
+  it('can decode URL-encoded cookie values', () => {
+    // given: a single cookie with a URL encoded value
+    const cookieName = 'test';
+    const cookieValue = 'John%20Doe';
+    // and: a header value
+    const headerValue = `${cookieName}=${cookieValue}`;
+
+    // when: parsing the cookie header
+    const cookies = parseCookieHeaderValue(headerValue);
+
+    // then: a single cookie was parsed
+    expect(cookies).toEqual({
+      [cookieName]: 'John Doe',
+    });
+  });
+});