@lolyjs/core 0.2.0-alpha.8 → 0.3.0-alpha.0

package/dist/index.types-Duhjyfit.d.mts

@@ -0,0 +1,280 @@
+import { Request, Response } from 'express';
+
+type GenerateStaticParams = () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
+/**
+ * Response class for redirects in server loaders.
+ * Use ctx.Redirect() to return this from getServerSideProps.
+ */
+declare class RedirectResponse {
+    destination: string;
+    permanent: boolean;
+    constructor(destination: string, permanent?: boolean);
+}
+/**
+ * Response class for not found in server loaders.
+ * Use ctx.NotFound() to return this from getServerSideProps.
+ */
+declare class NotFoundResponse {
+    constructor();
+}
+/**
+ * Base context interface with common fields shared by ServerContext and ApiContext.
+ * This reduces duplication and ensures consistency across context types.
+ */
+interface BaseContext {
+    /** Express request object */
+    req: Request;
+    /** Express response object */
+    res: Response;
+    /** Route parameters extracted from the URL pattern */
+    params: Record<string, string>;
+    /** Current pathname (may be rewritten path for rewrites) */
+    pathname: string;
+    /** Local storage for passing data between middlewares and handlers */
+    locals: Record<string, any>;
+}
+interface ServerContext extends BaseContext {
+    /**
+     * Redirect helper method. Returns a RedirectResponse that will be handled automatically.
+     * @example
+     * if (!user) {
+     *   return ctx.Redirect("/login");
+     * }
+     */
+    Redirect: (destination: string, permanent?: boolean) => RedirectResponse;
+    /**
+     * Not found helper method. Returns a NotFoundResponse that will be handled automatically.
+     * @example
+     * if (!post) {
+     *   return ctx.NotFound();
+     * }
+     */
+    NotFound: () => NotFoundResponse;
+}
+interface WssActions {
+    /**
+     * Emit to current socket only (reply)
+     */
+    reply(event: string, payload?: any): void;
+    /**
+     * Emit an event to all clients in the namespace
+     */
+    emit: (event: string, ...args: any[]) => void;
+    /**
+     * Emit to everyone except current socket
+     */
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
+     */
+    leave(room: string): Promise<void>;
+    /**
+     * Emit to a specific room
+     */
+    toRoom(room: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit to a specific user (by userId)
+     * Uses presence mapping to find user's sockets
+     */
+    toUser(userId: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit error event (reserved event: __loly:error)
+     */
+    error(code: string, message: string, details?: any): void;
+    /**
+     * Emit an event to a specific socket by Socket.IO socket ID
+     * @deprecated Use toUser() for user targeting
+     */
+    emitTo?: (socketId: string, event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific client by custom clientId
+     * @deprecated Use toUser() for user targeting
+     */
+    emitToClient?: (clientId: string, event: string, ...args: any[]) => void;
+}
+/**
+ * Route middleware function type.
+ * Middlewares run before getServerSideProps and can modify ctx.locals, set headers, redirect, etc.
+ *
+ * @param ctx - Server context with optional theme
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Simple middleware that adds data to ctx.locals
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getUser(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ *
+ * @example
+ * // Middleware that redirects
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     if (!ctx.locals.user) {
+ *       ctx.res.redirect('/login');
+ *       return; // Don't call next() if redirecting
+ *     }
+ *     await next();
+ *   }
+ * ];
+ */
+type RouteMiddleware = (ctx: ServerContext & {
+    theme?: string;
+}, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Global middleware type for middlewares that run before route matching.
+ * These middlewares establish context (ctx.locals) and always execute (both SSR and SPA navigation).
+ *
+ * @example
+ * // global.middleware.ts
+ * export const globalMiddlewares: GlobalMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getSession(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ */
+type GlobalMiddleware = (ctx: ServerContext, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Result returned by a server loader (getServerSideProps).
+ * @template TProps - Type of props that will be passed to the component (defaults to Record<string, any>)
+ */
+interface LoaderResult<TProps extends Record<string, any> = Record<string, any>> {
+    pathname?: string;
+    props?: TProps;
+    metadata?: PageMetadata | null;
+    className?: string;
+    theme?: string;
+}
+/**
+ * Server loader function type (getServerSideProps).
+ * This function is exported from server.hook.ts files.
+ *
+ * @template TProps - Type of props that will be returned (defaults to Record<string, any>)
+ *
+ * @example
+ * // Typed loader
+ * export const getServerSideProps: ServerLoader<{ user: User; posts: Post[] }> = async (ctx) => ({
+ *   props: { user: await getUser(), posts: await getPosts() }
+ * });
+ *
+ * @example
+ * // Untyped loader (backward compatible)
+ * export const getServerSideProps: ServerLoader = async (ctx) => ({
+ *   props: { any: 'data' }
+ * });
+ */
+type ServerLoader<TProps extends Record<string, any> = Record<string, any>> = (ctx: ServerContext) => Promise<LoaderResult<TProps> | RedirectResponse | NotFoundResponse>;
+/**
+ * Comprehensive page metadata for SEO and social sharing.
+ * Supports standard HTML meta tags, Open Graph, Twitter Cards, and more.
+ */
+interface PageMetadata {
+    /** Page title (sets <title> tag) */
+    title?: string;
+    /** Page description (sets <meta name="description">) */
+    description?: string;
+    /** Language code (sets <html lang="...">) */
+    lang?: string;
+    /** Canonical URL (sets <link rel="canonical">) */
+    canonical?: string;
+    /** Robots directive (sets <meta name="robots">) */
+    robots?: string;
+    /** Theme color (sets <meta name="theme-color">) */
+    themeColor?: string;
+    /** Viewport configuration (sets <meta name="viewport">) */
+    viewport?: string;
+    /** Open Graph metadata for social sharing */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        type?: string;
+        url?: string;
+        image?: string | {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        };
+        siteName?: string;
+        locale?: string;
+    };
+    /** Twitter Card metadata */
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player";
+        title?: string;
+        description?: string;
+        image?: string;
+        imageAlt?: string;
+        site?: string;
+        creator?: string;
+    };
+    /** Additional custom meta tags */
+    metaTags?: {
+        name?: string;
+        property?: string;
+        httpEquiv?: string;
+        content: string;
+    }[];
+    /** Additional link tags (e.g., preconnect, dns-prefetch) */
+    links?: {
+        rel: string;
+        href: string;
+        as?: string;
+        crossorigin?: string;
+        type?: string;
+    }[];
+}
+type MetadataLoader = (ctx: ServerContext) => PageMetadata | Promise<PageMetadata>;
+interface ApiContext extends BaseContext {
+    /**
+     * Response helper method. Sends a JSON response with optional status code.
+     * @example
+     * return ctx.Response({ user }, 200);
+     * return ctx.Response({ error: "Not found" }, 404);
+     */
+    Response: (body?: any, status?: number) => Response<any, Record<string, any>>;
+    /**
+     * Not found helper method. Sends a 404 JSON response.
+     * @example
+     * return ctx.NotFound({ error: "Resource not found" });
+     */
+    NotFound: (body?: any) => Response<any, Record<string, any>>;
+}
+/**
+ * API middleware function type.
+ * Middlewares run before the API handler and can modify ctx.locals, set headers, etc.
+ *
+ * @param ctx - API context
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Authentication middleware
+ * export const middlewares: ApiMiddleware[] = [
+ *   async (ctx, next) => {
+ *     const token = ctx.req.headers.authorization;
+ *     if (!token) {
+ *       return ctx.Response({ error: 'Unauthorized' }, 401);
+ *     }
+ *     ctx.locals.user = await verifyToken(token);
+ *     await next();
+ *   }
+ * ];
+ */
+type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+
+export { type ApiMiddleware as A, type GlobalMiddleware as G, type LoaderResult as L, type MetadataLoader as M, NotFoundResponse as N, type PageMetadata as P, type RouteMiddleware as R, type ServerContext as S, type WssActions as W, type ApiContext as a, type GenerateStaticParams as b, type ServerLoader as c, RedirectResponse as d };

package/dist/index.types-Duhjyfit.d.ts

@@ -0,0 +1,280 @@
+import { Request, Response } from 'express';
+
+type GenerateStaticParams = () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
+/**
+ * Response class for redirects in server loaders.
+ * Use ctx.Redirect() to return this from getServerSideProps.
+ */
+declare class RedirectResponse {
+    destination: string;
+    permanent: boolean;
+    constructor(destination: string, permanent?: boolean);
+}
+/**
+ * Response class for not found in server loaders.
+ * Use ctx.NotFound() to return this from getServerSideProps.
+ */
+declare class NotFoundResponse {
+    constructor();
+}
+/**
+ * Base context interface with common fields shared by ServerContext and ApiContext.
+ * This reduces duplication and ensures consistency across context types.
+ */
+interface BaseContext {
+    /** Express request object */
+    req: Request;
+    /** Express response object */
+    res: Response;
+    /** Route parameters extracted from the URL pattern */
+    params: Record<string, string>;
+    /** Current pathname (may be rewritten path for rewrites) */
+    pathname: string;
+    /** Local storage for passing data between middlewares and handlers */
+    locals: Record<string, any>;
+}
+interface ServerContext extends BaseContext {
+    /**
+     * Redirect helper method. Returns a RedirectResponse that will be handled automatically.
+     * @example
+     * if (!user) {
+     *   return ctx.Redirect("/login");
+     * }
+     */
+    Redirect: (destination: string, permanent?: boolean) => RedirectResponse;
+    /**
+     * Not found helper method. Returns a NotFoundResponse that will be handled automatically.
+     * @example
+     * if (!post) {
+     *   return ctx.NotFound();
+     * }
+     */
+    NotFound: () => NotFoundResponse;
+}
+interface WssActions {
+    /**
+     * Emit to current socket only (reply)
+     */
+    reply(event: string, payload?: any): void;
+    /**
+     * Emit an event to all clients in the namespace
+     */
+    emit: (event: string, ...args: any[]) => void;
+    /**
+     * Emit to everyone except current socket
+     */
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
+     */
+    leave(room: string): Promise<void>;
+    /**
+     * Emit to a specific room
+     */
+    toRoom(room: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit to a specific user (by userId)
+     * Uses presence mapping to find user's sockets
+     */
+    toUser(userId: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit error event (reserved event: __loly:error)
+     */
+    error(code: string, message: string, details?: any): void;
+    /**
+     * Emit an event to a specific socket by Socket.IO socket ID
+     * @deprecated Use toUser() for user targeting
+     */
+    emitTo?: (socketId: string, event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific client by custom clientId
+     * @deprecated Use toUser() for user targeting
+     */
+    emitToClient?: (clientId: string, event: string, ...args: any[]) => void;
+}
+/**
+ * Route middleware function type.
+ * Middlewares run before getServerSideProps and can modify ctx.locals, set headers, redirect, etc.
+ *
+ * @param ctx - Server context with optional theme
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Simple middleware that adds data to ctx.locals
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getUser(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ *
+ * @example
+ * // Middleware that redirects
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     if (!ctx.locals.user) {
+ *       ctx.res.redirect('/login');
+ *       return; // Don't call next() if redirecting
+ *     }
+ *     await next();
+ *   }
+ * ];
+ */
+type RouteMiddleware = (ctx: ServerContext & {
+    theme?: string;
+}, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Global middleware type for middlewares that run before route matching.
+ * These middlewares establish context (ctx.locals) and always execute (both SSR and SPA navigation).
+ *
+ * @example
+ * // global.middleware.ts
+ * export const globalMiddlewares: GlobalMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getSession(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ */
+type GlobalMiddleware = (ctx: ServerContext, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Result returned by a server loader (getServerSideProps).
+ * @template TProps - Type of props that will be passed to the component (defaults to Record<string, any>)
+ */
+interface LoaderResult<TProps extends Record<string, any> = Record<string, any>> {
+    pathname?: string;
+    props?: TProps;
+    metadata?: PageMetadata | null;
+    className?: string;
+    theme?: string;
+}
+/**
+ * Server loader function type (getServerSideProps).
+ * This function is exported from server.hook.ts files.
+ *
+ * @template TProps - Type of props that will be returned (defaults to Record<string, any>)
+ *
+ * @example
+ * // Typed loader
+ * export const getServerSideProps: ServerLoader<{ user: User; posts: Post[] }> = async (ctx) => ({
+ *   props: { user: await getUser(), posts: await getPosts() }
+ * });
+ *
+ * @example
+ * // Untyped loader (backward compatible)
+ * export const getServerSideProps: ServerLoader = async (ctx) => ({
+ *   props: { any: 'data' }
+ * });
+ */
+type ServerLoader<TProps extends Record<string, any> = Record<string, any>> = (ctx: ServerContext) => Promise<LoaderResult<TProps> | RedirectResponse | NotFoundResponse>;
+/**
+ * Comprehensive page metadata for SEO and social sharing.
+ * Supports standard HTML meta tags, Open Graph, Twitter Cards, and more.
+ */
+interface PageMetadata {
+    /** Page title (sets <title> tag) */
+    title?: string;
+    /** Page description (sets <meta name="description">) */
+    description?: string;
+    /** Language code (sets <html lang="...">) */
+    lang?: string;
+    /** Canonical URL (sets <link rel="canonical">) */
+    canonical?: string;
+    /** Robots directive (sets <meta name="robots">) */
+    robots?: string;
+    /** Theme color (sets <meta name="theme-color">) */
+    themeColor?: string;
+    /** Viewport configuration (sets <meta name="viewport">) */
+    viewport?: string;
+    /** Open Graph metadata for social sharing */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        type?: string;
+        url?: string;
+        image?: string | {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        };
+        siteName?: string;
+        locale?: string;
+    };
+    /** Twitter Card metadata */
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player";
+        title?: string;
+        description?: string;
+        image?: string;
+        imageAlt?: string;
+        site?: string;
+        creator?: string;
+    };
+    /** Additional custom meta tags */
+    metaTags?: {
+        name?: string;
+        property?: string;
+        httpEquiv?: string;
+        content: string;
+    }[];
+    /** Additional link tags (e.g., preconnect, dns-prefetch) */
+    links?: {
+        rel: string;
+        href: string;
+        as?: string;
+        crossorigin?: string;
+        type?: string;
+    }[];
+}
+type MetadataLoader = (ctx: ServerContext) => PageMetadata | Promise<PageMetadata>;
+interface ApiContext extends BaseContext {
+    /**
+     * Response helper method. Sends a JSON response with optional status code.
+     * @example
+     * return ctx.Response({ user }, 200);
+     * return ctx.Response({ error: "Not found" }, 404);
+     */
+    Response: (body?: any, status?: number) => Response<any, Record<string, any>>;
+    /**
+     * Not found helper method. Sends a 404 JSON response.
+     * @example
+     * return ctx.NotFound({ error: "Resource not found" });
+     */
+    NotFound: (body?: any) => Response<any, Record<string, any>>;
+}
+/**
+ * API middleware function type.
+ * Middlewares run before the API handler and can modify ctx.locals, set headers, etc.
+ *
+ * @param ctx - API context
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Authentication middleware
+ * export const middlewares: ApiMiddleware[] = [
+ *   async (ctx, next) => {
+ *     const token = ctx.req.headers.authorization;
+ *     if (!token) {
+ *       return ctx.Response({ error: 'Unauthorized' }, 401);
+ *     }
+ *     ctx.locals.user = await verifyToken(token);
+ *     await next();
+ *   }
+ * ];
+ */
+type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+
+export { type ApiMiddleware as A, type GlobalMiddleware as G, type LoaderResult as L, type MetadataLoader as M, NotFoundResponse as N, type PageMetadata as P, type RouteMiddleware as R, type ServerContext as S, type WssActions as W, type ApiContext as a, type GenerateStaticParams as b, type ServerLoader as c, RedirectResponse as d };