@edumalin/platform 3.0.0

package/src/event/matcher/match-event.ts

@@ -0,0 +1,22 @@
+import { type Event } from '../event.js';
+import { type EventName } from '../event-name.js';
+import { type EventMatcher } from './event-matcher.js';
+import { type EventMatcherCase } from './event-matcher-case.js';
+
+/**
+ * Matches a event, branching based on the event type
+ *
+ * @param event Event
+ * @param matcher Matcher
+ * @returns Matcher result
+ * @template EventType Event type
+ * @template ResultType Result type
+ */
+export function matchEvent<EventType extends Event, ResultType>(
+  event: EventType,
+  matcher: EventMatcher<EventType, ResultType>
+): ResultType {
+  const { name, properties } = event;
+  const handler = matcher[name as EventName<EventType>] as EventMatcherCase<EventType, ResultType>;
+  return handler(properties, event);
+}

package/src/event/matcher/match-events.ts

@@ -0,0 +1,44 @@
+import { arrayToDeduplicatedArray } from '@edumalin/platform/collection';
+import { entriesToObject, objectToEntries } from '@edumalin/platform/functional';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type Event } from '../event.js';
+import { type EventsMatcher } from './events-matcher.js';
+import { type EventName } from '../event-name.js';
+import { eventToEventName } from '../properties/event-to-event-name.js';
+import { eventToEventProperties } from '../properties/event-to-event-properties.js';
+import { type EventsMatcherCase } from './events-matcher-case.js';
+
+/**
+ * Matches a event, branching based on the event type
+ *
+ * @param events Events
+ * @param matcher Matcher
+ * @returns Matcher result
+ * @template EventType Event type
+ * @template ResultType Result type
+ */
+export function matchEvents<EventType extends Event, ResultType>(
+  events: ReadonlyArray<EventType>,
+  matcher: EventsMatcher<EventType, ResultType>
+): ReadonlyRecord<EventName<EventType>, ResultType> {
+  type Name = EventName<EventType>;
+  const toUniqueEventNames = arrayToDeduplicatedArray({ valueSelector: eventToEventName });
+  const eventNames = toUniqueEventNames(events) as unknown as ReadonlyArray<Name>;
+  const eventsByName = events.reduce(
+    (acc, event) => {
+      acc[event.name as Name].push(event);
+      return acc;
+    },
+    entriesToObject(eventNames.map(eventName => [eventName, [] as Array<EventType>] as const))
+  );
+
+  return entriesToObject(
+    objectToEntries(eventsByName).map(([eventName, events]) => {
+      const handler = matcher[eventName] as EventsMatcherCase<EventType, ResultType>;
+      const eventProperties = events.map(eventToEventProperties);
+      const result = handler(eventProperties, events);
+      return [eventName, result] as const;
+    })
+  );
+}

package/src/event/properties/event-properties-from-event-definitions.ts

@@ -0,0 +1,14 @@
+import { type ReadonlyRecord, type TypeSchemaType } from '@edumalin/platform/typescript';
+
+import { type EventPropertiesSchema } from './event-properties-schema.js';
+
+/**
+ * Event properties from event definitions
+ *
+ * @template EventDefinitions Event definitions
+ */
+export type EventPropertiesFromEventDefinitions<
+  EventDefinitions extends ReadonlyRecord<string, EventPropertiesSchema<any>>,
+> = {
+  [EventName in keyof EventDefinitions & string]: TypeSchemaType<EventDefinitions[EventName]>;
+};

package/src/event/properties/event-properties-schema-type-name.ts

@@ -0,0 +1,4 @@
+/**
+ * Event properties schema type name
+ */
+export const eventPropertiesSchemaTypeName = '@edumalin/platform/event:properties';

package/src/event/properties/event-properties-schema.ts

@@ -0,0 +1,10 @@
+import { type TypeSchema } from '@edumalin/platform/typescript';
+
+import { type eventPropertiesSchemaTypeName } from './event-properties-schema-type-name.js';
+
+/**
+ * Event properties schema
+ *
+ * @template SchemaType Schema type
+ */
+export type EventPropertiesSchema<SchemaType> = TypeSchema<typeof eventPropertiesSchemaTypeName, SchemaType>;

package/src/event/properties/event-properties.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { eventProperties } from './event-properties.js';
+import { type EventPropertiesSchema } from './event-properties-schema.js';
+
+describe('Event properties', () => {
+  it('defines an event properties schema', () => {
+    // given: an event properties type
+    interface TestSchema {
+      test: number;
+    }
+
+    // when: creating a schema
+    const schema = eventProperties<TestSchema>();
+
+    // expect: the schema to be an event properties schema for the specified properties type
+    expectTypeOf(schema).toEqualTypeOf<EventPropertiesSchema<TestSchema>>();
+  });
+});

package/src/event/properties/event-properties.ts

@@ -0,0 +1,17 @@
+import { typeSchema } from '@edumalin/platform/typescript';
+
+import { type EventPropertiesSchema } from './event-properties-schema.js';
+import { eventPropertiesSchemaTypeName } from './event-properties-schema-type-name.js';
+
+/**
+ * Creates a event properties schema
+ *
+ * @returns Event properties schema
+ * @template SchemaType Schema type
+ */
+export function eventProperties(): EventPropertiesSchema<void>;
+export function eventProperties<SchemaType>(): EventPropertiesSchema<SchemaType>;
+
+export function eventProperties<SchemaType>(): EventPropertiesSchema<SchemaType> {
+  return typeSchema<typeof eventPropertiesSchemaTypeName, SchemaType>(eventPropertiesSchemaTypeName);
+}

package/src/event/properties/event-to-event-name.ts

@@ -0,0 +1,12 @@
+import { type Event } from '../event.js';
+
+/**
+ * Returns an event's name, given an event
+ *
+ * @param event Event
+ * @returns Event name
+ * @template EventType Event type
+ */
+export function eventToEventName<EventType extends Event>(event: EventType): EventType['name'] {
+  return event.name;
+}

package/src/event/properties/event-to-event-properties.spec.ts

@@ -0,0 +1,22 @@
+import { createDomain } from '@edumalin/platform/domain';
+import { describe, expect, it } from 'vitest';
+
+import { createEventType } from '../type/create-event-type.js';
+import { eventProperties } from './event-properties.js';
+import { eventToEventProperties } from './event-to-event-properties.js';
+
+describe('Event to event properties', () => {
+  const testDomain = createDomain('test');
+  it('returns properties, given an event', () => {
+    // given: an event
+    const eventType = createEventType(testDomain, { testEvent: eventProperties<{ test: string }>() });
+    const expectedProperties = { test: 'test' };
+    const event = eventType.testEvent(expectedProperties);
+
+    // when: getting the properties from the event
+    const properties = eventToEventProperties(event);
+
+    // then: the event's properties have been returned
+    expect(properties).toBe(expectedProperties);
+  });
+});

package/src/event/properties/event-to-event-properties.ts

@@ -0,0 +1,12 @@
+import { type Event } from '../event.js';
+
+/**
+ * Returns an event's properties, given an event
+ *
+ * @param event Event
+ * @returns Event properties
+ * @template EventType Event type
+ */
+export function eventToEventProperties<EventType extends Event>(event: EventType): EventType['properties'] {
+  return event.properties;
+}

package/src/event/type/create-event-type.spec.ts

@@ -0,0 +1,9 @@
+import { describe, it } from 'vitest';
+
+import { createEventType } from './create-event-type.js';
+
+describe('Create event type', () => {
+  createEventType;
+
+  it.todo('works');
+});

package/src/event/type/create-event-type.ts

@@ -0,0 +1,34 @@
+import { type Domain } from '@edumalin/platform/domain';
+import { objectToEntries } from '@edumalin/platform/functional';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EventPropertiesFromEventDefinitions } from '../properties/event-properties-from-event-definitions.js';
+import { type EventPropertiesSchema } from '../properties/event-properties-schema.js';
+import { eventCreatorEntryToPropertyDescriptorMap } from './event-creator-entry-to-property-descriptor-map.js';
+import { eventPropertiesSchemaEntryToEventCreatorEntry } from './event-properties-schema-entry-to-event-creator-entry.js';
+import { type EventType } from './event-type.js';
+
+/**
+ * Creates a event type
+ *
+ * @param domain Domain
+ * @param definitions Event definitions
+ * @returns Event group
+ * @template DomainType Domain type
+ * @template EventDefinitions Event definitions
+ */
+export function createEventType<
+  DomainType extends Domain,
+  EventDefinitions extends ReadonlyRecord<string, EventPropertiesSchema<any>>,
+>(
+  domain: DomainType,
+  definitions: EventDefinitions
+): EventType<DomainType, EventPropertiesFromEventDefinitions<EventDefinitions>> {
+  const propertyDescriptors = objectToEntries(definitions)
+    .map(eventPropertiesSchemaEntryToEventCreatorEntry(domain))
+    .reduce<PropertyDescriptorMap>(eventCreatorEntryToPropertyDescriptorMap, {});
+  return Object.defineProperties({}, propertyDescriptors) as EventType<
+    DomainType,
+    EventPropertiesFromEventDefinitions<EventDefinitions>
+  >;
+}

package/src/event/type/event-creator-entry-to-property-descriptor-map.ts

@@ -0,0 +1,25 @@
+import { type EventCreatorEntry } from './event-creator-entry.js';
+
+/**
+ * Adds an event creator property descriptor to a property descriptor map and returns it
+ *
+ * @param propertyDescriptorMap Property descriptor map
+ * @param eventCreatorEntry Event creator entry
+ * @returns Property descriptor map
+ * @private
+ */
+export function eventCreatorEntryToPropertyDescriptorMap(
+  propertyDescriptorMap: PropertyDescriptorMap,
+  eventCreatorEntry: EventCreatorEntry
+): PropertyDescriptorMap {
+  const [eventName, eventCreator] = eventCreatorEntry;
+
+  return {
+    ...propertyDescriptorMap,
+    [eventName]: {
+      enumerable: false,
+      value: eventCreator,
+      writable: false,
+    },
+  };
+}

package/src/event/type/event-creator-entry.ts

@@ -0,0 +1,8 @@
+import { type TypeCreator } from '@edumalin/platform/typescript';
+
+import { type EventCreator } from '../creator/event-creator.js';
+
+/**
+ * Event creator entry
+ */
+export type EventCreatorEntry = readonly [eventName: string, eventCreator: EventCreator<string, TypeCreator<any, any>>];

package/src/event/type/event-from-type.ts

@@ -0,0 +1,12 @@
+import { type EventFromCreator } from '../creator/event-from-creator.js';
+import { type EventType as GenericEventType } from './event-type.js';
+
+/**
+ * Event from event type
+ *
+ * @template EventType Event type
+ */
+export type EventFromType<
+  EventType extends GenericEventType,
+  EventName extends keyof EventType & string = keyof EventType & string,
+> = EventFromCreator<EventType[EventName]>;

package/src/event/type/event-properties-schema-entry-to-event-creator-entry.ts

@@ -0,0 +1,25 @@
+import { type Domain } from '@edumalin/platform/domain';
+
+import { type EventPropertiesSchema } from '../properties/event-properties-schema.js';
+import { type EventCreatorEntry } from './event-creator-entry.js';
+
+/**
+ * Returns an event creator entry, given an entry with an event properties schema
+ *
+ * @param domain Domain
+ * @returns Event creator entry
+ * @template DomainType Domain type
+ * @private
+ */
+export function eventPropertiesSchemaEntryToEventCreatorEntry<DomainType extends Domain>(
+  domain: DomainType
+): (entry: readonly [name: string, schema: EventPropertiesSchema<unknown>]) => EventCreatorEntry {
+  return ([name]) => {
+    const creator = (properties: unknown) => ({
+      domain,
+      name,
+      ...(properties !== undefined ? { properties } : {}),
+    });
+    return [name, creator];
+  };
+}

package/src/event/type/event-type-with-events.ts

@@ -0,0 +1,26 @@
+import { entriesToObject, objectToEntries } from '@edumalin/platform/functional';
+
+import { type EventType as GenericEventType } from './event-type.js';
+
+/**
+ * Creates a function that returns an event type with only a subset of events
+ *
+ * @param eventType Event type
+ * @returns Function that returns an event type with only a subset of events
+ * @template EventType Event type
+ */
+export function eventTypeWithEvents<EventType extends GenericEventType>(
+  eventType: EventType
+): <EventNames extends ReadonlyArray<keyof EventType & string>>(
+  ...eventNames: EventNames
+) => Pick<EventType, EventNames[number]> {
+  type EventTypeEntry = readonly [key: keyof GenericEventType, value: EventType[keyof EventType]];
+  const eventTypeEntries = objectToEntries(eventType) as ReadonlyArray<EventTypeEntry>;
+
+  return <EventNames extends ReadonlyArray<keyof EventType & string>>(...eventNames: EventNames) => {
+    const set = new Set(eventNames);
+    const filteredEntries = eventTypeEntries.filter(([eventName]) => set.has(eventName));
+
+    return entriesToObject(filteredEntries) as Pick<EventType, EventNames[number]>;
+  };
+}

package/src/event/type/event-type.ts

@@ -0,0 +1,31 @@
+import { type Domain } from '@edumalin/platform/domain';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EventCreator } from '../creator/event-creator.js';
+import { type Event } from '../event.js';
+
+/**
+ * Event type
+ *
+ * @template DomainType Domain type
+ * @template EventPropertiesByEventName Event properties by event name
+ */
+export type EventType<
+  DomainType extends Domain = Domain,
+  EventPropertiesByEventName extends ReadonlyRecord<string, any> = ReadonlyRecord<string, any>,
+> = {
+  /**
+   * Creates a new event
+   *
+   * @param properties Event properties
+   * @returns Event
+   */
+  readonly [EventName in keyof EventPropertiesByEventName & string]: EventCreator<
+    EventName,
+    EventPropertiesByEventName[EventName] extends void
+      ? () => Event<DomainType, EventName, EventPropertiesByEventName[EventName]>
+      : (
+          properties: EventPropertiesByEventName[EventName]
+        ) => Event<DomainType, EventName, EventPropertiesByEventName[EventName]>
+  >;
+};

package/src/functional/call-with.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates a function that calls a function with a set of parameters
+ *
+ * @param parameters Parameters
+ * @returns Function that calls a function with a set of parameters
+ * @template Parameters Parameters type
+ */
+export function callWith<Parameters extends ReadonlyArray<unknown>>(
+  ...parameters: Parameters
+): <T>(func: (...parameters: Parameters) => T) => T {
+  return <T>(func: (...parameters: Parameters) => T) => func(...parameters);
+}

package/src/functional/entries-to-object.spec.ts

@@ -0,0 +1,11 @@
+import { describe, it } from 'vitest';
+
+import { entriesToObject } from './entries-to-object.js';
+
+describe('Entries to object', () => {
+  entriesToObject;
+
+  it.todo('builds an object from a list of entries');
+
+  it.todo('properly infers the object type');
+});

package/src/functional/entries-to-object.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates an object from a list of key/value pairs
+ *
+ * @param entries Entries
+ * @returns Object
+ */
+export function entriesToObject<K extends string, T>(
+  entries: ReadonlyArray<readonly [key: K, value: T]>
+): Record<K, T> {
+  return Object.fromEntries(entries) as Record<K, T>;
+}

package/src/functional/identity.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { identity } from './identity.js';
+
+describe('Identity', () => {
+  it('returns its argument', () => {
+    // given: an argument
+    const argument = 42;
+
+    // when: calling identity
+    const result = identity(argument);
+
+    // expect: the returned value to be the argument
+    expect(result).toBe(argument);
+  });
+});

package/src/functional/identity.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the passed parameter without making any change
+ *
+ * @param value Value
+ * @returns Value
+ */
+export function identity<T>(value: T): T {
+  return value;
+}

package/src/functional/index.ts

@@ -0,0 +1,12 @@
+export { callWith } from './call-with.js';
+export { entriesToObject } from './entries-to-object.js';
+export { identity } from './identity.js';
+export { isDefined } from './is-defined.js';
+export { isInstanceOf } from './is-instance-of.js';
+export { isNotNull } from './is-not-null.js';
+export { not } from './not.js';
+export { objectToEntries } from './object-to-entries.js';
+export { objectToKeys } from './object-to-keys.js';
+export { objectToValues } from './object-to-values.js';
+export { objectWithProperties } from './object-with-properties.js';
+export { pipe } from './pipe.js';

package/src/functional/is-defined.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isDefined } from './is-defined.js';
+
+describe('Is defined', () => {
+  it('returns true when a value is defined', () => {
+    // expect: true to be returned when the value is defined
+    expect(isDefined('test')).toBe(true);
+  });
+
+  it('returns false when a value is undefined', () => {
+    // expect: false to be returned when the value is undefined
+    expect(isDefined(undefined)).toBe(false);
+  });
+
+  it('acts as a type guard', () => {
+    // given: a value that may be undefined
+    const value: string | undefined = 'test';
+
+    // when: conditionally testing that a value is defined
+    if (isDefined(value)) {
+      // then: the type of the tested value excludes undefined
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});

package/src/functional/is-defined.ts

@@ -0,0 +1,10 @@
+/**
+ * Type guard that tests whether a value is defined
+ *
+ * @param value Value
+ * @returns true if the value is defined
+ * @template T Value type
+ */
+export function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}

package/src/functional/is-instance-of.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { isInstanceOf } from './is-instance-of.js';
+
+describe('Is instance of', () => {
+  it.each([
+    [Array, [], true],
+    [Array, {}, false],
+    [Function, () => void 0, true],
+    [Function, {}, false],
+    [Object, {}, true],
+    [Object, [], true],
+    [Object, 'str', false],
+  ])(
+    'creates a function that tests whether a value is an instance of a given class',
+    (instanceClass, value, expectedResult) => {
+      // given: an instance class
+
+      // when: creating a function that tests whether a value is an instance of the given class
+      const func = isInstanceOf(instanceClass);
+
+      // and: calling it
+      const result = func(value);
+
+      // expect: true to have been returned if the value is an instance of the given class
+      expect(result).toBe(expectedResult);
+    }
+  );
+
+  it.todo('performs a type assertion');
+});

package/src/functional/is-instance-of.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a function that tests whether a value is an instance of a given class
+ *
+ * @param instanceClass Instance class
+ * @returns Function that tests whether a value is an instance of the given class
+ * @template T Instance type
+ */
+export function isInstanceOf<T>(instanceClass: new (...args: ReadonlyArray<any>) => T): (arg: unknown) => arg is T {
+  return (value: unknown): value is T => value instanceof instanceClass;
+}

package/src/functional/is-not-null.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { isNotNull } from './is-not-null.js';
+
+describe('Is not null', () => {
+  it('returns true when a value is not null', () => {
+    // expect: true to be returned when the value is not null
+    expect(isNotNull('test')).toBe(true);
+  });
+
+  it('returns false when a value is null', () => {
+    // expect: false to be returned when the value is null
+    expect(isNotNull(null)).toBe(false);
+  });
+
+  it('acts as a type guard', () => {
+    // given: a value that may be null
+    const value: string | null = 'test';
+
+    // when: conditionally testing that a value is not null
+    if (isNotNull(value)) {
+      // then: the type of the tested value excludes null
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+});

package/src/functional/is-not-null.ts

@@ -0,0 +1,9 @@
+/**
+ * Type guard that tests whether a value is not null
+ *
+ * @param value Value
+ * @returns true if the value is not null
+ */
+export function isNotNull<T>(value: T | null): value is T {
+  return value !== null;
+}

package/src/functional/not.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates a function that inverts the result of another function
+ *
+ * @param fn Function
+ * @returns `false` if the wrapped function returns `true`, otherwise `true`
+ * @template Parameters Parameters type
+ */
+export function not<Parameters extends ReadonlyArray<unknown>>(
+  fn: (...parameters: Parameters) => boolean
+): (...parameters: Parameters) => boolean {
+  return (...parameters) => !fn(...parameters);
+}

package/src/functional/object-to-entries.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { objectToEntries } from './object-to-entries.js';
+
+describe('Object to entries', () => {
+  const obj = {
+    s: 'test',
+    n: 42,
+  };
+
+  it('returns entries, given an object', () => {
+    // given: an object
+
+    // when: getting entries from the object
+    const entries = objectToEntries(obj);
+
+    // then: the list of entries is returned
+    expect(entries).toEqual(
+      expect.arrayContaining([
+        ['s', 'test'],
+        ['n', 42],
+      ])
+    );
+  });
+
+  it('properly infers the entries type', () => {
+    // given: an object
+
+    // when: getting entries from the object
+    // oxlint-disable-next-line @typescript-eslint/no-unused-vars
+    const entries = objectToEntries(obj);
+
+    // then: the list is properly typed
+    type EntryType = (typeof entries)[number];
+    type KeyType = EntryType[0];
+    type ValueType = EntryType[1];
+    expectTypeOf<KeyType>().toEqualTypeOf<'s' | 'n'>();
+    expectTypeOf<ValueType>().toEqualTypeOf<string | number>();
+  });
+});

package/src/functional/object-to-entries.ts

@@ -0,0 +1,13 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+/**
+ * Returns the list of key/value pairs from an object
+ *
+ * @param obj Object
+ * @returns List of key/value pairs
+ */
+export function objectToEntries<K extends string, T>(
+  obj: ReadonlyRecord<K, T>
+): ReadonlyArray<readonly [key: K, value: T]> {
+  return Object.entries(obj) as unknown as ReadonlyArray<readonly [key: K, value: T]>;
+}