@pikku/core 0.6.9

package/dist/channel/eventhub-forwarder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface defining the methods of a EventHub Service.
+ */
+export interface EventHubForwarder {
+    /**
+     * 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.
+     */
+    forwardPublish(topic: string, channelId: string, data: unknown, isBinary?: boolean): Promise<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.
+     */
+    onForwardedPublishMessage(callback: (topic: string, data: unknown, isBinary?: boolean) => void): void;
+}

package/dist/channel/eventhub-forwarder.js

@@ -0,0 +1 @@
+export {};

package/dist/channel/eventhub-service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Interface defining the methods of a EventHub Service.
+ */
+export interface EventHubService<Out = unknown> {
+    /**
+     * 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(topic: string, 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(topic: string, 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(topic: string, channelId: string | null, data: Out, isBinary?: boolean): Promise<void> | void;
+}

package/dist/channel/eventhub-service.js

@@ -0,0 +1 @@
+export {};

package/dist/channel/eventhub-store.d.ts

@@ -0,0 +1,5 @@
+export declare abstract class EventHubStore {
+    abstract getChannelIdsForTopic(topic: string): Promise<string[]>;
+    abstract subscribe(topic: string, channelId: string): Promise<boolean>;
+    abstract unsubscribe(topic: string, channelId: string): Promise<boolean>;
+}

package/dist/channel/eventhub-store.js

@@ -0,0 +1,2 @@
+export class EventHubStore {
+}

package/dist/channel/index.d.ts

@@ -0,0 +1,9 @@
+export * from './channel-runner.js';
+export * from './channel.types.js';
+export * from './log-channels.js';
+export * from './pikku-abstract-channel-handler.js';
+export * from './eventhub-service.js';
+export * from './eventhub-forwarder.js';
+export * from './eventhub-service.js';
+export * from './channel-store.js';
+export * from './eventhub-store.js';

package/dist/channel/index.js

@@ -0,0 +1,9 @@
+export * from './channel-runner.js';
+export * from './channel.types.js';
+export * from './log-channels.js';
+export * from './pikku-abstract-channel-handler.js';
+export * from './eventhub-service.js';
+export * from './eventhub-forwarder.js';
+export * from './eventhub-service.js';
+export * from './channel-store.js';
+export * from './eventhub-store.js';

package/dist/channel/local/index.d.ts

@@ -0,0 +1,3 @@
+export * from './local-channel-handler.js';
+export * from './local-channel-runner.js';
+export * from './local-eventhub-service.js';

package/dist/channel/local/index.js

@@ -0,0 +1,3 @@
+export * from './local-channel-handler.js';
+export * from './local-channel-runner.js';
+export * from './local-eventhub-service.js';

package/dist/channel/local/local-channel-handler.d.ts

@@ -0,0 +1,17 @@
+import { CoreUserSession } from '../../types/core.types.js';
+import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
+export declare class PikkuLocalChannelHandler<UserSession extends CoreUserSession = CoreUserSession, OpeningData = unknown, Out = unknown> extends PikkuAbstractChannelHandler<UserSession, OpeningData, Out> {
+    private onMessageCallback?;
+    private openCallBack?;
+    private closeCallback?;
+    private sendCallback?;
+    registerOnOpen(callback: () => void): void;
+    open(): void;
+    registerOnMessage(callback: (data: any) => Promise<unknown>): void;
+    message(data: unknown): Promise<unknown>;
+    registerOnClose(callback: () => void): void;
+    close(): void;
+    registerOnSend(send: (message: Out) => void): void;
+    send(message: Out, isBinary?: boolean): void;
+    setUserSession(userSession: UserSession): void;
+}

package/dist/channel/local/local-channel-handler.js

@@ -0,0 +1,41 @@
+import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
+export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
+    onMessageCallback;
+    openCallBack;
+    closeCallback;
+    sendCallback;
+    registerOnOpen(callback) {
+        this.openCallBack = callback;
+    }
+    open() {
+        this.getChannel().state = 'open';
+        if (this.openCallBack) {
+            this.openCallBack();
+        }
+    }
+    registerOnMessage(callback) {
+        this.onMessageCallback = callback;
+    }
+    async message(data) {
+        return this.onMessageCallback?.(data);
+    }
+    registerOnClose(callback) {
+        this.closeCallback = callback;
+    }
+    close() {
+        super.close();
+        this.closeCallback?.();
+    }
+    registerOnSend(send) {
+        this.sendCallback = send;
+    }
+    send(message, isBinary) {
+        if (!this.sendCallback) {
+            throw new Error('No send callback registered');
+        }
+        return this.sendCallback?.(message, isBinary);
+    }
+    setUserSession(userSession) {
+        this.getChannel().userSession = userSession;
+    }
+}

package/dist/channel/local/local-channel-runner.d.ts

@@ -0,0 +1,3 @@
+import { CoreAPIChannel, RunChannelOptions, RunChannelParams } from '../channel.types.js';
+import { PikkuLocalChannelHandler } from './local-channel-handler.js';
+export declare const runLocalChannel: ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession, respondWith404, coerceToArray, logWarningsForStatusCodes, bubbleErrors, }: Pick<CoreAPIChannel<unknown, any>, "route"> & RunChannelOptions & RunChannelParams<unknown>) => Promise<PikkuLocalChannelHandler | void>;

package/dist/channel/local/local-channel-runner.js

@@ -0,0 +1,46 @@
+import { openChannel } from '../channel-runner.js';
+import { createHTTPInteraction, handleError, } from '../../http/http-route-runner.js';
+import { closeSessionServices } from '../../utils.js';
+import { processMessageHandlers } from '../channel-handler.js';
+import { PikkuLocalChannelHandler } from './local-channel-handler.js';
+export const runLocalChannel = async ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession = false, respondWith404 = true, coerceToArray = false, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
+    let sessionServices;
+    const http = createHTTPInteraction(request, response);
+    try {
+        const { userSession, openingData, channelConfig } = await openChannel({
+            channelId,
+            createSessionServices,
+            respondWith404,
+            http,
+            route,
+            singletonServices,
+            skipUserSession,
+            coerceToArray,
+        });
+        const channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, userSession, openingData);
+        const channel = channelHandler.getChannel();
+        if (createSessionServices) {
+            sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+        }
+        const allServices = { ...singletonServices, ...sessionServices };
+        channelHandler.registerOnOpen(() => {
+            channelConfig.onConnect?.(allServices, channel);
+        });
+        channelHandler.registerOnClose(async () => {
+            channelConfig.onDisconnect?.(allServices, channel);
+            if (sessionServices) {
+                await closeSessionServices(singletonServices.logger, sessionServices);
+            }
+        });
+        channelHandler.registerOnMessage(processMessageHandlers(allServices, channelConfig, channelHandler));
+        return channelHandler;
+    }
+    catch (e) {
+        handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+};

package/dist/channel/local/local-eventhub-service.d.ts

@@ -0,0 +1,44 @@
+import { PikkuChannelHandler } from '../channel.types.js';
+import { EventHubService } from '../eventhub-service.js';
+/**
+ * Implementation of the SubscriptionService interface.
+ * Manages subscriptions and publishes messages to subscribers.
+ */
+export declare class LocalEventHubService<Data = unknown> implements EventHubService<Data> {
+    private channels;
+    /**
+     * A map storing topics and their associated connection IDs.
+     */
+    private subscriptions;
+    /**
+     * Subscribes a connection to a specific topic.
+     * Creates the topic if it does not already exist.
+     * @param topic - The topic to subscribe to.
+     * @param channelId - The unique ID of the connection to subscribe.
+     */
+    subscribe(topic: string, channelId: string): void;
+    /**
+     * Unsubscribes a connection from a specific topic.
+     * Removes the topic if it has no more subscribers.
+     * @param topic - The topic to unsubscribe from.
+     * @param channelId - The unique ID of the connection to unsubscribe.
+     */
+    unsubscribe(topic: string, channelId: string): 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(topic: string, channelId: string, data: Data, isBinary?: boolean): void;
+    /**
+     * Registers a channel on open
+     */
+    onChannelOpened(channelHandler: PikkuChannelHandler): void;
+    /**
+     * Handles cleanup when a channel is closed.
+     * Removes the channel from all topics it is subscribed to.
+     * Deletes the topic if no more channels are subscribed to it.
+     * @param channelId - The ID of the channel that was closed.
+     */
+    onChannelClosed(channelId: string): void;
+}

package/dist/channel/local/local-eventhub-service.js

@@ -0,0 +1,81 @@
+/**
+ * Implementation of the SubscriptionService interface.
+ * Manages subscriptions and publishes messages to subscribers.
+ */
+export class LocalEventHubService {
+    channels = new Map();
+    /**
+     * A map storing topics and their associated connection IDs.
+     */
+    subscriptions = new Map();
+    /**
+     * Subscribes a connection to a specific topic.
+     * Creates the topic if it does not already exist.
+     * @param topic - The topic to subscribe to.
+     * @param channelId - The unique ID of the connection to subscribe.
+     */
+    subscribe(topic, channelId) {
+        if (!this.subscriptions.has(topic)) {
+            this.subscriptions.set(topic, new Set());
+        }
+        this.subscriptions.get(topic).add(channelId);
+    }
+    /**
+     * Unsubscribes a connection from a specific topic.
+     * Removes the topic if it has no more subscribers.
+     * @param topic - The topic to unsubscribe from.
+     * @param channelId - The unique ID of the connection to unsubscribe.
+     */
+    unsubscribe(topic, channelId) {
+        const topicSubscriptions = this.subscriptions.get(topic);
+        if (topicSubscriptions) {
+            topicSubscriptions.delete(channelId);
+            if (topicSubscriptions.size === 0) {
+                this.subscriptions.delete(topic); // Cleanup empty subscriptions
+            }
+        }
+    }
+    /**
+     * 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(topic, channelId, data, isBinary) {
+        const subscribedChannelIds = this.subscriptions.get(topic);
+        if (!subscribedChannelIds) {
+            return;
+        }
+        for (const toChannelId of subscribedChannelIds) {
+            if (channelId === toChannelId)
+                continue; // Skip sending to the sender
+            const channel = this.channels.get(toChannelId);
+            if (channel) {
+                channel.send(data, isBinary);
+            }
+            else {
+                // TODO: Websocket is closed, remove the channel from the topic
+            }
+        }
+    }
+    /**
+     * Registers a channel on open
+     */
+    onChannelOpened(channelHandler) {
+        this.channels.set(channelHandler.getChannel().channelId, channelHandler);
+    }
+    /**
+     * Handles cleanup when a channel is closed.
+     * Removes the channel from all topics it is subscribed to.
+     * Deletes the topic if no more channels are subscribed to it.
+     * @param channelId - The ID of the channel that was closed.
+     */
+    onChannelClosed(channelId) {
+        for (const [topic, channelIds] of this.subscriptions.entries()) {
+            channelIds.delete(channelId);
+            if (channelIds.size === 0) {
+                this.subscriptions.delete(topic); // Cleanup empty topics
+            }
+        }
+        this.channels.delete(channelId);
+    }
+}

package/dist/channel/log-channels.d.ts

@@ -0,0 +1,6 @@
+import { Logger } from '../services/index.js';
+/**
+ * Logs all the loaded channels.
+ * @param logger - A logger for logging information.
+ */
+export declare const logChannels: (logger: Logger) => void;

package/dist/channel/log-channels.js

@@ -0,0 +1,17 @@
+import { getChannels } from './channel-runner.js';
+/**
+ * Logs all the loaded channels.
+ * @param logger - A logger for logging information.
+ */
+export const logChannels = (logger) => {
+    const { channels } = getChannels();
+    if (channels.length === 0) {
+        logger.info('No channels added');
+        return;
+    }
+    let scheduledChannels = 'Channels:';
+    for (const { name, route } of channels) {
+        scheduledChannels += `\n\t- ${name} at ${route}`;
+    }
+    logger.info(scheduledChannels);
+};

package/dist/channel/pikku-abstract-channel-handler.d.ts

@@ -0,0 +1,15 @@
+import { CoreUserSession } from '../types/core.types.js';
+import { PikkuChannel, PikkuChannelHandler } from './channel.types.js';
+export declare abstract class PikkuAbstractChannelHandler<UserSession extends CoreUserSession = CoreUserSession, OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<UserSession, OpeningData, Out> {
+    channelId: string;
+    channelName: string;
+    protected userSession: UserSession | undefined;
+    protected openingData: OpeningData;
+    protected channel?: PikkuChannel<UserSession, OpeningData, Out>;
+    constructor(channelId: string, channelName: string, userSession: UserSession | undefined, openingData: OpeningData);
+    abstract setUserSession(userSession: UserSession): Promise<void> | void;
+    abstract send(message: Out, isBinary?: boolean): Promise<void> | void;
+    getChannel(): PikkuChannel<UserSession, OpeningData, Out>;
+    open(): void;
+    close(): Promise<void> | void;
+}

package/dist/channel/pikku-abstract-channel-handler.js

@@ -0,0 +1,33 @@
+export class PikkuAbstractChannelHandler {
+    channelId;
+    channelName;
+    userSession;
+    openingData;
+    channel;
+    constructor(channelId, channelName, userSession, openingData) {
+        this.channelId = channelId;
+        this.channelName = channelName;
+        this.userSession = userSession;
+        this.openingData = openingData;
+    }
+    getChannel() {
+        if (!this.channel) {
+            this.channel = {
+                channelId: this.channelId,
+                userSession: this.userSession,
+                openingData: this.openingData,
+                setUserSession: this.setUserSession.bind(this),
+                send: this.send.bind(this),
+                close: this.close.bind(this),
+                state: 'initial',
+            };
+        }
+        return this.channel;
+    }
+    open() {
+        this.getChannel().state = 'open';
+    }
+    close() {
+        this.getChannel().state = 'closed';
+    }
+}

package/dist/channel/serverless/index.d.ts

@@ -0,0 +1 @@
+export * from './serverless-channel-runner.js';

package/dist/channel/serverless/index.js

@@ -0,0 +1 @@
+export * from './serverless-channel-runner.js';

package/dist/channel/serverless/serverless-channel-runner.d.ts

@@ -0,0 +1,10 @@
+import type { CoreAPIChannel, RunChannelOptions, RunChannelParams, PikkuChannelHandlerFactory } from '../channel.types.js';
+import { ChannelStore } from '../channel-store.js';
+export interface RunServerlessChannelParams<ChannelData> extends RunChannelParams<ChannelData> {
+    channelStore: ChannelStore;
+    channelHandlerFactory: PikkuChannelHandlerFactory;
+    channelObject?: unknown;
+}
+export declare const runChannelConnect: ({ singletonServices, channelId, channelObject, request, response, route, createSessionServices, channelStore, channelHandlerFactory, coerceToArray, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreAPIChannel<unknown, any>, "route"> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
+export declare const runChannelDisconnect: ({ singletonServices, ...params }: RunServerlessChannelParams<unknown>) => Promise<void>;
+export declare const runChannelMessage: ({ singletonServices, ...params }: RunServerlessChannelParams<unknown>, data: unknown) => Promise<unknown>;

package/dist/channel/serverless/serverless-channel-runner.js

@@ -0,0 +1,98 @@
+import { closeSessionServices } from '../../utils.js';
+import { processMessageHandlers } from '../channel-handler.js';
+import { getChannels, openChannel } from '../channel-runner.js';
+import { createHTTPInteraction, handleError, } from '../../http/http-route-runner.js';
+const getVariablesForChannel = ({ channelId, userSession, channelName, channelHandlerFactory, openingData, }) => {
+    const { channels } = getChannels();
+    const channelConfig = channels.find((channelConfig) => channelConfig.name === channelName);
+    if (!channelConfig) {
+        throw new Error(`Channel not found: ${channelName}`);
+    }
+    const channelHandler = channelHandlerFactory(channelId, channelConfig.name, openingData, userSession);
+    return {
+        channelConfig,
+        channelHandler,
+        channel: channelHandler.getChannel(),
+    };
+};
+export const runChannelConnect = async ({ singletonServices, channelId, channelObject, request, response, route, createSessionServices, channelStore, channelHandlerFactory, coerceToArray = false, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
+    let sessionServices;
+    const http = createHTTPInteraction(request, response);
+    try {
+        const { userSession, channelConfig, openingData } = await openChannel({
+            channelId,
+            createSessionServices,
+            http,
+            route,
+            singletonServices,
+            coerceToArray,
+        });
+        await channelStore.addChannel({
+            channelId,
+            channelName: channelConfig.name,
+            openingData,
+            channelObject,
+        });
+        const { channel } = getVariablesForChannel({
+            channelId,
+            userSession,
+            channelHandlerFactory,
+            channelName: channelConfig.name,
+        });
+        if (createSessionServices) {
+            sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+        }
+        await channelConfig.onConnect?.({ ...singletonServices, ...sessionServices }, channel);
+        http?.response?.setStatus(101);
+    }
+    catch (e) {
+        handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+};
+export const runChannelDisconnect = async ({ singletonServices, ...params }) => {
+    let sessionServices;
+    const { userSession, openingData, channelName } = await params.channelStore.getChannel(params.channelId);
+    const { channel, channelConfig } = getVariablesForChannel({
+        ...params,
+        userSession,
+        openingData,
+        channelName,
+    });
+    if (!sessionServices && params.createSessionServices) {
+        sessionServices = await params.createSessionServices(singletonServices, {}, userSession);
+    }
+    await channelConfig.onDisconnect?.({ ...singletonServices, ...sessionServices }, channel);
+    await params.channelStore.removeChannels([channel.channelId]);
+    if (sessionServices) {
+        await closeSessionServices(singletonServices.logger, sessionServices);
+    }
+};
+export const runChannelMessage = async ({ singletonServices, ...params }, data) => {
+    let sessionServices;
+    const { userSession, openingData, channelName } = await params.channelStore.getChannel(params.channelId);
+    const { channelHandler, channelConfig } = getVariablesForChannel({
+        ...params,
+        userSession,
+        openingData,
+        channelName,
+    });
+    if (params.createSessionServices) {
+        sessionServices = await params.createSessionServices(singletonServices, {}, userSession);
+    }
+    let response;
+    try {
+        const onMessage = processMessageHandlers({ ...singletonServices, ...sessionServices }, channelConfig, channelHandler);
+        response = await onMessage(data);
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+    return response;
+};

package/dist/errors/error-handler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Base class for custom errors.
+ * @extends {Error}
+ */
+export declare class EError extends Error {
+    /**
+     * Creates an instance of EError.
+     * @param message - The error message.
+     */
+    constructor(message?: string);
+}
+/**
+ * Interface for error details.
+ */
+export interface ErrorDetails {
+    status: number;
+    message: string;
+}
+export declare const getErrors: () => Map<any, ErrorDetails>;
+/**
+ * Adds an error to the API errors map.
+ * @param error - The error to add.
+ * @param details - The details of the error.
+ */
+export declare const addError: (error: any, { status, message }: ErrorDetails) => void;
+/**
+ * Adds multiple errors to the API errors map.
+ * @param errors - An array of errors and their details.
+ */
+export declare const addErrors: (errors: Array<[error: any, details: ErrorDetails]>) => void;
+/**
+ * Retrieves the error response for a given error.
+ * @param error - The error to get the response for.
+ * @returns An object containing the status and message, or undefined if the error is not found.
+ */
+export declare const getErrorResponse: (error: Error) => {
+    status: number;
+    message: string;
+} | undefined;

package/dist/errors/error-handler.js

@@ -0,0 +1,54 @@
+/**
+ * Base class for custom errors.
+ * @extends {Error}
+ */
+export class EError extends Error {
+    /**
+     * Creates an instance of EError.
+     * @param message - The error message.
+     */
+    constructor(message = 'An error occurred') {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Map of API errors to their details.
+ */
+if (!globalThis.pikku?.apiErrors) {
+    globalThis.pikku = globalThis.pikku || {};
+    globalThis.pikku.apiErrors = new Map([]);
+}
+const apiErrors = () => {
+    return globalThis.pikku.apiErrors;
+};
+export const getErrors = () => apiErrors();
+/**
+ * Adds an error to the API errors map.
+ * @param error - The error to add.
+ * @param details - The details of the error.
+ */
+export const addError = (error, { status, message }) => {
+    apiErrors().set(error, { status, message });
+};
+/**
+ * Adds multiple errors to the API errors map.
+ * @param errors - An array of errors and their details.
+ */
+export const addErrors = (errors) => {
+    errors.forEach((error) => {
+        addError(error[0], error[1]);
+    });
+};
+/**
+ * Retrieves the error response for a given error.
+ * @param error - The error to get the response for.
+ * @returns An object containing the status and message, or undefined if the error is not found.
+ */
+export const getErrorResponse = (error) => {
+    const foundError = Array.from(apiErrors().entries()).find(([e]) => e.name === error.constructor.name);
+    if (foundError) {
+        return foundError[1];
+    }
+    return apiErrors().get(error);
+};