koa-session
Version:
Koa cookie session middleware with external store support
270 lines (269 loc) • 10.1 kB
TypeScript
import z from 'zod';
export declare const SessionOptions: z.ZodObject<{
/**
* cookie key
* Default is `koa.sess`
*/
key: z.ZodDefault<z.ZodString>;
/**
* maxAge in ms
* Default is `86400000`, one day
* If set to 'session' will result in a cookie that expires when session/browser is closed
*
* Warning: If a session cookie is stolen, this cookie will never expire
*/
maxAge: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodLiteral<"session">]>>;
/**
* automatically commit headers
* Default is `true`
*/
autoCommit: z.ZodDefault<z.ZodBoolean>;
/**
* cookie value can overwrite or not
* Default is `true`
*/
overwrite: z.ZodDefault<z.ZodBoolean>;
/**
* httpOnly or not
* Default is `true`
*/
httpOnly: z.ZodDefault<z.ZodBoolean>;
/**
* signed or not
* Default is `true`
*/
signed: z.ZodDefault<z.ZodBoolean>;
/**
* Force a session identifier cookie to be set on every response.
* The expiration is reset to the original `maxAge`, resetting the expiration countdown.
* Default is `false`
*/
rolling: z.ZodDefault<z.ZodBoolean>;
/**
* renew session when session is nearly expired, so we can always keep user logged in.
* Default is `false`
*/
renew: z.ZodDefault<z.ZodBoolean>;
/**
* secure cookie
* Default is `undefined`, will be set to `true` if the connection is over HTTPS, otherwise `false`.
*/
secure: z.ZodOptional<z.ZodBoolean>;
/**
* session cookie sameSite options
* Default is `undefined`, meaning don't set it
*/
sameSite: z.ZodOptional<z.ZodString>;
/**
* External key is used the cookie by default,
* but you can use `options.externalKey` to customize your own external key methods.
*/
externalKey: z.ZodOptional<z.ZodObject<{
/**
* get the external key
* `(ctx) => string`
*/
get: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodString>;
/**
* set the external key
* `(ctx, key) => void`
*/
set: z.ZodFunction<z.ZodTuple<[z.ZodAny, z.ZodString], z.ZodUnknown>, z.ZodVoid>;
}, "strip", z.ZodTypeAny, {
set: (args_0: any, args_1: string, ...args: unknown[]) => void;
get: (args_0: any, ...args: unknown[]) => string;
}, {
set: (args_0: any, args_1: string, ...args: unknown[]) => void;
get: (args_0: any, ...args: unknown[]) => string;
}>>;
/**
* session storage is dependent on your external store
*/
store: z.ZodOptional<z.ZodObject<{
/**
* get session data by key
* `(key, maxAge, { rolling, ctx }) => sessionData | Promise<sessionData>`
*/
get: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodNumber, z.ZodObject<{
rolling: z.ZodBoolean;
ctx: z.ZodAny;
}, "strip", z.ZodTypeAny, {
rolling: boolean;
ctx?: any;
}, {
rolling: boolean;
ctx?: any;
}>], z.ZodUnknown>, z.ZodPromise<z.ZodAny>>;
/**
* set session data for key, with a `maxAge` (in ms)
* `(key, sess, maxAge, { rolling, changed, ctx }) => void | Promise<void>`
*/
set: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodAny, z.ZodNumber, z.ZodObject<{
rolling: z.ZodBoolean;
changed: z.ZodBoolean;
ctx: z.ZodAny;
}, "strip", z.ZodTypeAny, {
rolling: boolean;
changed: boolean;
ctx?: any;
}, {
rolling: boolean;
changed: boolean;
ctx?: any;
}>], z.ZodUnknown>, z.ZodPromise<z.ZodVoid>>;
/**
* destroy session data for key
* `(key, { ctx })=> void | Promise<void>`
*/
destroy: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodObject<{
ctx: z.ZodAny;
}, "strip", z.ZodTypeAny, {
ctx?: any;
}, {
ctx?: any;
}>], z.ZodUnknown>, z.ZodPromise<z.ZodVoid>>;
}, "strip", z.ZodTypeAny, {
set: (args_0: string, args_1: any, args_2: number, args_3: {
rolling: boolean;
changed: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
get: (args_0: string, args_1: number, args_2: {
rolling: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<any>;
destroy: (args_0: string, args_1: {
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
}, {
set: (args_0: string, args_1: any, args_2: number, args_3: {
rolling: boolean;
changed: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
get: (args_0: string, args_1: number, args_2: {
rolling: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<any>;
destroy: (args_0: string, args_1: {
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
}>>;
/**
* If your session store requires data or utilities from context, `opts.ContextStore` is also supported.
* `ContextStore` must be a class which claims three instance methods demonstrated above.
* `new ContextStore(ctx)` will be executed on every request.
*/
ContextStore: z.ZodOptional<z.ZodAny>;
encode: z.ZodDefault<z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodString>>>;
decode: z.ZodDefault<z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>>;
/**
* If you want to generate a new session id, you can use `genid` option to customize it.
* Default is a function that uses `randomUUID()`.
* `(ctx) => string`
*/
genid: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodString>>;
/**
* If you want to prefix the session id, you can use `prefix` option to customize it.
* It will not work if `options.genid(ctx)` present.
*/
prefix: z.ZodOptional<z.ZodString>;
/**
* valid session value before use it
* `(ctx, sessionData) => boolean`
*/
valid: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny, z.ZodAny], z.ZodUnknown>, z.ZodAny>>;
/**
* hook before save session
* `(ctx, sessionModel) => void`
*/
beforeSave: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodAny, z.ZodAny], z.ZodUnknown>, z.ZodVoid>>;
}, "strip", z.ZodTypeAny, {
key: string;
autoCommit: boolean;
overwrite: boolean;
httpOnly: boolean;
signed: boolean;
rolling: boolean;
renew: boolean;
encode: (args_0: any, ...args: unknown[]) => string;
decode: (args_0: string, ...args: unknown[]) => any;
maxAge?: number | "session" | undefined;
externalKey?: {
set: (args_0: any, args_1: string, ...args: unknown[]) => void;
get: (args_0: any, ...args: unknown[]) => string;
} | undefined;
valid?: ((args_0: any, args_1: any, ...args: unknown[]) => any) | undefined;
secure?: boolean | undefined;
sameSite?: string | undefined;
store?: {
set: (args_0: string, args_1: any, args_2: number, args_3: {
rolling: boolean;
changed: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
get: (args_0: string, args_1: number, args_2: {
rolling: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<any>;
destroy: (args_0: string, args_1: {
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
} | undefined;
ContextStore?: any;
genid?: ((args_0: any, ...args: unknown[]) => string) | undefined;
prefix?: string | undefined;
beforeSave?: ((args_0: any, args_1: any, ...args: unknown[]) => void) | undefined;
}, {
maxAge?: number | "session" | undefined;
externalKey?: {
set: (args_0: any, args_1: string, ...args: unknown[]) => void;
get: (args_0: any, ...args: unknown[]) => string;
} | undefined;
key?: string | undefined;
valid?: ((args_0: any, args_1: any, ...args: unknown[]) => any) | undefined;
autoCommit?: boolean | undefined;
overwrite?: boolean | undefined;
httpOnly?: boolean | undefined;
signed?: boolean | undefined;
rolling?: boolean | undefined;
renew?: boolean | undefined;
secure?: boolean | undefined;
sameSite?: string | undefined;
store?: {
set: (args_0: string, args_1: any, args_2: number, args_3: {
rolling: boolean;
changed: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
get: (args_0: string, args_1: number, args_2: {
rolling: boolean;
ctx?: any;
}, ...args: unknown[]) => Promise<any>;
destroy: (args_0: string, args_1: {
ctx?: any;
}, ...args: unknown[]) => Promise<void>;
} | undefined;
ContextStore?: any;
encode?: ((args_0: any, ...args: unknown[]) => string) | undefined;
decode?: ((args_0: string, ...args: unknown[]) => any) | undefined;
genid?: ((args_0: any, ...args: unknown[]) => string) | undefined;
prefix?: string | undefined;
beforeSave?: ((args_0: any, args_1: any, ...args: unknown[]) => void) | undefined;
}>;
export type SessionOptions = z.infer<typeof SessionOptions>;
export type CreateSessionOptions = Partial<SessionOptions>;
type Middleware = (ctx: any, next: any) => Promise<void>;
/**
* Initialize session middleware with `opts`:
*
* - `key` session cookie name ["koa.sess"]
* - all other options are passed as cookie options
*
* @param {Object} [opts] session options
* @param {Application} app koa application instance
* @public
*/
export declare function createSession(opts: CreateSessionOptions, app: any): Middleware;
export declare function createSession(app: any, opts?: CreateSessionOptions): Middleware;
export default createSession;