effect-web-midi 0.1.0

package/src/internal/StreamMaker.ts

@@ -0,0 +1,414 @@
+/** biome-ignore-all lint/style/useShorthandFunctionType: It's a nice way to
+ * preserve JSDoc comments attached to the function signature */
+
+import * as Cause from 'effect/Cause'
+import * as Effect from 'effect/Effect'
+import * as EFunction from 'effect/Function'
+import * as Stream from 'effect/Stream'
+import type * as EMIDIAccess from './EMIDIAccess.ts'
+import type * as EMIDIInput from './EMIDIInput.ts'
+import type * as EMIDIOutput from './EMIDIOutput.ts'
+import * as Util from './util.ts'
+
+// TODO: make an experiment to see if listeners are automatically removed on disconnect
+
+/**
+ * Set of possible ways to react when the MIDI-related event will have relevant
+ * field be null. Although there should be no sane scenario where it would be
+ * the case, it's still allowed by the spec, and for a better UX this lib lets
+ * the developer make a decision on how to handle such cases.
+ *
+ * - `fail` will add an error into a signature of a stream, allowing the user to
+ *   handle it
+ * - `die` will throw a defect, which won't be reflected as a possible failure
+ *   in types
+ * - `ignore` will just silently remove such events from the stream
+ * - `passthrough` - will pass such events with an unmodified content of the
+ *   relevant field
+ *
+ * @internal
+ */
+const validOnNullStrategies = new Set([
+  'fail',
+  'die',
+  'ignore',
+  'passthrough',
+] as const)
+
+/**
+ * Helper utility to turn MIDI event listeners into effect's Streams.
+ *
+ * The signature is split into 2 calls, so that you are able at first call pass
+ * into generic an interface with `addEventListener` types of the raw web MIDI
+ * objects as keys and according event structures as values.
+ *
+ * **Second call arguments**
+ *
+ * - `isSelf` - Function determining if the maker was called as an overload with
+ *   all parameters passed all at once, or with them spread by 2 calls. `self`
+ *   will be later assigned to a `cameFrom` property of the object in the
+ *   success channel of the stream
+ *
+ * - `buildConfig` - Function that makes config out of an effectful version
+ *   (e.g. {@linkcode EMIDIAccess.EMIDIAccessInstance}, {@linkcode EMIDIInput.EMIDIInput},
+ *   {@linkcode EMIDIOutput.EMIDIOutput}) of a MIDI object.
+ *
+ * - `remapValueToContainer` - Callback that maps the value of the event's
+ *   selected field to an extension of the object inside stream's success
+ *   channel. All fields of the returned object must always be present and
+ *   should be consistently nullable, when the incoming event's field is null.
+ *
+ * @template TEventTypeToEventValueMap An interface with event types of raw
+ * Web MIDI objects as keys and according event structures as values. e.g.
+ * `MIDIAccessEventMap`, `MIDIPortEventMap`, `MIDIInputEventMap`
+ *
+ * @internal
+ */
+export const createStreamMakerFrom =
+  <TEventTypeToEventValueMap extends object>() =>
+  /**
+   * @param isSelf Function determining if the maker was called as an overload
+   * with all parameters passed all at once, or with them spread by 2 calls.
+   * `self` will be later assigned to a `cameFrom` property of the object in the
+   * success channel of the stream
+   *
+   * @param buildConfig Function that makes config out of an effectful version
+   * (e.g. {@linkcode EMIDIAccess.EMIDIAccessInstance}, {@linkcode EMIDIInput.EMIDIInput},
+   * {@linkcode EMIDIOutput.EMIDIOutput}) of a MIDI object.
+   *
+   * @param remapValueToContainer Callback that maps the `fieldValue` of the
+   * event's selected field (`nullableFieldName`) to an extension of the object
+   * inside stream's success channel. The value is not null, except when
+   * `onNullStrategy` is `'passthrough'`. All fields of the returned object must
+   * always be present and should be consistently nullable, if the incoming
+   * event's field is null.
+   */
+  <
+    TEventTarget extends Stream.EventListener<
+      TEventTypeToEventValueMap[TSelectedEventType]
+    >,
+    const TSelectedEventType extends Extract<
+      keyof TEventTypeToEventValueMap,
+      string
+    >,
+    const TNullableFieldName extends Extract<
+      keyof TEventTypeToEventValueMap[TSelectedEventType],
+      string
+    >,
+    TCameFrom,
+    const TTag extends string,
+    TContainerWithNullableFields extends object,
+  >(
+    isSelf: (self: unknown) => self is TCameFrom,
+    buildConfig: (
+      self: TCameFrom,
+    ) => StreamConfig<
+      TTag,
+      TEventTarget,
+      TSelectedEventType,
+      TNullableFieldName
+    >,
+    remapValueToContainer: (
+      fieldValue: TEventTypeToEventValueMap[TSelectedEventType][TNullableFieldName],
+    ) => TContainerWithNullableFields,
+  ): DualStreamMaker<TCameFrom, TTag, TContainerWithNullableFields> =>
+    EFunction.dual<
+      MakeStreamTargetLast<TCameFrom, TTag, TContainerWithNullableFields>,
+      MakeStreamTargetFirst<TCameFrom, TTag, TContainerWithNullableFields>
+    >(
+      Util.polymorphicCheckInDual(isSelf),
+      (cameFromPolymorphic, options) =>
+        Effect.gen(function* () {
+          const onNullStrategy = ((
+            options as { onExtremelyRareNullableField?: OnNullStrategy }
+          )?.onExtremelyRareNullableField ?? 'die') as Exclude<
+            OnNullStrategy,
+            undefined
+          >
+
+          if (!validOnNullStrategies.has(onNullStrategy))
+            throw new Error(
+              `Invalid strategy to handle nullish values: ${onNullStrategy}`,
+            )
+
+          const cameFrom = yield* Util.fromPolymorphic(
+            cameFromPolymorphic,
+            isSelf,
+          )
+
+          const {
+            tag,
+            eventListener: { target, type },
+            spanAttributes,
+            nullableFieldName: field,
+          } = buildConfig(cameFrom)
+
+          const missingFieldMessage = `Property ${field} of ${tag} is null`
+          const NullCausedErrorEffect = new Cause.NoSuchElementException(
+            missingFieldMessage,
+          )
+
+          return Stream.fromEventListener(target, type, options).pipe(
+            Stream.filter(
+              event => !!event[field] || onNullStrategy !== 'ignore',
+            ),
+            Stream.mapEffect(event =>
+              event[field] || onNullStrategy === 'passthrough'
+                ? Effect.succeed({
+                    _tag: tag,
+                    ...remapValueToContainer(event[field]),
+                    cameFrom,
+                    capturedAt: new Date(),
+                  })
+                : onNullStrategy === 'fail'
+                  ? NullCausedErrorEffect
+                  : Effect.dieMessage(missingFieldMessage),
+            ),
+            Stream.withSpan('MIDI Web API event stream', {
+              kind: 'producer',
+              attributes: { eventType: type, ...spanAttributes },
+            }),
+          )
+          // biome-ignore lint/suspicious/noExplicitAny: <I don't care>
+        }).pipe(Stream.unwrap) as any,
+    )
+
+interface StreamConfig<
+  TTag,
+  TEventTarget,
+  TSelectedEventType,
+  TNullableFieldName,
+> {
+  /**
+   * Tag that will be assigned to the object inside stream's success channel
+   */
+  readonly tag: TTag
+
+  /**
+   * Config specifying where to attach the event listener
+   */
+  readonly eventListener: {
+    /**
+     * Native MIDI object (e.g. {@linkcode MIDIAccess},
+     * {@linkcode MIDIInput}, {@linkcode MIDIOutput}) that can have new
+     * listeners attached
+     */
+    readonly target: TEventTarget
+
+    /**
+     * The type of event supported by the native MIDI object,
+     * `addEventListener`'s first argument (e.g.
+     * {@linkcode MIDIAccess.addEventListener|MIDIAccess's},
+     * {@linkcode MIDIInput.addEventListener|MIDIInput's},
+     * {@linkcode MIDIOutput.addEventListener|MIDIOutput's}) which can have
+     * new listeners attached. Restricted by the keys of
+     * {@linkcode TEventTypeToEventValueMap} passed in the first call
+     */
+    readonly type: TSelectedEventType
+  }
+
+  /**
+   * Additional attributes that will be attached to Open Telemetry span of
+   * the stream
+   */
+  readonly spanAttributes: {
+    readonly spanTargetName: string
+    readonly [k: string]: unknown
+  }
+
+  /**
+   * The name of the field that will be extracted from the event (e.g.
+   * {@linkcode MIDIConnectionEvent.port|MIDIConnectionEvent's port},
+   * {@linkcode MIDIMessageEvent.data|MIDIMessageEvent's data})
+   */
+  readonly nullableFieldName: TNullableFieldName
+}
+
+export interface StreamMakerOptionsWellknown {
+  /**
+   * A boolean value indicating that events of this type will be dispatched to
+   * the registered `listener` before being dispatched to any `EventTarget`
+   * beneath it in the DOM tree.
+   * @default false
+   */
+  readonly capture?: boolean
+
+  /**
+   * A boolean value indicating that the `listener` should be invoked at most
+   * once after being added. If `true`, the `listener` would be automatically
+   * removed when invoked.
+   * @default false
+   */
+  readonly passive?: boolean
+
+  /**
+   * A boolean value that, if true, indicates that the function specified by
+   * listener will never call `preventDefault()`. If a passive listener calls
+   * `preventDefault()`, nothing will happen and a console warning may be
+   * generated.
+   * @default false
+   */
+  readonly once?: boolean
+
+  /**
+   * How many elements sent by event target to buffer while waiting for the
+   * moment they are consumed. Can be limited to a certain number
+   * @default "unbounded"
+   */
+  readonly bufferSize?: number | 'unbounded' | undefined
+}
+
+export interface StreamMakerOptionsObject<
+  TOnNullStrategy extends OnNullStrategy,
+> extends StreamMakerOptionsWellknown {
+  /**
+   * A strategy to react when the MIDI-related event will have relevant field be
+   * null. Although there should be no sane scenario where it would be the case,
+   * it's still allowed by the spec, and for a better DevX this lib lets the dev
+   * make a decision on how to handle such cases.
+   *
+   * - `fail` will add an error into a signature of a stream, allowing the user
+   *   to handle it
+   * - `die` will throw a defect, which won't be reflected as a possible failure
+   *   in types. Selected by default. `undefined` is treated the same.
+   * - `ignore` will just silently remove such events from the stream
+   * - `passthrough` - will pass such events with an unmodified content of the
+   *   relevant field
+   *
+   * @default 'die'
+   */
+  readonly onExtremelyRareNullableField?: TOnNullStrategy
+}
+
+/**
+ * Passing a value of a `boolean` type is equivalent to setting
+ * `options.capture` property
+ */
+export type StreamMakerOptions<TOnNullStrategy extends OnNullStrategy> =
+  | boolean
+  | StreamMakerOptionsObject<TOnNullStrategy>
+  | undefined
+
+export type OnNullStrategy =
+  | (typeof validOnNullStrategies extends Set<infer U> ? U : never)
+  | undefined
+
+export type StreamValue<
+  TTag extends string,
+  TCameFrom,
+  TContainerWithNullableFields extends object,
+  TOnNullStrategy extends OnNullStrategy,
+> = {
+  readonly _tag: TTag
+  /**
+   * An effectful MIDI entity that wraps the raw MIDI object, which triggered an
+   * event
+   */
+  readonly cameFrom: TCameFrom
+  readonly capturedAt: Date
+} & (
+  | {
+      readonly [NullableField in keyof TContainerWithNullableFields]: Exclude<
+        TContainerWithNullableFields[NullableField],
+        null
+      >
+    }
+  | ([TOnNullStrategy] extends ['passthrough']
+      ? {
+          readonly [NullableField in keyof TContainerWithNullableFields]: null
+        }
+      : never)
+)
+
+export type StreamError<TOnNullStrategy extends OnNullStrategy, E> =
+  | E
+  | ([TOnNullStrategy] extends ['fail'] ? Cause.NoSuchElementException : never)
+
+export interface BuiltStream<
+  TTag extends string,
+  TCameFrom,
+  TContainerWithNullableFields extends object,
+  TOnNullStrategy extends OnNullStrategy,
+  E = never,
+  R = never,
+> extends Stream.Stream<
+    StreamValue<TTag, TCameFrom, TContainerWithNullableFields, TOnNullStrategy>,
+    StreamError<TOnNullStrategy, E>,
+    R
+  > {}
+
+export interface DualStreamMaker<
+  TCameFrom,
+  TTag extends string,
+  TContainerWithNullableFields extends object,
+> extends MakeStreamTargetFirst<TCameFrom, TTag, TContainerWithNullableFields>,
+    MakeStreamTargetLast<TCameFrom, TTag, TContainerWithNullableFields> {}
+
+export interface MakeStreamTargetFirst<
+  TCameFrom,
+  TTag extends string,
+  TContainerWithNullableFields extends object,
+> {
+  /**
+   * @param polymorphicEventTargetWrapper Raw MIDI object, which triggers
+   * events, wrapped in this lib's abstraction and potentially inside Effect.
+   * Will be assigned to the `cameFrom` property of the stream's success channel
+   * object
+   *
+   * @param options Passing a value of a `boolean` type is equivalent to setting
+   * `options.capture` property
+   */
+  <
+    E = never,
+    R = never,
+    const TOnNullStrategy extends OnNullStrategy = undefined,
+  >(
+    polymorphicEventTargetWrapper: Util.PolymorphicEffect<TCameFrom, E, R>,
+    options?: StreamMakerOptions<TOnNullStrategy>,
+  ): BuiltStream<
+    TTag,
+    TCameFrom,
+    TContainerWithNullableFields,
+    TOnNullStrategy,
+    E,
+    R
+  >
+}
+
+export interface MakeStreamTargetLast<
+  TCameFrom,
+  TTag extends string,
+  TContainerWithNullableFields extends object,
+> {
+  /**
+   * @param options Passing a value of a `boolean` type is equivalent to setting
+   * `options.capture` property
+   *
+   * **Second call argument**
+   *
+   * - `polymorphicEventTargetWrapper` Raw MIDI object, which triggers events,
+   *   wrapped in this lib's abstraction and potentially inside Effect. Will be
+   *   assigned to the `cameFrom` property of the stream's success channel
+   *   object
+   */
+  <const TOnNullStrategy extends OnNullStrategy = undefined>(
+    options?: StreamMakerOptions<TOnNullStrategy>,
+  ): {
+    /**
+     * @param polymorphicEventTargetWrapper Raw MIDI object, which triggers
+     * events, wrapped in this lib's abstraction and potentially inside Effect.
+     * Will be assigned to the `cameFrom` property of the stream's success
+     * channel object
+     */
+    <E = never, R = never>(
+      polymorphicEventTargetWrapper: Util.PolymorphicEffect<TCameFrom, E, R>,
+    ): BuiltStream<
+      TTag,
+      TCameFrom,
+      TContainerWithNullableFields,
+      TOnNullStrategy,
+      E,
+      R
+    >
+  }
+}

package/src/internal/errors.ts

@@ -0,0 +1,220 @@
+import * as Schema from 'effect/Schema'
+import type * as Types from 'effect/Types'
+import type * as EMIDIAccess from './EMIDIAccess.ts'
+import * as EMIDIPort from './EMIDIPort.ts'
+
+// NOTE: stacks are properly extracted from error instances into structs, while
+// decoding
+
+const PortId = Schema.fromBrand(EMIDIPort.BothId)(Schema.NonEmptyTrimmedString)
+
+const ErrorSchema = <TSchema extends Schema.Schema.Any | undefined = undefined>(
+  nameSchema?: TSchema,
+) =>
+  Schema.Struct({
+    name: (nameSchema ??
+      Schema.NonEmptyTrimmedString) as TSchema extends undefined
+      ? typeof Schema.NonEmptyTrimmedString
+      : TSchema,
+    message: Schema.NonEmptyTrimmedString,
+    stack: Schema.NonEmptyTrimmedString.pipe(
+      Schema.optionalWith({ exact: true }),
+    ),
+    cause: Schema.Unknown.pipe(Schema.optionalWith({ exact: true })),
+  })
+
+const midiAccessFailureFields = {
+  whileAskingForPermissions: Schema.Struct({
+    sysex: Schema.optional(Schema.Boolean),
+    software: Schema.optional(Schema.Boolean),
+  }),
+}
+
+/**
+ * Thrown if the document or page is going to be closed due to user navigation.
+ *
+ * Wraps `DOMException { name: 'AbortError' }`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#aborterror|Web IDL spec}
+ */
+export class AbortError extends Schema.TaggedError<AbortError>()('AbortError', {
+  cause: ErrorSchema(Schema.Literal('AbortError')),
+}) {}
+
+/**
+ * Thrown if the underlying system raises any errors when trying to open the
+ * port.
+ *
+ * Wraps `DOMException { name: 'InvalidStateError' }`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#invalidstateerror|Web IDL spec}
+ */
+export class UnderlyingSystemError extends Schema.TaggedError<UnderlyingSystemError>()(
+  'UnderlyingSystemError',
+  {
+    cause: ErrorSchema(Schema.Literal('InvalidStateError')),
+    ...midiAccessFailureFields,
+  },
+) {}
+
+/**
+ * Thrown if the MIDI API, or a certain configuration of it is not supported by
+ * the system.
+ *
+ * Wraps `ReferenceError | TypeError | DOMException { name: 'NotSupportedError' }`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#notsupportederror|Web IDL spec}
+ */
+export class MIDIAccessNotSupportedError extends Schema.TaggedError<MIDIAccessNotSupportedError>()(
+  'MIDIAccessNotSupportedError',
+  {
+    cause: ErrorSchema(
+      Schema.Literal('ReferenceError', 'TypeError', 'NotSupportedError'),
+    ),
+    ...midiAccessFailureFields,
+  },
+) {}
+
+/**
+ * Thrown on platforms where `.clear()` method of output ports is not supported
+ * (currently supported only in Firefox)
+ *
+ * Wraps `TypeError | DOMException { name: 'NotSupportedError' }`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#notsupportederror|Web IDL spec}
+ */
+export class ClearingSendingQueueIsNotSupportedError extends Schema.TaggedError<ClearingSendingQueueIsNotSupportedError>()(
+  'ClearingSendingQueueIsNotSupportedError',
+  {
+    cause: ErrorSchema(Schema.Literal('TypeError', 'NotSupportedError')),
+    portId: PortId,
+  },
+) {}
+
+/**
+ * Thrown when attempt to open the port failed because it is unavailable (e.g.
+ * is already in use by another process and cannot be opened, or is
+ * disconnected).
+ *
+ * Wraps `DOMException { name: 'InvalidAccessError' | 'NotAllowedError' | 'InvalidStateError' }`
+ *
+ * @see Web IDL specs: {@link https://webidl.spec.whatwg.org/#invalidaccesserror|InvalidAccessError}, {@link https://webidl.spec.whatwg.org/#notallowederror|NotAllowedError}, {@link https://webidl.spec.whatwg.org/#invalidstateerror|InvalidStateError}
+ */
+export class UnavailablePortError extends Schema.TaggedError<UnavailablePortError>()(
+  'UnavailablePortError',
+  {
+    cause: ErrorSchema(
+      Schema.Literal(
+        'InvalidAccessError',
+        'NotAllowedError',
+        'InvalidStateError',
+      ),
+    ),
+    portId: PortId,
+  },
+) {}
+
+/**
+ * Thrown when `.send` operation was called on a disconnected port.
+ *
+ * Wraps `DOMException { name: 'InvalidStateError' }`
+ *
+ * @see {@link https://webidl.spec.whatwg.org/#invalidaccesserror|Web IDL spec}
+ */
+export class DisconnectedPortError extends Schema.TaggedError<DisconnectedPortError>()(
+  'DisconnectedPortError',
+  {
+    cause: ErrorSchema(Schema.Literal('InvalidStateError')),
+    portId: PortId,
+  },
+) {}
+
+/**
+ * Thrown when trying to send system exclusive message from the access handle,
+ * that doesn't have this permission
+ *
+ * Wraps `DOMException { name: 'InvalidAccessError' | 'NotAllowedError' }`
+ *
+ * @see Web IDL specs: {@link https://webidl.spec.whatwg.org/#invalidaccesserror|InvalidAccessError}, {@link https://webidl.spec.whatwg.org/#notallowederror|NotAllowedError}
+ */
+export class CantSendSysexMessagesError extends Schema.TaggedError<CantSendSysexMessagesError>()(
+  'CantSendSysexMessagesError',
+  {
+    cause: ErrorSchema(Schema.Literal('InvalidAccessError', 'NotAllowedError')),
+    portId: PortId,
+  },
+) {}
+
+/**
+ * Thrown if the user, the system or their security settings denied the
+ * application from creating an {@linkcode EMIDIAccess.EMIDIAccessInstance} object
+ * with the requested {@linkcode EMIDIAccess.RequestMIDIAccessOptions|options}, or if the
+ * document is not allowed to use the feature (for example, because of a
+ * Permission Policy, or because the user previously denied a permission
+ * request).
+ *
+ * Wraps `DOMException { name: 'NotAllowedError' | 'SecurityError' }`
+ *
+ * @see Web IDL specs: {@link https://webidl.spec.whatwg.org/#notallowederror|NotAllowedError}, {@link https://webidl.spec.whatwg.org/#securityerror|SecurityError}
+ */
+export class MIDIAccessNotAllowedError extends Schema.TaggedError<MIDIAccessNotAllowedError>()(
+  'MIDIAccessNotAllowedError',
+  {
+    cause: ErrorSchema(Schema.Literal('NotAllowedError', 'SecurityError')),
+    ...midiAccessFailureFields,
+  },
+) {}
+
+/**
+ * Thrown when data to be sent is not a valid sequence or does not contain a
+ * valid MIDI message
+ *
+ * Wraps `TypeError`
+ */
+export class MalformedMidiMessageError extends Schema.TaggedError<MalformedMidiMessageError>()(
+  'MalformedMidiMessageError',
+  {
+    cause: ErrorSchema(Schema.Literal('TypeError')),
+    portId: PortId,
+    midiMessage: Schema.Array(Schema.Int),
+  },
+) {}
+
+/**
+ * Keep in mind that if port isn't found, it might not mean it's disconnected.
+ * For example, virtual ports created by software won't show up in the list of
+ * available inputs/outputs of MIDI Access handle with disabled
+ * {@linkcode EMIDIAccess.RequestMIDIAccessOptions.software} flag.
+ */
+export class PortNotFoundError extends Schema.TaggedError<PortNotFoundError>()(
+  'PortNotFound',
+  { portId: PortId },
+) {}
+
+/**
+ *
+ * @internal
+ */
+export const remapErrorByName =
+  // biome-ignore lint/suspicious/noExplicitAny: I don't care
+    <TErrorClassUnion extends new (arg: any) => Error>(
+      map: { [name: string]: TErrorClassUnion },
+      absurdMessage: string,
+      rest: Omit<
+        Types.UnionToIntersection<
+          // biome-ignore lint/suspicious/noExplicitAny: I don't care
+          TErrorClassUnion extends new (arg: infer P) => any ? P : never
+        >,
+        'cause'
+      >,
+    ) =>
+    (cause: unknown) => {
+      if (!(cause instanceof Error && cause.name in map))
+        throw new Error(absurdMessage)
+      // biome-ignore lint/style/noNonNullAssertion: Because we checked it above with `cause.name in map`
+      const Class = map[cause.name]!
+      return new Class({
+        cause,
+        ...rest,
+      }) as InstanceType<TErrorClassUnion>
+    }