alepha/server/cookies.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core1 from "alepha";
import * as _alepha_core0 from "alepha";
import { Alepha, Descriptor, KIND, Static, TSchema } from "alepha";
import { DateTimeProvider, DurationLike } from "alepha/datetime";

//#region src/services/CookieParser.d.ts
declare class CookieParser {
  parseRequestCookies(header: string): Record<string, string>;
  serializeResponseCookies(cookies: Record<string, Cookie | null>, isHttps: boolean): string[];
  cookieToString(name: string, cookie: Cookie, isHttps?: boolean): string;
}
//# sourceMappingURL=CookieParser.d.ts.map
//#endregion
//#region src/providers/ServerCookiesProvider.d.ts
declare const envSchema: _alepha_core1.TObject<{
  /**
   *  A 32-byte secret key used for cookie encryption and signing. MUST be set for `encrypt` or `sign` to work.
   */
  COOKIE_SECRET: _alepha_core1.TOptional<_alepha_core1.TString>;
}>;
declare module "alepha" {
  interface Env extends Partial<Static<typeof envSchema>> {}
}
declare class ServerCookiesProvider {
  protected readonly alepha: Alepha;
  protected readonly log: _alepha_core1.Logger;
  protected readonly env: {
    COOKIE_SECRET?: string | undefined;
  };
  protected readonly cookieParser: CookieParser;
  protected readonly dateTimeProvider: DateTimeProvider;
  protected readonly ALGORITHM = "aes-256-gcm";
  protected readonly IV_LENGTH = 16;
  protected readonly AUTH_TAG_LENGTH = 16;
  protected readonly SIGNATURE_LENGTH = 32;
  readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
  readonly onSend: _alepha_core1.HookDescriptor<"server:onSend">;
  protected getCookiesFromContext(cookies?: Cookies): Cookies;
  getCookie<T extends TSchema>(name: string, options: CookieDescriptorOptions<T>, contextCookies?: Cookies): Static<T> | undefined;
  setCookie<T extends TSchema>(name: string, options: CookieDescriptorOptions<T>, data: Static<T>, contextCookies?: Cookies): void;
  deleteCookie<T extends TSchema>(name: string, contextCookies?: Cookies): void;
  protected encrypt(text: string): string;
  protected decrypt(encryptedText: string): string;
  secretKey(): string;
  protected sign(data: string): string;
}
//#endregion
//#region src/descriptors/$cookie.d.ts
/**
 * Declares a type-safe, configurable HTTP cookie.
 * This descriptor provides methods to get, set, and delete the cookie
 * within the server request/response cycle.
 */
declare const $cookie: {
  <T extends TSchema>(options: CookieDescriptorOptions<T>): AbstractCookieDescriptor<T>;
  [KIND]: typeof CookieDescriptor;
};
interface CookieDescriptorOptions<T extends TSchema> {
  /** The schema for the cookie's value, used for validation and type safety. */
  schema: T;
  /** The name of the cookie. */
  name?: string;
  /** The cookie's path. Defaults to "/". */
  path?: string;
  /** Time-to-live for the cookie. Maps to `Max-Age`. */
  ttl?: DurationLike;
  /** If true, the cookie is only sent over HTTPS. Defaults to true in production. */
  secure?: boolean;
  /** If true, the cookie cannot be accessed by client-side scripts. */
  httpOnly?: boolean;
  /** SameSite policy for the cookie. Defaults to "lax". */
  sameSite?: "strict" | "lax" | "none";
  /** The domain for the cookie. */
  domain?: string;
  /** If true, the cookie value will be compressed using zlib. */
  compress?: boolean;
  /** If true, the cookie value will be encrypted. Requires `COOKIE_SECRET` env var. */
  encrypt?: boolean;
  /** If true, the cookie will be signed to prevent tampering. Requires `COOKIE_SECRET` env var. */
  sign?: boolean;
}
interface AbstractCookieDescriptor<T extends TSchema> {
  readonly name: string;
  readonly options: CookieDescriptorOptions<T>;
  set(value: Static<T>, options?: {
    cookies?: Cookies;
    ttl?: DurationLike;
  }): void;
  get(options?: {
    cookies?: Cookies;
  }): Static<T> | undefined;
  del(options?: {
    cookies?: Cookies;
  }): void;
}
declare class CookieDescriptor<T extends TSchema> extends Descriptor<CookieDescriptorOptions<T>> implements AbstractCookieDescriptor<T> {
  protected readonly serverCookiesProvider: ServerCookiesProvider;
  get schema(): T;
  get name(): string;
  /**
   * Sets the cookie with the given value in the current request's response.
   */
  set(value: Static<T>, options?: {
    cookies?: Cookies;
    ttl?: DurationLike;
  }): void;
  /**
   * Gets the cookie value from the current request. Returns undefined if not found or invalid.
   */
  get(options?: {
    cookies?: Cookies;
  }): Static<T> | undefined;
  /**
   * Deletes the cookie in the current request's response.
   */
  del(options?: {
    cookies?: Cookies;
  }): void;
}
interface Cookies {
  req: Record<string, string>;
  res: Record<string, Cookie | null>;
}
interface Cookie {
  value: string;
  path?: string;
  maxAge?: number;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: "strict" | "lax" | "none";
  domain?: string;
}
//# sourceMappingURL=$cookie.d.ts.map
//#endregion
//#region src/index.d.ts
declare module "alepha/server" {
  interface ServerRequest {
    cookies: Cookies;
  }
}
/**
 * Provides HTTP cookie management capabilities for server requests and responses with type-safe cookie descriptors.
 *
 * The server-cookies module enables declarative cookie handling using the `$cookie` descriptor on class properties.
 * It offers automatic cookie parsing, secure cookie configuration, and seamless integration with server routes
 * for managing user sessions, preferences, and authentication tokens.
 *
 * @see {@link $cookie}
 * @module alepha.server.cookies
 */
declare const AlephaServerCookies: _alepha_core0.Service<_alepha_core0.Module>;
//# sourceMappingURL=index.d.ts.map

//#endregion
export { $cookie, AbstractCookieDescriptor, AlephaServerCookies, Cookie, CookieDescriptor, CookieDescriptorOptions, Cookies, ServerCookiesProvider };
//# sourceMappingURL=index.d.ts.map