acrylblends 0.2.0 → 0.4.0

package/plugins/acryl-router/src/core/utils/stream.test.ts

@@ -0,0 +1,212 @@
+import { StreamingApi } from './stream.ts'
+
+describe('StreamingApi', () => {
+  it('write(string)', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+    api.write('foo')
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('foo'))
+    api.write('bar')
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('bar'))
+  })
+
+  it('write(Uint8Array)', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+    api.write(new Uint8Array([1, 2, 3]))
+    expect((await reader.read()).value).toEqual(new Uint8Array([1, 2, 3]))
+    api.write(new Uint8Array([4, 5, 6]))
+    expect((await reader.read()).value).toEqual(new Uint8Array([4, 5, 6]))
+  })
+
+  it('writeln(string)', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+    api.writeln('foo')
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('foo\n'))
+    api.writeln('bar')
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('bar\n'))
+  })
+
+  it('pipe()', async () => {
+    const { readable: senderReadable, writable: senderWritable } = new TransformStream()
+
+    // send data to readable in other scope
+    ;(async () => {
+      const writer = senderWritable.getWriter()
+      await writer.write(new TextEncoder().encode('foo'))
+      await writer.write(new TextEncoder().encode('bar'))
+      // await writer.close()
+    })()
+
+    const { readable: receiverReadable, writable: receiverWritable } = new TransformStream()
+
+    const api = new StreamingApi(receiverWritable, receiverReadable)
+
+    // pipe readable to api in other scope
+    ;(async () => {
+      await api.pipe(senderReadable)
+    })()
+
+    // read data from api
+    const reader = api.responseReadable.getReader()
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('foo'))
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('bar'))
+  })
+
+  it('pipe() re-acquires writer lock when pipeTo() throws', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+
+    const erroringReadable = new ReadableStream({
+      start(controller) {
+        controller.error(new Error('upstream error'))
+      },
+    })
+
+    await expect(api.pipe(erroringReadable)).rejects.toThrow('upstream error')
+    api.write('after pipe')
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('after pipe'))
+  })
+
+  it('pipe() can be called again after a previous pipe() throws', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+
+    const erroringReadable = new ReadableStream({
+      start(controller) {
+        controller.error(new Error('upstream error'))
+      },
+    })
+    await expect(api.pipe(erroringReadable)).rejects.toThrow('upstream error')
+
+    const src = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('second pipe'))
+        controller.close()
+      },
+    })
+    await api.pipe(src)
+    expect((await reader.read()).value).toEqual(new TextEncoder().encode('second pipe'))
+  })
+
+  it('close()', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const reader = api.responseReadable.getReader()
+    await api.close()
+    expect((await reader.read()).done).toBe(true)
+  })
+
+  it('should not throw an error in write()', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    await api.close()
+    const write = () => api.write('foo')
+    expect(write).not.toThrow()
+  })
+
+  it('should not throw an error in close()', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const close = async () => {
+      await api.close()
+      await api.close()
+    }
+    expect(close).not.toThrow()
+  })
+
+  it('onAbort()', async () => {
+    const { readable, writable } = new TransformStream()
+    const handleAbort1 = vi.fn()
+    const handleAbort2 = vi.fn()
+    const api = new StreamingApi(writable, readable)
+    api.onAbort(handleAbort1)
+    api.onAbort(handleAbort2)
+    expect(handleAbort1).not.toBeCalled()
+    expect(handleAbort2).not.toBeCalled()
+    await api.responseReadable.cancel()
+    expect(handleAbort1).toBeCalled()
+    expect(handleAbort2).toBeCalled()
+  })
+
+  it('abort()', async () => {
+    const { readable, writable } = new TransformStream()
+    const handleAbort1 = vi.fn()
+    const handleAbort2 = vi.fn()
+    const api = new StreamingApi(writable, readable)
+    api.onAbort(handleAbort1)
+    api.onAbort(handleAbort2)
+    expect(handleAbort1).not.toBeCalled()
+    expect(handleAbort2).not.toBeCalled()
+    expect(api.aborted).toBe(false)
+
+    api.abort()
+    expect(handleAbort1).toHaveBeenCalledOnce()
+    expect(handleAbort2).toHaveBeenCalledOnce()
+    expect(api.aborted).toBe(true)
+
+    api.abort()
+    expect(handleAbort1).toHaveBeenCalledOnce()
+    expect(handleAbort2).toHaveBeenCalledOnce()
+    expect(api.aborted).toBe(true)
+  })
+
+  it('abort() continues when an abort listener throws', async () => {
+    const { readable, writable } = new TransformStream()
+    const handleAbort = vi.fn()
+    const api = new StreamingApi(writable, readable)
+    api.onAbort(() => {
+      throw new Error('cleanup failed')
+    })
+    api.onAbort(handleAbort)
+    api.abort()
+    expect(api.aborted).toBe(true)
+    expect(handleAbort).toHaveBeenCalledOnce()
+  })
+
+  it('abort() handles a rejecting thenable returned by a listener', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const unhandled = vi.fn()
+    process.on('unhandledRejection', unhandled)
+    try {
+      api.onAbort(
+        () =>
+          ({
+            then: (_resolve: unknown, reject: (reason: unknown) => void) =>
+              reject(new Error('thenable cleanup failed')),
+          }) as unknown as Promise<void>
+      )
+      api.abort()
+      expect(api.aborted).toBe(true)
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      expect(unhandled).not.toHaveBeenCalled()
+    } finally {
+      process.off('unhandledRejection', unhandled)
+    }
+  })
+
+  it('abort() does not leave an unhandled rejection when an async listener rejects', async () => {
+    const { readable, writable } = new TransformStream()
+    const api = new StreamingApi(writable, readable)
+    const unhandled = vi.fn()
+    process.on('unhandledRejection', unhandled)
+    try {
+      api.onAbort(async () => {
+        throw new Error('async cleanup failed')
+      })
+      api.abort()
+      expect(api.aborted).toBe(true)
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      expect(unhandled).not.toHaveBeenCalled()
+    } finally {
+      process.off('unhandledRejection', unhandled)
+    }
+  })
+})

package/plugins/acryl-router/src/core/utils/stream.ts

@@ -0,0 +1,107 @@
+/**
+ * @module
+ * Stream utility.
+ */
+
+export class StreamingApi {
+  private writer: WritableStreamDefaultWriter<Uint8Array>
+  private encoder: TextEncoder
+  private writable: WritableStream
+  private abortSubscribers: (() => void | Promise<void>)[] = []
+  responseReadable: ReadableStream
+  /**
+   * Whether the stream has been aborted.
+   */
+  aborted: boolean = false
+  /**
+   * Whether the stream has been closed normally.
+   */
+  closed: boolean = false
+
+  constructor(writable: WritableStream, _readable: ReadableStream) {
+    this.writable = writable
+    this.writer = writable.getWriter()
+    this.encoder = new TextEncoder()
+
+    const reader = _readable.getReader()
+
+    // in case the user disconnects, let the reader know to cancel
+    // this in-turn results in responseReadable being closed
+    // and writeSSE method no longer blocks indefinitely
+    this.abortSubscribers.push(async () => {
+      await reader.cancel()
+    })
+
+    this.responseReadable = new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await reader.read()
+        done ? controller.close() : controller.enqueue(value)
+      },
+      cancel: () => {
+        if (!this.closed) {
+          this.abort()
+        }
+      },
+    })
+  }
+
+  async write(input: Uint8Array | string): Promise<StreamingApi> {
+    try {
+      if (typeof input === 'string') {
+        input = this.encoder.encode(input)
+      }
+      await this.writer.write(input)
+    } catch {
+      // Do nothing. If you want to handle errors, create a stream by yourself.
+    }
+    return this
+  }
+
+  async writeln(input: string): Promise<StreamingApi> {
+    await this.write(input + '\n')
+    return this
+  }
+
+  sleep(ms: number): Promise<unknown> {
+    return new Promise((res) => setTimeout(res, ms))
+  }
+
+  async close() {
+    this.closed = true
+    try {
+      await this.writer.close()
+    } catch {
+      // Do nothing. If you want to handle errors, create a stream by yourself.
+    }
+  }
+
+  async pipe(body: ReadableStream) {
+    this.writer.releaseLock()
+    try {
+      await body.pipeTo(this.writable, { preventClose: true, preventAbort: true })
+    } finally {
+      this.writer = this.writable.getWriter()
+    }
+  }
+
+  onAbort(listener: () => void | Promise<void>) {
+    this.abortSubscribers.push(listener)
+  }
+
+  /**
+   * Abort the stream.
+   * You can call this method when stream is aborted by external event.
+   */
+  abort() {
+    if (!this.aborted) {
+      this.aborted = true
+      this.abortSubscribers.forEach((subscriber) => {
+        try {
+          void Promise.resolve(subscriber()).catch(() => {})
+        } catch {
+          // Ignore synchronous listener errors.
+        }
+      })
+    }
+  }
+}

package/plugins/acryl-router/src/core/utils/types.test.ts

@@ -0,0 +1,295 @@
+import type { JSONParsed, JSONValue } from './types.ts'
+
+describe('JSONParsed', () => {
+  const SampleEnum = {
+  Value1: 'value1',
+  Value2: 'value2',
+} as const
+type SampleEnum = (typeof SampleEnum)[keyof typeof SampleEnum]
+
+  interface Meta {
+    metadata: {
+      href: string
+      sampleEnum: SampleEnum
+    }
+  }
+
+  interface SampleInterface {
+    someMeta: Meta
+  }
+
+  type SampleType = {
+    someMeta: Meta
+  }
+
+  describe('primitives', () => {
+    it('should convert number type to number', () => {
+      type Actual = JSONParsed<number>
+      type Expected = number
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert string type to string', () => {
+      type Actual = JSONParsed<string>
+      type Expected = string
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert boolean type to boolean', () => {
+      type Actual = JSONParsed<boolean>
+      type Expected = boolean
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert null type to null', () => {
+      type Actual = JSONParsed<null>
+      type Expected = null
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('toJSON', () => {
+    it('should convert { toJSON() => T } to T', () => {
+      type Actual = JSONParsed<{ toJSON(): number }>
+      type Expected = number
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('toJSON is not called recursively', () => {
+      type Actual = JSONParsed<{ toJSON(): { toJSON(): number } }>
+      type Expected = {}
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert { a: { toJSON() => T } } to { a: T }', () => {
+      type Actual = JSONParsed<{ a: { toJSON(): number } }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert invalid type with { toJSON() => T to T', () => {
+      type Actual = JSONParsed<bigint & { toJSON(): string }>
+      type Expected = string
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('invalid types', () => {
+    it('should convert undefined type to never', () => {
+      type Actual = JSONParsed<undefined>
+      type Expected = never
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert symbol type to never', () => {
+      type Actual = JSONParsed<symbol>
+      type Expected = never
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert function type to never', () => {
+      type Actual = JSONParsed<() => void>
+      type Expected = never
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert bigint type to never', () => {
+      type Actual = JSONParsed<bigint>
+      type Expected = never
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('array', () => {
+    it('should convert undefined[] type to null[]', () => {
+      type Actual = JSONParsed<undefined[]>
+      type Expected = null[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert Function[] type to null[]', () => {
+      type Actual = JSONParsed<(() => void)[]>
+      type Expected = null[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert symbol[] type to null[]', () => {
+      type Actual = JSONParsed<symbol[]>
+      type Expected = null[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert (T | undefined)[] type to JSONParsedT | null>[]', () => {
+      type Actual = JSONParsed<(number | undefined)[]>
+      type Expected = (number | null)[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert { key: readonly T[]} correctly', () => {
+      type Actual = JSONParsed<{ key: readonly number[] }>
+      type Expected = { key: readonly number[] }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert T[] with additional properties to T[]', () => {
+      type Actual = JSONParsed<{ foo: 'bar' }[] & { meta: 'v1' }>
+      type Expected = { foo: 'bar' }[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert elements of T[] with additional properties', () => {
+      type Actual = JSONParsed<(number | undefined)[] & { meta: 'v1' }>
+      type Expected = (number | null)[]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('tuple', () => {
+    it('should convert [T, S] type to [T, S]', () => {
+      type Actual = JSONParsed<[number, string]>
+      type Expected = [number, string]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert [T, undefined] type to [T, null]', () => {
+      type Actual = JSONParsed<[number, undefined]>
+      type Expected = [number, null]
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('object', () => {
+    it('should omit keys with undefined value', () => {
+      type Actual = JSONParsed<{ a: number; b: undefined }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should omit keys with symbol value', () => {
+      type Actual = JSONParsed<{ a: number; b: symbol }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should omit keys with function value', () => {
+      type Actual = JSONParsed<{ a: number; b: () => void }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should omit symbol keys', () => {
+      type Actual = JSONParsed<{ a: number; [x: symbol]: number }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert T | undefined to T | undefined', () => {
+      type Actual = JSONParsed<{ a: number; b: number | undefined }>
+      type Expected = { a: number; b: number | undefined }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should omit keys with invalid union', () => {
+      type Actual = JSONParsed<{ a: number; b: undefined | symbol }>
+      type Expected = { a: number }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('unknown', () => {
+    it('should convert unknown type to unknown', () => {
+      type Actual = JSONParsed<unknown>
+      type Expected = JSONValue
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+
+    it('Should convert unknown value to JSONValue', () => {
+      type Actual = JSONParsed<{ value: unknown }>
+      type Expected = { value: JSONValue }
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  describe('Set/Map', () => {
+    it('should convert Set to empty object', () => {
+      type Actual = JSONParsed<Set<number>>
+      type Expected = {}
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+    it('should convert Map to empty object', () => {
+      type Actual = JSONParsed<Map<number, number>>
+      type Expected = {}
+      expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+    })
+  })
+
+  it('Should parse a complex type', () => {
+    const sample: JSONParsed<SampleType> = {
+      someMeta: {
+        metadata: {
+          href: '',
+          sampleEnum: SampleEnum.Value1,
+        },
+      },
+    }
+    expectTypeOf(sample).toEqualTypeOf<SampleType>()
+  })
+
+  it('Should parse a complex interface', () => {
+    const sample: JSONParsed<SampleInterface> = {
+      someMeta: {
+        metadata: {
+          href: '',
+          sampleEnum: SampleEnum.Value1,
+        },
+      },
+    }
+    expectTypeOf(sample).toEqualTypeOf<SampleInterface>()
+  })
+
+  it('Should convert Date to string', () => {
+    type Post = {
+      datetime: Date
+    }
+    type Expected = {
+      datetime: string
+    }
+    type Actual = JSONParsed<Post>
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+
+  it('Should convert bigint to never', () => {
+    type Post = {
+      num: bigint
+    }
+    type Expected = never
+    type Actual = JSONParsed<Post>
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+
+  it('Should convert bigint when TError is provided', () => {
+    type Post = {
+      num: bigint
+    }
+    type Expected = {
+      num: JSONValue
+    }
+    type Actual = JSONParsed<Post, never>
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+
+  it('Should convert bigint[] to never', () => {
+    type Post = {
+      nums: bigint[]
+    }
+    type Expected = never
+    type Actual = JSONParsed<Post>
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+
+  it('Should convert bigint[] when TError is provided', () => {
+    type Post = {
+      num: bigint[]
+    }
+    type Expected = {
+      num: JSONValue[]
+    }
+    type Actual = JSONParsed<Post, never>
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+
+  it('Should parse bigint with a toJSON function', () => {
+    class SafeBigInt {
+      unsafe = BigInt('42')
+
+      toJSON() {
+        return {
+          unsafe: '42n',
+        }
+      }
+    }
+
+    type Actual = JSONParsed<SafeBigInt>
+    type Expected = { unsafe: string }
+    expectTypeOf<Actual>().toEqualTypeOf<Expected>()
+  })
+})