effect-web-midi 0.2.3

package/src/internal/EMIDIInput.ts

@@ -0,0 +1,114 @@
+import * as Brand from 'effect/Brand'
+
+import * as EMIDIPort from './EMIDIPort.ts'
+import * as StreamMaker from './StreamMaker.ts'
+import * as Util from './Util.ts'
+
+// TODO: implement scoping of midi access that will clean up all message queues
+// and streams, and remove listeners
+
+// TODO: implement scope inheritance
+
+/**
+ * Thin wrapper around {@linkcode MIDIInput} instance. Will be seen in all
+ * external code.
+ */
+export interface EMIDIInput extends EMIDIPort.EMIDIPort<'input'> {}
+
+/**
+ * Thin wrapper around {@linkcode MIDIInput} instance giving access to the
+ * actual field storing it.
+ * @internal
+ */
+interface EMIDIInputImpl extends EMIDIPort.EMIDIPortImpl<MIDIInput, 'input'> {}
+
+/**
+ * Validates the raw MIDI input port, and puts it into a field hidden from the
+ * client's code
+ *
+ * @internal
+ */
+const makeImpl = (rawInput: MIDIInput): EMIDIInputImpl =>
+  EMIDIPort.makeImpl(rawInput, 'input', globalThis.MIDIInput)
+
+/**
+ * Asserts an object to be valid EMIDIInput and casts it to internal
+ * implementation type
+ *
+ * @internal
+ */
+const assertImpl = (input: unknown) => {
+  if (!isImpl(input)) throw new Error('Failed to cast to EMIDIInputImpl')
+  return input
+}
+
+/**
+ * Asserts an object to be valid EMIDIInput
+ */
+export const assert: (input: unknown) => EMIDIInput = assertImpl
+
+/**
+ * @internal
+ */
+const assumeImpl = (input: EMIDIInput) => input as EMIDIInputImpl
+
+/**
+ *
+ *
+ * @internal
+ */
+export const make: (rawInput: MIDIInput) => EMIDIInput = makeImpl
+
+/**
+ *
+ *
+ * @internal
+ */
+const isImpl: (input: unknown) => input is EMIDIInputImpl =
+  EMIDIPort.isImplOfSpecificType('input', globalThis.MIDIInput)
+
+/**
+ *
+ *
+ */
+export const is: (input: unknown) => input is EMIDIInput = isImpl
+
+/**
+ * [MIDIMessageEvent MDN
+ * Reference](https://developer.mozilla.org/docs/Web/API/MIDIMessageEvent)
+ *
+ * MIDI spec says that synthetically built `MIDIMessageEvent`s can have `data`
+ * field equal to `null`, but when coming from the browser, they won't. The
+ * default behavior is to defect on `null`.
+ */
+export const makeMessagesStreamByPort =
+  StreamMaker.createStreamMakerFrom<MIDIInputEventMap>()(
+    is,
+    input => ({
+      tag: 'MIDIMessage',
+      eventListener: { target: assumeImpl(input)._port, type: 'midimessage' },
+      spanAttributes: {
+        spanTargetName: 'MIDI port',
+        port: Util.getStaticMIDIPortInfo(input),
+      },
+      nullableFieldName: 'data',
+    }),
+    midiMessage => ({ midiMessage }),
+  )
+
+/**
+ *
+ *
+ */
+export type PolymorphicInput<E, R> = EMIDIPort.PolymorphicPort<E, R, 'input'>
+
+/**
+ *
+ *
+ */
+export type PolymorphicInputClean = EMIDIPort.PolymorphicPortClean<'input'>
+
+export type Id = EMIDIPort.Id<'input'>
+export const Id = Brand.nominal<Id>()
+
+export interface InputIdToInstanceMap extends Record<Id, EMIDIInput> {}

package/src/internal/EMIDIOutput.ts

@@ -0,0 +1,231 @@
+/** biome-ignore-all lint/style/useShorthandFunctionType: It's a nice way to
+ * preserve JSDoc comments attached to the function signature */
+
+import * as Brand from 'effect/Brand'
+import * as Effect from 'effect/Effect'
+import * as EFunction from 'effect/Function'
+
+import * as EMIDIPort from './EMIDIPort.ts'
+import * as MIDIErrors from './MIDIErrors.ts'
+import * as Util from './Util.ts'
+
+/**
+ * Thin wrapper around {@linkcode MIDIOutput} instance. Will be seen in all
+ * external code.
+ */
+export interface EMIDIOutput extends EMIDIPort.EMIDIPort<'output'> {}
+
+/**
+ * Thin wrapper around {@linkcode MIDIOutput} instance giving access to the
+ * actual field storing it.
+ * @internal
+ */
+interface EMIDIOutputImpl
+  extends EMIDIPort.EMIDIPortImpl<MIDIOutput, 'output'> {}
+
+/**
+ * Validates the raw MIDI output port, and puts it into a field hidden from the
+ * client's code
+ *
+ * @internal
+ */
+const makeImpl = (rawOutput: MIDIOutput): EMIDIOutputImpl =>
+  EMIDIPort.makeImpl(rawOutput, 'output', globalThis.MIDIOutput)
+
+/**
+ * Asserts an object to be valid EMIDIOutput and casts it to
+ * internal implementation type
+ *
+ * @internal
+ */
+const assertImpl = (output: unknown) => {
+  if (!isImpl(output))
+    throw new Error('Assertion failed: Not a EMIDIOutputImpl')
+  return output
+}
+
+/**
+ * Asserts an object to be valid EMIDIOutput
+ */
+export const assert: (output: unknown) => EMIDIOutput = assertImpl
+
+/**
+ * Casts
+ * @internal
+ */
+const assumeImpl = (output: EMIDIOutput) => output as EMIDIOutputImpl
+
+/**
+ *
+ * @internal
+ */
+export const make: (rawOutput: MIDIOutput) => EMIDIOutput = makeImpl
+
+/**
+ *
+ * @internal
+ */
+const isImpl = EMIDIPort.isImplOfSpecificType('output', globalThis.MIDIOutput)
+
+/**
+ *
+ */
+export const is: (output: unknown) => output is EMIDIOutput = isImpl
+
+/**
+ *
+ *
+ * @internal
+ */
+const simplify = <E = never, R = never>(
+  polymorphicPort: PolymorphicOutput<E, R>,
+) => Util.fromPolymorphic(polymorphicPort, is)
+
+/**
+ * If `midiMessage` is a System Exclusive message, and the `MIDIAccess` did not
+ * enable System Exclusive access, an `InvalidAccessError` exception will be
+ * thrown
+ *
+ * If the port is `"connected"` and the connection is `"closed"`, asynchronously
+ * tries to open the port. It's unclear in the spec if potential error of `open`
+ * call would result in an `InvalidAccessError` error coming from the `send`
+ * method itself.
+ *
+ * @returns An effect with the same port for easier chaining of operations
+ */
+export const send: DualSendMIDIMessageFromPort = EFunction.dual<
+  SendMIDIMessagePortLast,
+  SendMIDIMessagePortFirst
+>(
+  Util.polymorphicCheckInDual(is),
+  Effect.fn('EMIDIOutput.send')(
+    function* (polymorphicOutput, midiMessage, timestamp) {
+      const output = yield* simplify(polymorphicOutput)
+
+      yield* Effect.annotateCurrentSpan({
+        midiMessage,
+        timestamp,
+        port: Util.getStaticMIDIPortInfo(output),
+      })
+
+      yield* Effect.try({
+        try: () => assumeImpl(output)._port.send(midiMessage, timestamp),
+        catch: MIDIErrors.remapErrorByName(
+          {
+            NotAllowedError: MIDIErrors.CannotSendSysexMessageError,
+            // InvalidAccessError is kept for compatibility reason
+            // (https://github.com/WebAudio/web-midi-api/pull/278):
+            InvalidAccessError: MIDIErrors.CannotSendSysexMessageError,
+
+            InvalidStateError: MIDIErrors.CannotSendToDisconnectedPortError,
+            TypeError: MIDIErrors.MalformedMIDIMessageError,
+          },
+          'EMIDIOutput.send error handling absurd',
+          { portId: output.id, midiMessage: [...midiMessage] },
+        ),
+      })
+
+      return output as EMIDIOutput
+    },
+  ),
+)
+
+/**
+ * Clears any enqueued send data that has not yet been sent from the
+ * `MIDIOutput`'s queue. The browser will ensure the MIDI stream is left in a
+ * good state, and if the output port is in the middle of a sysex message, a
+ * sysex termination byte (`0xf7`) will be sent.
+ *
+ * @param polymorphicOutput An effectful output port
+ *
+ * @returns An effect with the same port for easier chaining of operations
+ * @experimental Supported only in Firefox. {@link https://caniuse.com/mdn-api_midioutput_clear|Can I use - MIDIOutput API: clear}
+ * @see {@link https://www.w3.org/TR/webmidi/#dom-midioutput-clear|Web MIDI spec}, {@link https://developer.mozilla.org/en-US/docs/Web/API/MIDIOutput/clear|MDN reference}
+ */
+export const clear = Effect.fn('EMIDIOutput.clear')(function* <
+  E = never,
+  R = never,
+>(polymorphicOutput: PolymorphicOutput<E, R>) {
+  const output = yield* simplify(polymorphicOutput)
+
+  yield* Effect.annotateCurrentSpan({
+    port: Util.getStaticMIDIPortInfo(output),
+  })
+
+  yield* Effect.try({
+    // @ts-expect-error even though `.clear` is in spec, the API is not
+    // supported in at least 2 major browsers, hence doesn't meet the condition
+    // to be included into TS's DOM types
+    try: () => assumeImpl(output)._port.clear(),
+    catch: MIDIErrors.remapErrorByName(
+      {
+        // TODO: test this
+        // most likely it would be something like `TypeError: Undefined is not a function`
+        TypeError: MIDIErrors.ClearingSendingQueueIsNotSupportedError,
+        NotSupportedError: MIDIErrors.ClearingSendingQueueIsNotSupportedError,
+      },
+      'EMIDIOutput.clear error handling absurd',
+      { portId: output.id },
+    ),
+  })
+
+  return output
+})
+
+/**
+ *
+ *
+ */
+export type PolymorphicOutput<E, R> = EMIDIPort.PolymorphicPort<E, R, 'output'>
+
+/**
+ *
+ *
+ */
+export type PolymorphicOutputClean = EMIDIPort.PolymorphicPortClean<'output'>
+
+export type SendFromPortArgs = [
+  midiMessage: Iterable<number>,
+  timestamp?: DOMHighResTimeStamp,
+]
+
+export interface DualSendMIDIMessageFromPort
+  extends SendMIDIMessagePortLast,
+    SendMIDIMessagePortFirst {}
+
+export interface SendMIDIMessagePortLast {
+  /**
+   *
+   */
+  (
+    ...args: SendFromPortArgs
+  ): {
+    /**
+     *
+     */
+    <E = never, R = never>(
+      polymorphicOutput: PolymorphicOutput<E, R>,
+    ): SentMessageEffectFromPort<E, R>
+  }
+}
+
+export interface SendMIDIMessagePortFirst {
+  /**
+   *
+   */
+  <E = never, R = never>(
+    polymorphicOutput: PolymorphicOutput<E, R>,
+    ...args: SendFromPortArgs
+  ): SentMessageEffectFromPort<E, R>
+}
+
+/**
+ *
+ */
+export interface SentMessageEffectFromPort<E = never, R = never>
+  extends Util.SentMessageEffectFrom<EMIDIOutput, E, R> {}
+
+export type Id = EMIDIPort.Id<'output'>
+export const Id = Brand.nominal<Id>()
+
+export interface OutputIdToInstanceMap extends Record<Id, EMIDIOutput> {}

package/src/internal/EMIDIPort.ts

@@ -0,0 +1,239 @@
+/** biome-ignore-all lint/style/useShorthandFunctionType: It's a nice way to
+ * preserve JSDoc comments attached to the function signature */
+
+import * as Brand from 'effect/Brand'
+import * as Equal from 'effect/Equal'
+import * as Hash from 'effect/Hash'
+import * as Inspectable from 'effect/Inspectable'
+import * as Pipeable from 'effect/Pipeable'
+
+import type * as EMIDIInput from './EMIDIInput.ts'
+import type * as EMIDIOutput from './EMIDIOutput.ts'
+import type * as Util from './Util.ts'
+
+/**
+ * Unique symbol used for distinguishing {@linkcode EMIDIPort} instances
+ * from other objects at both runtime and type-level
+ * @internal
+ */
+const TypeId: unique symbol = Symbol.for('effect-web-midi/EMIDIPort')
+
+/**
+ * Unique symbol used for distinguishing {@linkcode EMIDIPort} instances
+ * from other objects at both runtime and type-level
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * Prototype of all {@linkcode EMIDIPort} instances
+ * @internal
+ */
+const CommonProto = {
+  _tag: 'EMIDIPort' as const,
+
+  [TypeId]: TypeId,
+
+  [Hash.symbol]() {
+    return Hash.string(this.id)
+  },
+
+  [Equal.symbol](that: Equal.Equal) {
+    return 'id' in that && this.id === that.id
+  },
+
+  pipe() {
+    // biome-ignore lint/complexity/noArguments: Effect's tradition
+    return Pipeable.pipeArguments(this, arguments)
+  },
+
+  toString() {
+    return Inspectable.format(this.toJSON())
+  },
+
+  toJSON() {
+    return {
+      _id: 'EMIDIPort',
+      id: this.id,
+      name: this.name,
+      manufacturer: this.manufacturer,
+      version: this.version,
+      type: this.type,
+    }
+  },
+
+  [Inspectable.NodeInspectSymbol]() {
+    return this.toJSON()
+  },
+
+  get id() {
+    return BothId(assumeImpl(this)._port.id)
+  },
+  get name() {
+    return assumeImpl(this)._port.name
+  },
+  get manufacturer() {
+    return assumeImpl(this)._port.manufacturer
+  },
+  get version() {
+    return assumeImpl(this)._port.version
+  },
+  get type() {
+    return assumeImpl(this)._port.type
+  },
+} satisfies EMIDIPort
+
+/**
+ * Thin wrapper around {@linkcode MIDIPort} instance. Will be seen in all
+ * external code.
+ */
+export interface EMIDIPort<TMIDIPortType extends MIDIPortType = MIDIPortType>
+  extends Equal.Equal,
+    Pipeable.Pipeable,
+    Inspectable.Inspectable,
+    Pick<MIDIPort, 'version' | 'name' | 'manufacturer'> {
+  /**
+   * The **`id`** read-only property of the MIDIPort interface returns the unique ID of the port.
+   *
+   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MIDIPort/id)
+   */
+  readonly id: Id<TMIDIPortType>
+  readonly [TypeId]: TypeId
+  readonly _tag: 'EMIDIPort'
+  readonly type: TMIDIPortType
+}
+
+/**
+ * Thin wrapper around {@linkcode MIDIPort} instance giving access to the
+ * actual field storing it.
+ * @internal
+ */
+export interface EMIDIPortImpl<
+  TPort extends MIDIPort = MIDIPort,
+  TPortType extends MIDIPortType = MIDIPortType,
+> extends EMIDIPort<TPortType> {
+  readonly _port: TPort
+}
+
+/**
+ *
+ *
+ * @internal
+ */
+export const makeImpl = <
+  TPort extends MIDIPort,
+  TPortType extends MIDIPortType,
+>(
+  port: NoInfer<TPort>,
+  type: TPortType,
+  ClassToAssertInheritance: new (...args: unknown[]) => TPort,
+): EMIDIPortImpl<TPort, TPortType> => {
+  if (port.type !== type || !(port instanceof ClassToAssertInheritance))
+    throw new Error(`EMIDIPort constructor accepts only ${type} ports`)
+
+  const instance = Object.create(CommonProto)
+  instance._port = port
+  return instance
+}
+
+/**
+ * Asserts an object to be valid EMIDIPort and casts it to internal
+ * implementation type
+ *
+ * @internal
+ */
+const assertImpl = (port: unknown) => {
+  if (!isGeneralImpl(port)) throw new Error('Failed to cast to EMIDIPort')
+  return port
+}
+
+/**
+ * Asserts an object to be valid EMIDIPort
+ */
+export const assert: (port: unknown) => EMIDIPort = assertImpl
+
+/**
+ * @internal
+ */
+export const assumeImpl = (port: EMIDIPort) => port as EMIDIPortImpl
+
+/**
+ *
+ *
+ * @internal
+ */
+const isGeneralImpl = (port: unknown): port is EMIDIPortImpl =>
+  typeof port === 'object' &&
+  port !== null &&
+  Object.getPrototypeOf(port) === CommonProto &&
+  TypeId in port &&
+  'type' in port &&
+  '_port' in port &&
+  typeof port._port === 'object' &&
+  port._port instanceof MIDIPort
+
+/**
+ *
+ *
+ */
+export type PolymorphicPort<
+  E,
+  R,
+  TMIDIPortType extends MIDIPortType = MIDIPortType,
+> = Util.PolymorphicEffect<EMIDIPort<TMIDIPortType>, E, R>
+
+/**
+ *
+ *
+ */
+export type PolymorphicPortClean<
+  TMIDIPortType extends MIDIPortType = MIDIPortType,
+> = PolymorphicPort<never, never, TMIDIPortType>
+
+export type ExtractTypeFromPort<TPort extends EMIDIPort> =
+  TPort extends EMIDIPort<infer TPortType> ? TPortType : never
+
+/**
+ *
+ *
+ * @internal
+ */
+export const isImplOfSpecificType =
+  <const TPortType extends MIDIPortType, TPort extends MIDIPort>(
+    type: TPortType,
+    ClassToAssertInheritance: new (...args: unknown[]) => TPort,
+  ) =>
+  (port: unknown): port is EMIDIPortImpl<TPort, TPortType> => {
+    if (!ClassToAssertInheritance)
+      throw new Error(
+        'Called in a context where ClassToAssertInheritance is falsy, probably on a platform where MIDI APIs are not supported, like node.js or bun',
+      )
+
+    return (
+      isGeneralImpl(port) &&
+      port.type === type &&
+      port._port instanceof ClassToAssertInheritance
+    )
+  }
+
+/**
+ *
+ *
+ */
+export const is: (port: unknown) => port is EMIDIPort = isGeneralImpl
+
+/**
+ * Unique identifier of the MIDI port.
+ *
+ * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MIDIPort/id)
+ */
+export type Id<TPortType extends MIDIPortType> =
+  // for distribution
+  TPortType extends MIDIPortType
+    ? Brand.Branded<string, 'MIDIPortId'> & Brand.Brand<TPortType>
+    : never
+
+export type BothId = Id<MIDIPortType>
+export const BothId = Brand.nominal<BothId>()
+
+export type BothIdToBothInstanceMap = EMIDIInput.InputIdToInstanceMap &
+  EMIDIOutput.OutputIdToInstanceMap