feat: 🎸 add types from DT

lib/index.d.ts

@@ -0,0 +1,174 @@
+import { Id, PolicyOptions } from '@hapi/catbox';
+import { CachePolicyOptions, Plugin, Request, ResponseToolkit, Server, ServerOptionsCache } from '@hapi/hapi';
+
+declare namespace yar {
+    interface YarOptions {
+        /**
+         * Determines the name of the cookie used to store session information.
+         * Defaults to session.
+         */
+        name?: string | undefined;
+
+        /**
+         * maximum cookie size before using server-side storage.
+         * Defaults to 1K. Set to zero to always use server-side storage.
+         */
+        maxCookieSize?: number | undefined;
+
+        /**
+         * determines whether to store empty session before they've been modified.
+         * Defaults to true.
+         */
+        storeBlank?: boolean | undefined;
+
+        /**
+         * will cause yar to throw an exception if trying to persist to cache when the cache is unavailable.
+         * Setting this to false will allow applications using yar to run uninterrupted if the cache is not ready (however sessions will not be saving).
+         * Defaults to true.
+         */
+        errorOnCacheNotReady?: boolean | undefined;
+
+        /**
+         * hapi cache options which includes (among other options):
+         */
+        cache?: CachePolicyOptions<any> | undefined;
+
+        /**
+         * the configuration for cookie-specific features:
+         */
+        cookieOptions: {
+            /**
+             * Tells Hapi that it should not respond with a HTTP 400 error if the session cookie cannot decrypt.
+             * This could happen if the cookie is changed on the client, or more likely, if you change the cookie password in your settings.
+             * If you want to make this condition send an error like it did in prior versions, change this to `false`,
+             * but be aware that if you change your cookie password you will cause 400 errors to be returned to end users.
+             * In that case you should probably change this back to true for a short time to allow session cookies to get reset for the best user experience.
+             * Defaults to true.
+             */
+            ignoreErrors?: boolean | undefined;
+
+            /**
+             * Tells Hapi that if a session cookie is invalid for any reason,
+             * to clear it from the browser.
+             * This prevents Hapi from having to reprocess the bad cookie on future requests.
+             * In general you'll probably want this on,
+             * but if you'd prefer that session cookies be dealt with in some
+             * other way you may set this to false.
+             * Defaults to true
+             */
+            clearInvalid?: boolean | undefined;
+            /**
+             * (Required) used to encrypt and sign the cookie data.
+             * Must be at least 32 chars.
+             */
+            password: string;
+            /**
+             * determines the cookie path.
+             * Defaults to '/'.
+             */
+            path?: string | undefined;
+            /**
+             * enables the same-site cookie parameter.
+             * Default to 'Lax'.
+             */
+            isSameSite?: 'Lax' | 'Strict' | 'None' | false | undefined;
+            /**
+             * determines whether or not to transfer using TLS/SSL.
+             * Defaults to true.
+             */
+            isSecure?: boolean | undefined;
+            /**
+             * determines whether or not to set HttpOnly option in cookie.
+             * Defaults to false.
+             */
+            isHttpOnly?: boolean | undefined;
+            /**
+             * sets the time for the cookie to live in the browser, in milliseconds.
+             * Defaults to null (session time-life - cookies are deleted when the browser is closed).
+             */
+            ttl?: number | undefined;
+            /**
+             * an optional function to create custom session IDs.
+             * Must retun a string and have the signature function (request) where:
+             * request - (optional) is the original request received from the client.
+             * Defaults to uuidv4
+             */
+            customSessionIDGenerator?(req: Request): string;
+        };
+    }
+
+    interface Yar {
+        /**
+         * Session id, see `customSessionIDGenerator`.
+         */
+        readonly id: string;
+        /**
+         * clears the session and assigns a new session id.
+         */
+        reset(): void;
+        /**
+         * - assigns a value (string, object, etc) to a given key which will persist across requests. Returns the value.
+         */
+        set<T>(key: string, value: T): T;
+        /**
+         *  assigns values to multiple keys using each 'keysObject' top-level property. Returns the keysObject.
+         */
+        set<T extends { [key: string]: any }>(keysObject: T): T;
+
+        /**
+         * retrieve value using a key. If 'clear' is 'true', key is cleared on return.
+         */
+        get(key: string, clear?: boolean): any;
+        /**
+         * clears key.
+         */
+        clear(key: string): void;
+        /**
+         * Manually notify the session of changes (when using get()
+         * and changing the content of the returned reference directly without calling set()).
+         */
+        touch(): void;
+        /**
+         * stores volatile data - data that should be deleted once read.
+         * When given no arguments, it will return all of the flash messages and delete the originals.
+         * When given only a type, it will return all of the flash messages of that type and delete the originals.
+         * When given a type and a message, it will set or append that message to the given type.
+         * 'isOverride' used to indicate that the message provided should replace
+         * any existing value instead of being appended to it (defaults to false).
+         */
+        flash(type?: string, message?: any, isOverride?: boolean): any[];
+
+        /**
+         * if set to 'true', enables lazy mode.
+         * In lazy mode, request.yar can be modified directly (e.g. setting request.yar.myKey to an object value),
+         * and those keys will be stored and loaded back.
+         * Lazy mode isn't as fast as the normal get/set because
+         * it has to store the session state on every responses regardless of any changes being made.
+         */
+        lazy(enabled: boolean): void;
+
+        /**
+         * used to manually prepare the session state and commit it into the response when the response is taken
+         * over in an onPreResponse handler. Normally, the yar onPreRespinse handler performs the commit, but if
+         * an application extension handler takes over, yar doesn't get a chance to commit the state before the
+         * response goes out. The method requires the hapi h toolkit argument available in the extension handler.
+         */
+        commit(h: ResponseToolkit): Promise<void>;
+    }
+
+    interface ServerYar {
+        revoke(id: Id): Promise<void>;
+    }
+}
+declare const yar: Plugin<yar.YarOptions>;
+export = yar;
+
+declare module '@hapi/hapi' {
+    interface Request {
+        yar: yar.Yar;
+    }
+
+    interface Server {
+        yar: yar.ServerYar;
+    }
+}

package.json

@@ -4,6 +4,7 @@
   "version": "11.0.1",
   "repository": "git://github.com/hapijs/yar",
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib"
   ],
@@ -28,10 +29,13 @@
     "@hapi/code": "^9.0.3",
     "@hapi/eslint-plugin": "*",
     "@hapi/hapi": "^21.2.1",
-    "@hapi/lab": "^25.1.2"
+    "@hapi/lab": "^25.1.2",
+    "@types/node": "^20.11.30",
+    "joi": "^17.12.2",
+    "typescript": "^5.4.2"
   },
   "scripts": {
-    "test": "lab -a @hapi/code -t 100 -L",
+    "test": "lab -a @hapi/code -t 100 -L -Y",
     "test-cov-html": "lab -a @hapi/code -r html -o coverage.html"
   },
   "license": "BSD-3-Clause"

test/types/index.ts

@@ -0,0 +1,31 @@
+import { Request, Server } from '@hapi/hapi';
+import * as yar from '../..';
+
+async function boot() {
+    const server = new Server();
+    await server.register({
+        plugin: yar,
+        options: {
+            cookieOptions: {
+                password: 'test',
+                isSecure: true,
+            },
+            cache: {
+                cache: 'test',
+                expiresIn: 123141243,
+            },
+        },
+    });
+
+    server.route({
+        path: '/test',
+        method: 'get',
+        handler(request: Request) {
+            const example = request.yar.get('example');
+            return {
+                id: request.yar.id,
+                key: example.key,
+            };
+        },
+    });
+}