[koa-session] upgrade typings to v5.7 (#22882)

* upgrade typings

* version bump

* dtslint

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 <https://github.com/kerol2r20>
-// Definitions: https://github.com/kerol2r20/DefinitelyTyped
+//                 Tomek Łaziuk <https://github.com/tlaziuk>
+// 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<void>;
+
+        /**
+         * Commit the session changes or removal.
+         */
+        commit(): Promise<void>;
+    }
+
+    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<Session>): 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<Session> & { _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<session.opts>, 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<session.Session>, ctx: Context }): void;
+        once(name: "session:missed" | "session:expired" | "session:invalid", data: { key?: string, value?: Partial<session.Session>, ctx: Context }): void;
     }
 }
 

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);

types/koa-session/lib/context.d.ts

@@ -0,0 +1,7 @@
+import {
+    ContextSession,
+} from "..";
+
+declare const c: ContextSession;
+
+export = c;

types/koa-session/lib/session.d.ts

@@ -0,0 +1,7 @@
+import {
+    Session,
+} from "..";
+
+declare const s: Session;
+
+export = s;

types/koa-session/lib/util.d.ts

@@ -0,0 +1,7 @@
+import {
+    util,
+} from "..";
+
+declare const u: util;
+
+export = u;

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"
     ]
-}
+}