@pikku/core 0.12.2 → 0.12.4

package/src/wirings/channel/channel.types.ts

@@ -1,178 +0,0 @@
-import type { PikkuError } from '../../errors/error-handler.js'
-import type {
-  HTTPFunctionMetaInputTypes,
-  PikkuHTTPRequest,
-  PikkuHTTPResponse,
-} from '../http/http.types.js'
-import type {
-  CorePikkuMiddleware,
-  MiddlewareMetadata,
-  PermissionMetadata,
-} from '../../types/core.types.js'
-
-export type BinaryData = ArrayBuffer | Uint8Array
-
-export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (
-  services: Services,
-  event: Event,
-  next: (event: Event | Event[] | null) => Promise<void> | void
-) => Promise<void> | void
-
-export type CorePikkuChannelMiddlewareFactory<
-  In = any,
-  Services = any,
-  Event = unknown,
-> = (input: In) => CorePikkuChannelMiddleware<Services, Event>
-import type {
-  CorePermissionGroup,
-  CorePikkuFunction,
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-  CorePikkuPermission,
-} from '../../function/functions.types.js'
-
-export type RunChannelOptions = Partial<{
-  skipUserSession: boolean
-  respondWith404: boolean
-  coerceDataFromSchema: boolean
-  logWarningsForStatusCodes: number[]
-  bubbleErrors: boolean
-}>
-
-export type RunChannelParams<ChannelData> = {
-  channelId: string
-  request?: PikkuHTTPRequest<ChannelData>
-  response?: PikkuHTTPResponse
-}
-
-export interface ChannelMessageMeta {
-  pikkuFuncId: string
-  summary?: string
-  description?: string
-  errors?: string[]
-  tags?: string[]
-  middleware?: MiddlewareMetadata[]
-  permissions?: PermissionMetadata[]
-}
-
-export interface ChannelMeta {
-  name: string
-  route: string
-  params?: string[]
-  query?: string[]
-  input: string | null
-  inputTypes?: HTTPFunctionMetaInputTypes
-  connect: ChannelMessageMeta | null
-  disconnect: ChannelMessageMeta | null
-  message: ChannelMessageMeta | null
-  messageWirings: Record<string, Record<string, ChannelMessageMeta>>
-  binary?: boolean | null
-  summary?: string
-  description?: string
-  errors?: string[]
-  tags?: string[]
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
-  channelMiddleware?: MiddlewareMetadata[]
-}
-
-export type ChannelsMeta = Record<string, ChannelMeta>
-
-export type CoreChannel<
-  ChannelData,
-  Channel extends string,
-  ChannelConnect = CorePikkuFunctionConfig<
-    | CorePikkuFunction<void, unknown>
-    | CorePikkuFunctionSessionless<void, unknown>,
-    CorePikkuPermission<void>,
-    CorePikkuMiddleware
-  >,
-  ChannelDisconnect = CorePikkuFunctionConfig<
-    CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>,
-    CorePikkuPermission<void>,
-    CorePikkuMiddleware
-  >,
-  ChannelFunctionMessage = CorePikkuFunctionConfig<
-    | CorePikkuFunction<unknown, unknown>
-    | CorePikkuFunctionSessionless<unknown, unknown>,
-    CorePikkuPermission<unknown>,
-    CorePikkuMiddleware
-  >,
-  PikkuPermission = CorePikkuPermission<ChannelData>,
-  PikkuMiddleware = CorePikkuMiddleware,
-> = {
-  name: string
-  route: Channel
-  onConnect?:
-    | ChannelConnect
-    | {
-        func?: ChannelConnect
-        middleware?: PikkuMiddleware[]
-      }
-  onDisconnect?:
-    | ChannelDisconnect
-    | {
-        func?: ChannelDisconnect
-        middleware?: PikkuMiddleware[]
-      }
-  onMessage?: ChannelFunctionMessage
-  onMessageWiring?: Record<
-    string,
-    Record<
-      string,
-      | ChannelFunctionMessage
-      | {
-          func: ChannelFunctionMessage
-          permissions?: CorePermissionGroup<PikkuPermission>
-          auth?: boolean
-          middleware?: PikkuMiddleware[]
-        }
-    >
-  >
-  middleware?: PikkuMiddleware[]
-  channelMiddleware?: Array<
-    CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
-  >
-  permissions?: CorePermissionGroup<PikkuPermission>
-  auth?: boolean
-  binary?: boolean | null
-  onBinaryMessage?: (
-    services: any,
-    data: BinaryData,
-    channel: PikkuChannel<ChannelData, any>
-  ) => Promise<BinaryData | void> | BinaryData | void
-  docs?: Partial<{
-    description: string
-    response: string
-    errors: Array<typeof PikkuError>
-    tags: string[]
-  }>
-  tags?: string[]
-}
-
-export interface PikkuChannel<OpeningData, out Out> {
-  // The channel identifier
-  channelId: string
-  // The data the channel was created with. This could be query parameters
-  // or parameters in the url.
-  openingData: OpeningData
-  // The data to send. This will fail is the stream has been closed.
-  send(data: Out, isBinary?: boolean): Promise<void> | void
-  sendBinary(data: BinaryData): Promise<void> | void
-  // This will close the channel.
-  close(): Promise<void> | void
-  // The current state of the channel
-  state: 'initial' | 'open' | 'closed'
-}
-
-export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
-  send(message: Out, isBinary?: boolean): Promise<void> | void
-  sendBinary(data: BinaryData): Promise<void> | void
-  getChannel(): PikkuChannel<OpeningData, Out>
-}
-
-export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (
-  channelId: string,
-  channelName: string,
-  openingData: OpeningData
-) => PikkuChannelHandler<OpeningData, Out>

package/src/wirings/channel/define-channel-routes.ts

@@ -1,25 +0,0 @@
-/**
- * Type-safe helper for defining channel message routes that can be composed.
- * Returns the routes record as-is (identity function) for use with `wireChannel`.
- *
- * @example
- * ```typescript
- * export const chatRoutes = defineChannelRoutes({
- *   greet: pikkuChannelFunc({ func: greetFunc }),
- *   farewell: pikkuChannelFunc({ func: farewellFunc }),
- * })
- *
- * wireChannel({
- *   name: 'chat',
- *   route: '/ws/chat',
- *   onMessageWiring: {
- *     command: chatRoutes,
- *   }
- * })
- * ```
- */
-export function defineChannelRoutes<T extends Record<string, any>>(
-  routes: T
-): T {
-  return routes
-}

package/src/wirings/channel/eventhub-service.ts

@@ -1,34 +0,0 @@
-/**
- * Interface defining the methods of a EventHub Service.
- */
-export interface EventHubService<Topics extends Record<string, any>> {
-  /**
-   * Subscribes a connection to a specific topic.
-   * @param topic - The topic to subscribe to.
-   * @param channelId - The unique ID of the connection to subscribe.
-   */
-  subscribe<T extends keyof Topics>(
-    topic: T,
-    channelId: string
-  ): Promise<void> | void
-  /**
-   * Unsubscribes a connection from a specific topic.
-   * @param topic - The topic to unsubscribe from.
-   * @param channelId - The unique ID of the connection to unsubscribe.
-   */
-  unsubscribe<T extends keyof Topics>(
-    topic: T,
-    channelId: string
-  ): Promise<void> | void
-  /**
-   * Sends data to all connections subscribed to a topic.
-   * @param topic - The topic to send data to.
-   * @param data - The data to send to the subscribers.
-   */
-  publish<T extends keyof Topics>(
-    topic: T,
-    channelId: string | null,
-    data: Topics[T],
-    isBinary?: boolean
-  ): Promise<void> | void
-}

package/src/wirings/channel/eventhub-store.ts

@@ -1,13 +0,0 @@
-export abstract class EventHubStore<
-  EventTopics extends Record<string, any> = {},
-> {
-  public abstract getChannelIdsForTopic(topic: string): Promise<string[]>
-  public abstract subscribe<T extends keyof EventTopics>(
-    topic: T,
-    channelId: string
-  ): Promise<boolean>
-  public abstract unsubscribe<T extends keyof EventTopics>(
-    topic: T,
-    channelId: string
-  ): Promise<boolean>
-}

package/src/wirings/channel/index.ts

@@ -1,24 +0,0 @@
-export { wireChannel, openChannel } from './channel-runner.js'
-export {
-  addChannelMiddleware,
-  combineChannelMiddleware,
-  wrapChannelWithMiddleware,
-} from './channel-middleware-runner.js'
-export { logChannels } from './log-channels.js'
-export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
-export type { EventHubService } from './eventhub-service.js'
-export { ChannelStore } from './channel-store.js'
-export type { Channel } from './channel-store.js'
-export { EventHubStore } from './eventhub-store.js'
-export type {
-  BinaryData,
-  ChannelsMeta,
-  CoreChannel,
-  CorePikkuChannelMiddleware,
-  CorePikkuChannelMiddlewareFactory,
-  ChannelMessageMeta,
-  ChannelMeta,
-  PikkuChannel,
-  PikkuChannelHandlerFactory,
-} from './channel.types.js'
-export { defineChannelRoutes } from './define-channel-routes.js'

package/src/wirings/channel/local/index.ts

@@ -1,3 +0,0 @@
-export { PikkuLocalChannelHandler } from './local-channel-handler.js'
-export { runLocalChannel } from './local-channel-runner.js'
-export { LocalEventHubService } from './local-eventhub-service.js'

package/src/wirings/channel/local/local-channel-handler.ts

@@ -1,79 +0,0 @@
-import type { BinaryData } from '../channel.types.js'
-import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js'
-
-export class PikkuLocalChannelHandler<
-  OpeningData = unknown,
-  Out = unknown,
-> extends PikkuAbstractChannelHandler<OpeningData, Out> {
-  private onMessageCallback?: (message: unknown) => void
-  private onBinaryMessageCallback?: (data: BinaryData) => void
-  private openCallBack?: () => void
-  private closeCallback?: () => void
-  private sendCallback?: (message: Out, isBinary?: boolean) => void
-  private sendBinaryCallback?: (data: BinaryData) => void
-
-  public registerOnOpen(callback: () => void): void {
-    this.openCallBack = callback
-  }
-
-  public open() {
-    this.getChannel().state = 'open'
-    if (this.openCallBack) {
-      this.openCallBack()
-    }
-  }
-
-  public registerOnMessage(callback: (data: any) => Promise<unknown>): void {
-    this.onMessageCallback = callback
-  }
-
-  public async message(data: unknown): Promise<unknown> {
-    return this.onMessageCallback?.(data)
-  }
-
-  public registerOnBinaryMessage(
-    callback: (
-      data: BinaryData
-    ) => Promise<BinaryData | void> | BinaryData | void
-  ): void {
-    this.onBinaryMessageCallback = callback
-  }
-
-  public async binaryMessage(data: BinaryData): Promise<BinaryData | void> {
-    return this.onBinaryMessageCallback?.(data)
-  }
-
-  public registerOnClose(callback: () => void): void {
-    this.closeCallback = callback
-  }
-
-  public close() {
-    if (this.getChannel().state === 'closed') {
-      return
-    }
-    super.close()
-    this.closeCallback?.()
-  }
-
-  public registerOnSend(send: (message: Out) => void) {
-    this.sendCallback = send
-  }
-
-  public send(message: Out, isBinary?: boolean): void {
-    if (!this.sendCallback) {
-      throw new Error('No send callback registered')
-    }
-    return this.sendCallback?.(message, isBinary)
-  }
-
-  public registerOnSendBinary(send: (data: BinaryData) => void) {
-    this.sendBinaryCallback = send
-  }
-
-  public sendBinary(data: BinaryData): void {
-    if (!this.sendBinaryCallback) {
-      throw new Error('No sendBinary callback registered')
-    }
-    this.sendBinaryCallback(data)
-  }
-}

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -1,215 +0,0 @@
-import { test, beforeEach, afterEach } from 'node:test'
-import * as assert from 'node:assert/strict'
-import { runLocalChannel } from './local-channel-runner.js'
-import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
-import { wireChannel } from '../channel-runner.js'
-import type {
-  HTTPMethod,
-  PikkuHTTPRequest,
-  PikkuHTTPResponse,
-  PikkuQuery,
-} from '../../http/http.types.js'
-import type { SerializeOptions } from 'cookie'
-import { httpRouter } from '../../http/routers/http-router.js'
-
-/**
- * Minimal stubs for dependencies that runChannel expects.
- * In a real test setup, you may provide more comprehensive mocks
- * or refactor your code to allow dependency injection.
- */
-const mockLogger = {
-  info: () => {},
-  error: () => {},
-  warn: () => {},
-  debug: () => {},
-}
-
-const mockSingletonServices = {
-  logger: mockLogger,
-} as any
-
-// Mock request and response objects
-export class PikkuMockRequest implements PikkuHTTPRequest {
-  private _params: Record<string, string | string[] | undefined> = {}
-
-  constructor(
-    private _route: string,
-    private _method: HTTPMethod
-  ) {}
-
-  method(): HTTPMethod {
-    return this._method
-  }
-  path(): string {
-    return this._route
-  }
-  json(): Promise<unknown> {
-    throw new Error('Method not implemented.')
-  }
-  arrayBuffer(): Promise<ArrayBuffer> {
-    throw new Error('Method not implemented.')
-  }
-  header(headerName: string): string | null {
-    throw new Error('Method not implemented.')
-  }
-  cookie(name?: string): string | null {
-    throw new Error('Method not implemented.')
-  }
-  params(): Partial<Record<string, string | string[]>> {
-    return this._params
-  }
-  setParams(params: Record<string, string | string[] | undefined>): void {
-    this._params = params
-  }
-  query(): PikkuQuery {
-    throw new Error('Method not implemented.')
-  }
-  public async data() {
-    return { test: 'data' }
-  }
-}
-
-export class PikkuMockResponse implements PikkuHTTPResponse {
-  public _status: number | undefined
-
-  status(code: number): this {
-    this._status = code
-    return this
-  }
-
-  cookie(name: string, value: string | null, options: SerializeOptions): this {
-    throw new Error('Method not implemented.')
-  }
-  header(name: string, value: string | string[]): this {
-    throw new Error('Method not implemented.')
-  }
-  arrayBuffer(data: XMLHttpRequestBodyInit): this {
-    throw new Error('Method not implemented.')
-  }
-  json(data: unknown): this {
-    // We don't need to implement this for our test
-    return this
-  }
-  redirect(location: string, status?: number): this {
-    throw new Error('Method not implemented.')
-  }
-}
-
-const mockCreateWireServices = async () => ({
-  wireServiceMock: true,
-})
-
-beforeEach(() => {
-  resetPikkuState()
-  httpRouter.reset()
-  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
-  pikkuState(null, 'package', 'factories', {
-    createWireServices: mockCreateWireServices,
-  } as any)
-})
-
-afterEach(() => {
-  resetPikkuState()
-  httpRouter.reset()
-})
-
-test('runChannel should return undefined and 404 if no matching channel is found', async () => {
-  const mockResponse = new PikkuMockResponse()
-
-  const result = await runLocalChannel({
-    channelId: 'test-channel-id',
-    request: new PikkuMockRequest('/non-existent-channel', 'get'),
-    response: mockResponse,
-  })
-
-  assert.equal(
-    result,
-    undefined,
-    'Should return undefined if no channel matches'
-  )
-  assert.equal(mockResponse._status, 404, 'Should set response status to 404')
-  // assert.equal(mockResponse._ended, true, 'Should end the response')
-})
-
-test('runChannel should return a channel handler if channel matches and no auth required', async () => {
-  resetPikkuState()
-  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
-  pikkuState(null, 'package', 'factories', {
-    createWireServices: mockCreateWireServices,
-  } as any)
-
-  pikkuState(null, 'channel', 'meta', {
-    test: {
-      name: 'test',
-      route: '/test-channel',
-    },
-  } as any)
-  wireChannel({
-    name: 'test',
-    route: '/test-channel',
-    auth: false,
-  })
-
-  // Initialize router after adding channel (for tests)
-  httpRouter.initialize()
-
-  const result = await runLocalChannel({
-    channelId: 'test-channel-id',
-    request: new PikkuMockRequest('/test-channel', 'get'),
-    response: new PikkuMockResponse(),
-    route: '/test-channel',
-  })
-
-  assert.ok(result, 'Should return a PikkuChannelHandler instance')
-
-  // Simulate opening the channel
-  result.open()
-})
-
-test('runChannel should close wire services once when channel closes', async () => {
-  resetPikkuState()
-  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
-  let closeCount = 0
-
-  pikkuState(null, 'channel', 'meta', {
-    test: {
-      name: 'test',
-      route: '/test-channel',
-    },
-  } as any)
-  wireChannel({
-    name: 'test',
-    route: '/test-channel',
-    auth: false,
-  })
-
-  httpRouter.initialize()
-
-  pikkuState(null, 'package', 'factories', {
-    createWireServices: async () => ({
-      tracked: {
-        close: async () => {
-          closeCount += 1
-        },
-      },
-    }),
-  } as any)
-
-  const result = await runLocalChannel({
-    channelId: 'test-channel-id',
-    request: new PikkuMockRequest('/test-channel', 'get'),
-    response: new PikkuMockResponse(),
-    route: '/test-channel',
-  })
-
-  assert.ok(result)
-  assert.equal(closeCount, 0)
-
-  result.close()
-  await new Promise((resolve) => setTimeout(resolve, 0))
-  assert.equal(closeCount, 1)
-
-  result.close()
-  await new Promise((resolve) => setTimeout(resolve, 0))
-  assert.equal(closeCount, 1)
-})