arkos 2.0.0-next.3 → 2.0.0-next.30

package/dist/types/app.d.ts

@@ -1,6 +1,10 @@
-import "./utils/helpers/arkos-config.helpers";
-import { Arkos } from "./types/arkos";
-import { IncomingMessage, Server, ServerResponse } from "http";
+import express from 'express';
+import { Arkos } from './types/arkos';
+import { IncomingMessage, Server, ServerResponse } from 'http';
+export declare const app: express.Express;
+export declare const docsLink = "https://www.arkosjs.com/docs/core-concepts/routing/setup#setting-up-your-app";
+type AppState = 'idle' | 'building' | 'built' | 'listening';
+export declare let state: AppState;
 /**
  * Creates and configures an Arkos application instance.
  *
@@ -31,16 +35,17 @@ import { IncomingMessage, Server, ServerResponse } from "http";
  *
  * app.use(reportsRouter);
  *
- * async function start() {
- *  await app.build();
+ * await app.build();
  *
- *  const server = http.createServer(app);
- *  app.listen(server)
- * }
- * main()
+ * const server = http.createServer(app);
+ * app.listen(server)
  * ```
  *
  * @see {@link https://www.arkosjs.com/docs/core-concepts/routing/setup}
  */
-export declare function arkos(): Arkos;
+declare function arkos(): Arkos;
+declare namespace arkos {
+    var serveUploadDir: typeof import("./modules/file-upload/utils/helpers/serve-upload-dir").serveUploadDir;
+}
+export default arkos;
 export declare function getAppServer(): Server<typeof IncomingMessage, typeof ServerResponse>;

package/dist/types/components/arkos-gateway/arkos-gateway.d.ts

@@ -0,0 +1,135 @@
+import { ArkosGatewayConfig, ArkosGatewayErrorHandler, ArkosGatewayEventConfig, ArkosGatewayHandler, ArkosGatewayPipe, ArkosGatewayMiddleware, ArkosGatewayConnectionHandler, ArkosGatewayRegisterOptions, ArkosBroadcastOperator, ArkosEmitTarget } from "./types";
+import { Validator } from "../../types/validation/validator";
+import { BroadcastOperator, Namespace, Server } from "socket.io";
+export declare class IArkosGateway {
+    private config;
+    private events;
+    private pipes;
+    private middlewares;
+    private gateways;
+    private hooks;
+    private _nsp;
+    constructor(config: ArkosGatewayConfig);
+    get nsp(): Omit<Namespace, keyof ArkosEmitTarget | keyof BroadcastOperator<any, any>> & ArkosBroadcastOperator;
+    /**
+     * Register a Socket.io connection-level middleware — runs before a socket
+     * is accepted into this gateway's namespace, and before authentication.
+     * Also accepts a child `ArkosGateway` which will inherit this gateway's
+     * name as prefix along with its auth, rateLimit, and pipes.
+     *
+     * @example
+     * chatGateway.use((socket, next) => {
+     *   console.log("incoming connection", socket.id)
+     * })
+     *
+     * // nested gateway
+     * chatGateway.use(notificationsGateway)
+     */
+    use(...middlewareOrGateway: Array<ArkosGatewayMiddleware | IArkosGateway>): this;
+    /**
+     * Register a pipe — middleware that runs before event handlers.
+     *
+     * When called with a function only, the pipe runs before every event
+     * handler in this gateway and drills down to child gateways.
+     *
+     * When called with an event config object, the pipe runs only for that
+     * specific event.
+     *
+     * @example
+     * // runs before every event in this gateway
+     * chatGateway.pipe((socket, data) => {
+     * })
+     *
+     * // runs only before "send_message"
+     * chatGateway.pipe({ event: "send_message" }, (socket, data) => {
+     * })
+     */
+    pipe(fn: ArkosGatewayPipe): this;
+    pipe<TSchema extends Validator = any>(eventConfig: {
+        event: string;
+    }, fn: ArkosGatewayPipe): this;
+    /**
+     * Register an event handler.
+     *
+     * @example
+     * chatGateway.on(
+     *   { event: "send_message", validation: MessageSchema, ack: true },
+     *   (socket, data, ack) => {
+     *     socket.to(data.room).emit("receive_message", data)
+     *     ack?.({ status: "ok" })
+     *   }
+     * )
+     */
+    on<TSchema extends Validator = any>(eventConfig: ArkosGatewayEventConfig<TSchema>, handler: ArkosGatewayHandler<TSchema>): this;
+    /**
+     * Register a lifecycle hook.
+     *
+     * - `"connection"` — called after a socket successfully connects and passes authentication.
+     * - `"disconnect"` — called when a socket disconnects.
+     * - `"error"` — called when an error is thrown inside any event handler.
+     *   If not registered, Arkos emits a default `"error"` event to the socket.
+     *
+     * @example
+     * chatGateway.hook("connection", (socket) => {
+     *   console.log("connected", socket.user.id)
+     * })
+     *
+     * chatGateway.hook("error", (err, socket) => {
+     *   socket.emit("error", { message: err.message })
+     * })
+     */
+    hook(type: "connection", handler: ArkosGatewayConnectionHandler): this;
+    hook(type: "disconnect", handler: ArkosGatewayConnectionHandler): this;
+    hook(type: "error", handler: ArkosGatewayErrorHandler): this;
+    /**
+     * Wire this gateway into a Socket.io `Server` instance.
+     * Registers the namespace, auth middleware, rate limiting, pipes,
+     * and all event handlers — then recurses into child gateways.
+     *
+     * @example
+     * const io = new Server(server)
+     * chatGateway.register(io)
+     *
+     * // with options
+     * chatGateway.register(io, { store: redisStore })
+     *
+     * // run code once the gateway is mounted
+     * chatGateway.register(io, { store: redisStore }, () => {
+     *   console.log("gateway mounted on", chatGateway.nsp.name)
+     * })
+     *
+     * The callback overload is available from 1.8.0-rc.
+     */
+    register(io: Server, callback?: () => void): void;
+    register(io: Server, options: ArkosGatewayRegisterOptions, callback?: () => void): void;
+    private _register;
+}
+/**
+ * Creates an Arkos WebSocket Gateway backed by Socket.io.
+ *
+ * Handles authentication, validation, rate limiting, pipes,
+ * error handling, and nested gateways — all declaratively.
+ * Enhances every connected socket with `socket.user()`, `socket.peer()`,
+ * `socket.retry()`, and automatic `_meta` injection on outgoing emits.
+ *
+ * @example
+ * ```ts
+ * const chatGateway = ArkosGateway({
+ *   name: "chat",
+ *   authentication: true,
+ *   rateLimit: { windowMs: 60_000, max: 200 },
+ * })
+ *
+ * chatGateway.on(
+ *   { event: "send_message", validation: MessageSchema, ack: true },
+ *   (socket, data, ack) => {
+ *     socket.to(data.room).emit("receive_message", data)
+ *     ack?.({ status: "ok" })
+ *   }
+ * )
+ * ```
+ * @since 1.7.0-canary.18
+ * @see {@link https://www.arkosjs.com/docs/core-concepts/components/gateways}
+ */
+declare function ArkosGateway(config: ArkosGatewayConfig): IArkosGateway;
+export default ArkosGateway;

package/dist/types/components/arkos-gateway/socket-extensions.d.ts

@@ -0,0 +1,80 @@
+import { ArkosEmitTarget, ArkosSocket, ArkosUserTarget } from "./types";
+import { Socket } from "socket.io";
+export declare class ArkosBroadcastOperatorImpl {
+    private readonly sockets;
+    private readonly operator;
+    constructor(sockets: Map<string, Socket>, operator: ArkosEmitTarget);
+    user(userId: string): ArkosUserTarget;
+    /**
+     * Returns all unique user IDs currently in the target room(s).
+     * Uses the internal `arkos::user:` room convention to map sockets to users.
+     *
+     * @example
+     * const users = await socket.to("room-123").users()
+     * console.log(users) // ['user-1', 'user-2']
+     */
+    users(): Promise<string[]>;
+    /**
+     * Excludes sockets from the broadcast.
+     * Accepts a room name, socket ID, array of rooms/IDs, or `{ user: string | string[] }`
+     * to exclude all sockets belonging to one or more users.
+     *
+     * @example
+     * socket.to("room-101").except("room-102").emit("foo", data)
+     * socket.broadcast.except({ user: userId }).emit("foo", data)
+     * socket.broadcast.except({ user: [id1, id2] }).emit("foo", data)
+     */
+    except(room: string | string[] | {
+        user: string | string[];
+    }): ArkosBroadcastOperatorImpl;
+    /**
+     * Emits an event to the target. `_meta` (`mid` + `timestamp`) is injected automatically.
+     *
+     * @example
+     * socket.to("room-101").emit("message", { text: "hello" })
+     * socket.broadcast.emit("announcement", data)
+     */
+    emit(event: string, ...args: any[]): boolean;
+    /**
+     * Sets the volatile flag — the event may be dropped if the client is not ready.
+     * Useful for high-frequency non-critical events like cursor positions or typing indicators.
+     *
+     * @example
+     * socket.to("room-101").volatile.emit("cursor", position)
+     */
+    get volatile(): ArkosBroadcastOperatorImpl;
+    /**
+     * Sets the compress flag for the next emission.
+     *
+     * @example
+     * socket.broadcast.compress(false).emit("ping", data)
+     */
+    compress(value: boolean): ArkosBroadcastOperatorImpl;
+    /**
+     * Sets a timeout in milliseconds for `emitWithAck`.
+     * Rejects the promise if no client acknowledges within the given delay.
+     *
+     * @example
+     * socket.to("room-101").timeout(3000).emitWithAck("confirm", data)
+     */
+    timeout(ms: number): ArkosBroadcastOperatorImpl;
+    /**
+     * Emits an event and waits for acknowledgements from all matched clients.
+     * `_meta` is injected automatically. Use `.timeout(ms)` to avoid hanging indefinitely.
+     *
+     * @example
+     * const responses = await socket.to("room-101").timeout(3000).emitWithAck("confirm", data)
+     */
+    emitWithAck(event: string, ...args: any[]): Promise<any[]>;
+}
+/**
+ * Mounts Arkos socket extensions and patches emit methods for automatic `_meta` injection.
+ * Called once by the gateway at connection time, right after injecting `_arkos`.
+ *
+ * Patches: `emit`, `emitWithAck`, `to()`, `timeout()`, `broadcast`
+ * Mounts: `user()`, `peer()`, `retry()`
+ *
+ * @internal
+ * @since 1.7.0-canary.29
+ */
+export declare function mountArkosSocketExtensions(socket: ArkosSocket): void;