@edumalin/platform 3.0.0

package/src/typescript/deep-partial.ts

@@ -0,0 +1,17 @@
+import { type IsBrandedType } from './is-branded-type.js';
+
+/**
+ * Deep partial
+ *
+ * Works like `Partial<T>` but recursively, making all properties optional including nested properties
+ *
+ * @template T Type
+ */
+export type DeepPartial<T> =
+  IsBrandedType<T> extends true
+    ? T
+    : T extends ReadonlyArray<unknown>
+      ? ReadonlyArray<DeepPartial<T[number]>>
+      : {
+          [PropertyKey in keyof T]?: T[PropertyKey] extends object ? DeepPartial<T[PropertyKey]> : T[PropertyKey];
+        };

package/src/typescript/expand.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type Expand } from './expand.js';
+
+describe('Expand', () => {
+  it('expands a type', () => {
+    // given: a type with an intersection
+    type TypeWithIntersection = { readonly x: string } & { readonly y: number };
+
+    // when: expanding the type
+    type ExpandedType = Expand<TypeWithIntersection>;
+
+    // expect: the type to have been expanded, removing the intersection
+    expectTypeOf<ExpandedType>().toEqualTypeOf<{ readonly x: string; readonly y: number }>();
+  });
+});

package/src/typescript/expand.ts

@@ -0,0 +1,10 @@
+/**
+ * Expands a type
+ *
+ * ```ts
+ * type Expanded = Expand<{ a: number } & { b: string }>;
+ * // ^ Expanded = { a: number; b: string }
+ * ```
+ * @template T Type
+ */
+export type Expand<T> = T extends T ? { [K in keyof T]: T[K] } : never;

package/src/typescript/function/unary-function.ts

@@ -0,0 +1,9 @@
+/**
+ * Unary function
+ *
+ * @template ParameterType Parameter type
+ * @template ReturnType Return type
+ */
+export interface UnaryFunction<ParameterType, ReturnType> {
+  (parameter: ParameterType): ReturnType;
+}

package/src/typescript/generic-function.ts

@@ -0,0 +1,4 @@
+/**
+ * Generic function
+ */
+export type GenericFunction = (...args: ReadonlyArray<any>) => any;

package/src/typescript/index.ts

@@ -0,0 +1,17 @@
+export { type DeepPartial } from './deep-partial.js';
+export { type Expand } from './expand.js';
+export { type GenericFunction } from './generic-function.js';
+export { type IsBrandedType } from './is-branded-type.js';
+export { type KeysOfValueType } from './keys-of-value-type.js';
+export { type OmitCallSignature } from './omit-call-signature.js';
+export { type OmitIndexedAccess } from './omit-indexed-access.js';
+export { type PickCallSignature } from './pick-call-signature.js';
+export { type PropertiesToUnion } from './properties-to-union.js';
+export { type ReadonlyRecord } from './readonly-record.js';
+export { type TypeCreator } from './schema/type-creator.js';
+export { type TypeSchema } from './schema/type-schema.js';
+export { typeSchema } from './schema/type-schema.js';
+export { type TypeSchemaType } from './schema/type-schema-type.js';
+export { type TypeSchemaTypeName } from './schema/type-schema-type-name.js';
+export { type UnaryFunction } from './function/unary-function.js';
+export { type UnionToIntersection } from './union-to-intersection.js';

package/src/typescript/is-branded-type.ts

@@ -0,0 +1,12 @@
+import { type ReadonlyRecord } from './readonly-record.js';
+
+/**
+ * Tests whether a type is branded
+ *
+ * @template T Type
+ */
+export type IsBrandedType<T> = T extends string
+  ? Exclude<T, string> extends ReadonlyRecord<`__tag_${string}`, any>
+    ? true
+    : false
+  : false;

package/src/typescript/keys-of-value-type.ts

@@ -0,0 +1,4 @@
+/**
+ * Filters keys with values of a specific type
+ */
+export type KeysOfValueType<T, V> = keyof { [P in keyof T as T[P] extends V ? P : never]: P };

package/src/typescript/omit-call-signature.ts

@@ -0,0 +1,10 @@
+import { type GenericFunction } from './generic-function.js';
+
+/**
+ * Omits a call signature from a type
+ *
+ * @template T Type
+ */
+export type OmitCallSignature<T> = {
+  readonly [K in keyof T]: K extends GenericFunction ? never : T[K];
+};

package/src/typescript/omit-indexed-access.ts

@@ -0,0 +1,8 @@
+/**
+ * Omits an indexed access from a type
+ *
+ * @template T Type
+ */
+export type OmitIndexedAccess<T> = {
+  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};

package/src/typescript/pick-call-signature.ts

@@ -0,0 +1,8 @@
+import { type GenericFunction } from './generic-function.js';
+
+/**
+ * Picks a call signature from a type
+ *
+ * @template T Type
+ */
+export type PickCallSignature<T extends GenericFunction> = (...parameters: Parameters<T>) => ReturnType<T>;

package/src/typescript/properties-to-union.ts

@@ -0,0 +1,6 @@
+/**
+ * Union of an object's properties
+ */
+export type PropertiesToUnion<T> = {
+  [PropertyKey in keyof T]: { [P in PropertyKey]: T[PropertyKey] };
+}[keyof T];

package/src/typescript/readonly-record.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type ReadonlyRecord } from './readonly-record.js';
+
+describe('Readonly record', () => {
+  it('defines a type with read-only properties', () => {
+    // given: keys and a value type
+    type Keys = 'a' | 'b';
+    type ValueType = number;
+
+    // when: defining a record
+    type TestRecord = ReadonlyRecord<Keys, ValueType>;
+
+    // expect: a record with readonly properties to have been defined
+    expectTypeOf<TestRecord>().toEqualTypeOf<{ readonly a: number; readonly b: number }>();
+  });
+});

package/src/typescript/readonly-record.ts

@@ -0,0 +1,10 @@
+/**
+ * Read-only record
+ *
+ * @template K Key type
+ * @template T Value type
+ */
+// oxlint-disable-next-line @typescript-eslint/no-explicit-any
+export type ReadonlyRecord<K extends keyof any, T> = {
+  readonly [P in K]: T;
+};

package/src/typescript/schema/type-creator.ts

@@ -0,0 +1,6 @@
+/**
+ * Type creator
+ */
+export type TypeCreator<Parameters, CreatedType> = Parameters extends void
+  ? () => CreatedType
+  : (parameters: Parameters) => CreatedType;

package/src/typescript/schema/type-schema-symbol.ts

@@ -0,0 +1,9 @@
+/**
+ * Type schema type name symbol
+ */
+export const typeSchemaTypeName = Symbol('@edumalin/platform/typescript:type-schema-type-name');
+
+/**
+ * Type schema type symbol
+ */
+export const typeSchemaType = Symbol('@edumalin/platform/typescript:type-schema-type');

package/src/typescript/schema/type-schema-type-name.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type TypeSchema } from './type-schema.js';
+import { type TypeSchemaTypeName } from './type-schema-type-name.js';
+
+describe('Type schema type name', () => {
+  it('can infer the type name of a type schema', () => {
+    // given: a type name
+    type SchemaTypeName = 'test-schema-type-name';
+    // and: a type schema using that name
+    type TestTypeSchema = TypeSchema<SchemaTypeName, boolean>;
+
+    // expect: the type name to be inferred from the type schema
+    expectTypeOf<TypeSchemaTypeName<TestTypeSchema>>().toEqualTypeOf<SchemaTypeName>();
+  });
+});

package/src/typescript/schema/type-schema-type-name.ts

@@ -0,0 +1,10 @@
+import { type TypeSchema } from './type-schema.js';
+
+/**
+ * Type schema type name from a type schema
+ *
+ * @returns Schema type name
+ * @template Schema Type schema
+ */
+export type TypeSchemaTypeName<Schema extends TypeSchema<string, unknown>> =
+  Schema extends TypeSchema<infer SchemaTypeSymbol, unknown> ? SchemaTypeSymbol : never;

package/src/typescript/schema/type-schema-type.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type TypeSchema } from './type-schema.js';
+import { type TypeSchemaType } from './type-schema-type.js';
+
+describe('Type schema type', () => {
+  it('can infer the type name of a type schema', () => {
+    // given: a schema type
+    type SchemaType = boolean;
+    // and: a type schema using that schema type
+    type TestTypeSchema = TypeSchema<'test', SchemaType>;
+
+    // when: getting the type from a type schema
+    type Result = TypeSchemaType<TestTypeSchema>;
+
+    // expect: the type to have been inferred from the type schema
+    expectTypeOf<Result>().toEqualTypeOf<SchemaType>();
+  });
+});

package/src/typescript/schema/type-schema-type.ts

@@ -0,0 +1,10 @@
+import { type TypeSchema } from './type-schema.js';
+
+/**
+ * Type schema type from a type schema
+ *
+ * @returns Type schema type
+ * @template Schema Type schema
+ */
+export type TypeSchemaType<Schema extends TypeSchema<string, unknown>> =
+  Schema extends TypeSchema<string, infer SchemaType> ? SchemaType : never;

package/src/typescript/schema/type-schema.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { type TypeSchema } from './type-schema.js';
+import { typeSchema } from './type-schema.js';
+import { typeSchemaTypeName } from './type-schema-symbol.js';
+
+describe('Type schema', () => {
+  it('can define a type schema', () => {
+    // given: a schema type name and type
+    const schemaTypeName = 'test-type' as const;
+    type SchemaType = { x: number };
+
+    // when: creating a type schema
+    const schema = typeSchema<typeof schemaTypeName, { x: number }>(schemaTypeName);
+
+    // expect: a property typed type schema to be created
+    expect(schema[typeSchemaTypeName]).toBe(schemaTypeName);
+    expectTypeOf(schema).toEqualTypeOf<TypeSchema<'test-type', SchemaType>>();
+  });
+});

package/src/typescript/schema/type-schema.ts

@@ -0,0 +1,29 @@
+import { typeSchemaType, typeSchemaTypeName } from './type-schema-symbol.js';
+
+/**
+ * Type schema
+ *
+ * @template SchemaTypeName Schema type name
+ * @template SchemaType Schema type
+ */
+export interface TypeSchema<SchemaTypeName extends string, SchemaType> {
+  readonly [typeSchemaTypeName]: SchemaTypeName;
+  readonly [typeSchemaType]: SchemaType;
+}
+
+/**
+ * Creates schema typing information
+ *
+ * @param schemaTypeName Schema type name
+ * @returns Type schema
+ * @template SchemaTypeName Schema type name
+ * @template SchemaType Schema type
+ */
+export function typeSchema<SchemaTypeName extends string, SchemaType>(
+  schemaTypeName: SchemaTypeName
+): TypeSchema<SchemaTypeName, SchemaType> {
+  return {
+    [typeSchemaTypeName]: schemaTypeName,
+    [typeSchemaType]: void 0 as unknown as SchemaType,
+  };
+}

package/src/typescript/union-to-intersection.ts

@@ -0,0 +1,8 @@
+/**
+ * Union to intersection
+ */
+export type UnionToIntersection<Union> = (Union extends any ? (_: Union) => void : never) extends (
+  _: infer Intersection
+) => void
+  ? Intersection
+  : never;

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

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

package/src/url/index.ts

@@ -0,0 +1,4 @@
+export { asUrlString } from './string/as-url-string.js';
+export { isUrlString } from './string/is-url-string.js';
+export { type UrlString } from './string/url-string.js';
+export { validateUrlString } from './string/validate-url-string.js';

package/src/url/string/as-url-string.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { asUrlString } from './as-url-string.js';
+
+describe('As URL string', () => {
+  it('safely casts a string to a URL string', () => {
+    // given: a valid URL string
+    const value = 'https://developer.edumalin.com/';
+
+    // when: casting the string to a URL string
+    const urlString = asUrlString(value);
+
+    // then: the URL string is left untouched
+    expect(urlString).toBe(value);
+  });
+
+  it('returns a URL string when given a URL', () => {
+    // given: a URL
+    const url = new URL('https://developer.edumalin.com');
+
+    // when: casting the URL to a URL string
+    const urlString = asUrlString(url);
+
+    // then: the URL string representation is returned
+    expect(urlString).toBe(url.toString());
+  });
+
+  it('throws an error when the string is not a valid URL string', () => {
+    // given: an invalid URL string
+    const value = 'a';
+
+    // expect: casting the string to a URL string to throw
+    expect(() => asUrlString(value)).toThrow(`@edumalin/platform:error:invalidUrlString`);
+  });
+});

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

@@ -0,0 +1,19 @@
+import { urlError } from '../url.error.js';
+import { type UrlString } from './url-string.js';
+
+/**
+ * Safely casts a value to a URL string
+ *
+ * @param value Value
+ * @returns URL string
+ */
+export function asUrlString(value: unknown): UrlString {
+  if (typeof value === 'string' || (typeof value === 'object' && value !== null && value instanceof URL)) {
+    try {
+      const url = typeof value === 'string' ? new URL(value) : value;
+      return url.toString() as UrlString;
+    } catch {}
+  }
+
+  throw urlError.invalidUrlString({ value });
+}

package/src/url/string/is-url-string.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isUrlString } from './is-url-string.js';
+import { type UrlString } from './url-string.js';
+
+describe('Is URL string', () => {
+  it.each([
+    ['https://developer.edumalin.com', true],
+    ['developer.edumalin.com', false],
+  ])('returns true when a string is a URL', (value, expectedResult) => {
+    // given: a string
+
+    // when: testing whether the string is a URL string
+    const result = isUrlString(value);
+
+    // expect: true to be returned when the string is a valid URL
+    expect(result).toBe(expectedResult);
+  });
+
+  it('asserts the type of the parameter', () => {
+    // given: an string
+    // oxlint-disable-next-line @typescript-eslint/no-inferrable-types
+    const value: string = '123456789012';
+
+    // expect: the conditional branch to assert the variable type
+    if (isUrlString(value)) {
+      expectTypeOf(value).toEqualTypeOf<UrlString>();
+    }
+  });
+});

package/src/url/string/is-url-string.ts

@@ -0,0 +1,20 @@
+import { type UrlString } from './url-string.js';
+
+/**
+ * Tests whether a value is a valid URL
+ *
+ * @param value Value
+ * @returns true if the value is a valid URL
+ */
+export function isUrlString(value: unknown): value is UrlString {
+  if (typeof value !== 'string') {
+    return false;
+  }
+
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/url/string/url-string.ts

@@ -0,0 +1,6 @@
+/**
+ * URL string
+ */
+export type UrlString = string & {
+  readonly __tag_platformUrlString: unique symbol;
+};

package/src/url/string/validate-url-string.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { validateUrlString } from './validate-url-string.js';
+
+describe('Validate URL string', () => {
+  it('throws an error when a URL string is not valid', () => {
+    // given: an invalid URL string
+    const value = 'developer.edumalin.com';
+
+    // expect: validating the string to throw
+    expect(() => validateUrlString(value)).toThrow(`@edumalin/platform:error:invalidUrlString`);
+  });
+
+  it('does not throw when a URL string is valid', () => {
+    // given: a valid URL string
+    const value = 'https://developer.edumalin.com';
+
+    // expect: validating the string not to throw
+    expect(() => validateUrlString(value)).not.toThrow();
+  });
+});

package/src/url/string/validate-url-string.ts

@@ -0,0 +1,14 @@
+import { urlError } from '../url.error.js';
+import { isUrlString } from './is-url-string.js';
+import { type UrlString } from './url-string.js';
+
+/**
+ * Validates that a value is a URL
+ *
+ * @param value Value
+ */
+export function validateUrlString(value: unknown): asserts value is UrlString {
+  if (!isUrlString(value)) {
+    throw urlError.invalidUrlString({ value });
+  }
+}

package/src/url/url.error.ts

@@ -0,0 +1,14 @@
+import { platformDomain } from '@edumalin/platform';
+import { createErrorType, errorProperties } from '@edumalin/platform/error';
+
+import { type InvalidUrlStringErrorProperties } from './error/invalid-url-string-error-properties';
+
+/**
+ * URL error
+ */
+export const urlError = createErrorType(platformDomain, {
+  /**
+   * Invalid URL string
+   */
+  invalidUrlString: errorProperties<InvalidUrlStringErrorProperties>(),
+});

package/src/uuid/as-uuid.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { asUUID } from './as-uuid.js';
+import { uuidError } from './uuid.error.js';
+
+describe('As UUID', () => {
+  it('safely casts a string to a UUID', () => {
+    // given: a valid UUID string
+    const value = 'bee71150-a94b-4a64-89f5-2c4472910da8';
+
+    // when: casting the string to a UUID
+    const uuid = asUUID(value);
+
+    // then: the UUID is left untouched
+    expect(uuid).toBe(value);
+  });
+
+  it('throws an error when the string is not a valid UUID', () => {
+    // given: an invalid UUID string
+    const value = 'a';
+
+    // expect: casting the string to a UUID to throw
+    expect(() => asUUID(value)).toThrow(uuidError.invalidUuid({ value }));
+  });
+});

package/src/uuid/as-uuid.ts

@@ -0,0 +1,13 @@
+import { type UUID } from './uuid.js';
+import { validateUUID } from './validate-uuid.js';
+
+/**
+ * Returns a value as a UUID
+ *
+ * @param value Value
+ * @returns UUID
+ */
+export function asUUID(value: unknown): UUID {
+  validateUUID(value);
+  return value;
+}

package/src/uuid/error/invalid-uuid-error-properties.ts

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

package/src/uuid/generate-uuid.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+import { generateUUID } from './generate-uuid.js';
+import { isUUID } from './is-uuid.js';
+
+describe('Generate UUID', () => {
+  it('generates a random UUID', () => {
+    // when: generating a random UUID
+    const uuid = generateUUID();
+
+    // then: a properly built random UUID is generated
+    expect(isUUID(uuid)).toBe(true);
+  });
+});

package/src/uuid/generate-uuid.ts

@@ -0,0 +1,12 @@
+import { asUUID } from './as-uuid.js';
+import { type UUID } from './uuid.js';
+
+/**
+ * Generates an UUID v4 string
+ *
+ * @returns UUID v4 string
+ */
+export function generateUUID(): UUID {
+  const uuidString = globalThis.crypto.randomUUID();
+  return asUUID(uuidString);
+}

package/src/uuid/index.ts

@@ -0,0 +1,7 @@
+export { asUUID } from './as-uuid.js';
+export { generateUUID } from './generate-uuid.js';
+export { type InvalidUuidErrorProperties } from './error/invalid-uuid-error-properties.js';
+export { isUUID } from './is-uuid.js';
+export { type UUID } from './uuid.js';
+export { uuidError } from './uuid.error.js';
+export { validateUUID } from './validate-uuid.js';

package/src/uuid/is-uuid.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isUUID } from './is-uuid.js';
+import { type UUID } from './uuid.js';
+
+describe('Is UUID', () => {
+  it.each([
+    ['a', false],
+    ['bee71150-a94b-4a64-89f5-2c4472910da80', false],
+    ['bee71150-a94b-4a64-89f5-2c4472910da', false],
+    ['bee71150-a94b-4a64-89f5-2c4472910da8', true],
+  ])('returns true when a string is a UUID', (value, expectedResult) => {
+    // when: testing whether a string is a UUID
+    const result = isUUID(value);
+
+    // expect: true to be returned if the string is a UUID
+    expect(result).toBe(expectedResult);
+  });
+
+  it('asserts the type of the parameter', () => {
+    // given: a UUID
+    // oxlint-disable-next-line @typescript-eslint/no-inferrable-types
+    const value: string = 'bee71150-a94b-4a64-89f5-2c4472910da8';
+
+    // expect: the conditional branch to assert the variable type
+    if (isUUID(value)) {
+      expectTypeOf(value).toEqualTypeOf<UUID>();
+    }
+  });
+});

package/src/uuid/is-uuid.ts

@@ -0,0 +1,12 @@
+import { type UUID } from './uuid.js';
+
+/**
+ * Returns true if a value is a UUID
+ *
+ * @param value Value
+ * @returns true if the value is a UUID
+ */
+export function isUUID(value: unknown): value is UUID {
+  // TODO: stronger check
+  return typeof value === 'string' && value.length === 36;
+}

package/src/uuid/uuid.error.ts

@@ -0,0 +1,15 @@
+import { platformDomain } from '@edumalin/platform';
+import { createErrorType, errorProperties } from '@edumalin/platform/error';
+
+import { type InvalidUuidErrorProperties } from './error/invalid-uuid-error-properties.js';
+
+/**
+ *
+ * Invalid UUID error
+ */
+export const uuidError = createErrorType(platformDomain, {
+  /**
+   * Invalid UUID
+   */
+  invalidUuid: errorProperties<InvalidUuidErrorProperties>(),
+});

package/src/uuid/uuid.ts

@@ -0,0 +1,6 @@
+/**
+ * UUID
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}` & {
+  readonly __tag_platformUuid: unique symbol;
+};