diff --git a/types/koa-session/index.d.ts b/types/koa-session/index.d.ts index bdc7d6b25b..d05ce7055e 100644 --- a/types/koa-session/index.d.ts +++ b/types/koa-session/index.d.ts @@ -1,13 +1,14 @@ -// Type definitions for koa-session 3.0 +// Type definitions for koa-session 5.7 // Project: https://github.com/koajs/session // Definitions by: Yu Hsin Lu -// Definitions: https://github.com/kerol2r20/DefinitelyTyped +// Tomek Łaziuk +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.3 /* =================== USAGE =================== import session = require("koa-session"); - import Koa = require('koa'); + import Koa = require("koa"); var app = new Koa(); app.use(session(app)); @@ -17,38 +18,141 @@ import * as Koa from "koa"; declare namespace session { - interface sessionConfig { + /** + * Session model. + */ + interface Session { + /** + * JSON representation of the session. + */ + toJSON(): object; + + /** + * alias to `toJSON` + */ + inspect(): object; + + /** + * Return how many values there are in the session object. + * Used to see if it"s "populated". + */ + readonly length: number; + + /** + * populated flag, which is just a boolean alias of .length. + */ + readonly populated: boolean; + + /** + * get/set session maxAge + */ + maxAge: opts["maxAge"]; + + /** + * save this session no matter whether it is populated + */ + save(): void; + + /** + * allow to put any value on session object + */ + [_: string]: any; + } + + interface ContextSession { + ctx: Koa.Context; + + app: Koa.Context["app"]; + + opts: opts; + + store: stores; + + session: Session | false; + + /** + * internal logic of `ctx.session` + */ + get(): Session; + + /** + * internal logic of `ctx.session=` + */ + set(val: any): void; + + prevHash: string; + + /** + * init session from external store + * will be called in the front of session middleware + */ + initFromExternal(): Promise; + + /** + * Commit the session changes or removal. + */ + commit(): Promise; + } + + interface util { + /** + * Decode the base64 cookie value to an object. + */ + decode(str: string): object; + + /** + * Encode an object into a base64-encoded JSON string. + */ + encode(obj: object): string; + + hash(sess: any): string; + } + + interface opts { /** * cookie key (default is koa:sess) */ - key?: string; + key: string; /** * maxAge in ms (default is 1 days) - * 'session' will result in a cookie that expires when session/browser is closed + * "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?: number | 'session'; + maxAge?: number | "session"; /** * can overwrite or not (default true) */ - overwrite?: boolean; + overwrite: boolean; /** * httpOnly or not (default true) */ - httpOnly?: boolean; + httpOnly: boolean; /** * signed or not (default true) */ - signed?: boolean; + signed: boolean; /** - * (boolean) 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 + * custom encode method + */ + encode: util["encode"]; + + /** + * custom decode method + */ + decode: util["decode"]; + + /** + * The way of generating external session id is controlled by the options.genid, which defaults to Date.now() + "-" + uid.sync(24). + */ + genid: () => string; + + /** + * 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?: boolean; @@ -57,59 +161,60 @@ declare namespace session { */ store?: stores; + /** + * If your session store requires data or utilities from context, opts.ContextStore is alse supported. + * ContextStore must be a class which claims three instance methods demonstrated above. + * new ContextStore(ctx) will be executed on every request. + */ + ContextStore?: { new(): stores }; + + /** + * If you want to add prefix for all external session id, you can use options.prefix, it will not work if options.genid present. + */ + prefix?: string; + /** * Hook: valid session value before use it */ - valid?(ctx: Koa.Context, session: sessionProps): void; + valid?(ctx: Koa.Context, session: Partial): void; /** * Hook: before save session */ - beforeSave?(ctx: Koa.Context, session: sessionProps): void; - } - interface sessionProps { - /** - * Returns true if the session is new - */ - isNew: boolean; - - /** - * Set cookie's maxAge - */ - maxAge: number; - - /** - * Save this session no matter whether it is populated - */ - save(): void; - [propName: string]: any; + beforeSave?(ctx: Koa.Context, session: Session): void; } interface stores { /** * get session object by key */ - get(key: any): any; + get(key: string, maxAge: opts["maxAge"], data: { rolling: opts["rolling"] }): any; /** * set session object for key, with a maxAge (in ms) */ - set(key: any, sess: any, maxAge?: number): any; + set(key: string, sess: Partial & { _expire?: number, _maxAge?: number }, maxAge: opts["maxAge"], data: { changed: boolean; rolling: opts["rolling"] }): any; /** * destroy session for key */ - destroy(key: any): void; + destroy(key: string): any; } } -declare function session(CONFIG: session.sessionConfig, app: Koa): Koa.Middleware; +declare function session(CONFIG: Partial, app: Koa): Koa.Middleware; declare function session(app: Koa): Koa.Middleware; -declare module 'koa' { +declare module "koa" { interface Context { - session: session.sessionProps | null; + session: session.Session | undefined; + readonly sessionOptions: session.opts | undefined; + } + + interface Application { + on(name: "session:missed" | "session:expired" | "session:invalid", data: { key?: string, value?: Partial, ctx: Context }): void; + once(name: "session:missed" | "session:expired" | "session:invalid", data: { key?: string, value?: Partial, ctx: Context }): void; } } diff --git a/types/koa-session/koa-session-tests.ts b/types/koa-session/koa-session-tests.ts index ef3ddc6a09..02f944ae66 100644 --- a/types/koa-session/koa-session-tests.ts +++ b/types/koa-session/koa-session-tests.ts @@ -1,8 +1,42 @@ import * as Koa from 'koa'; import * as session from 'koa-session'; +import * as ContextSession from "koa-session/lib/context"; + +import { + encode, + decode, + hash, +} from "koa-session/lib/util"; + +encode({ a: "b" }); + +decode("123"); + +hash("abc"); const app = new Koa(); -app.use(session(app)); +app.use(session({ + valid: (ctx, sess) => { + const { session: s } = ctx; + if (s) { + s.sess = "validated"; + s.save(); + return true; + } + return false; + }, + store: { + get: async (key) => { + return "abc"; + }, + set: (key, val) => { + console.log(key, val); + }, + destroy: (key) => { + console.log(key); + }, + }, +}, app)); app.listen(3000); diff --git a/types/koa-session/lib/context.d.ts b/types/koa-session/lib/context.d.ts new file mode 100644 index 0000000000..16d4388be1 --- /dev/null +++ b/types/koa-session/lib/context.d.ts @@ -0,0 +1,7 @@ +import { + ContextSession, +} from ".."; + +declare const c: ContextSession; + +export = c; diff --git a/types/koa-session/lib/session.d.ts b/types/koa-session/lib/session.d.ts new file mode 100644 index 0000000000..60e557bce8 --- /dev/null +++ b/types/koa-session/lib/session.d.ts @@ -0,0 +1,7 @@ +import { + Session, +} from ".."; + +declare const s: Session; + +export = s; diff --git a/types/koa-session/lib/util.d.ts b/types/koa-session/lib/util.d.ts new file mode 100644 index 0000000000..4d9a77752f --- /dev/null +++ b/types/koa-session/lib/util.d.ts @@ -0,0 +1,7 @@ +import { + util, +} from ".."; + +declare const u: util; + +export = u; diff --git a/types/koa-session/tsconfig.json b/types/koa-session/tsconfig.json index eea5fc5068..df47800012 100644 --- a/types/koa-session/tsconfig.json +++ b/types/koa-session/tsconfig.json @@ -18,6 +18,9 @@ }, "files": [ "index.d.ts", + "lib/context.d.ts", + "lib/session.d.ts", + "lib/util.d.ts", "koa-session-tests.ts" ] -} \ No newline at end of file +}