From c576e544beac58d911fe017a20bf3f2c794b45aa Mon Sep 17 00:00:00 2001 From: Rodrigo Saboya Date: Sat, 17 Feb 2018 22:33:46 -0200 Subject: [PATCH] Updating catbox to hapi 17 bindings. --- types/catbox/catbox-tests.ts | 24 +- types/catbox/index.d.ts | 102 +++--- types/catbox/tsconfig.json | 5 - types/catbox/v7/catbox-tests.ts | 27 ++ types/catbox/v7/index.d.ts | 310 ++++++++++++++++++ types/catbox/v7/tsconfig.json | 31 ++ types/catbox/v7/tslint.json | 1 + types/h2o2/tsconfig.json | 3 + types/hapi-auth-basic/tsconfig.json | 5 - types/hapi-auth-jwt2/tsconfig.json | 3 + types/hapi-decorators/tsconfig.json | 3 + types/hapi/index.d.ts | 4 +- .../test/server/server-cache-provision.ts | 4 +- types/hapi/test/server/server-cache.ts | 4 +- types/hapi/tsconfig.json | 5 - types/hapi/v16/tsconfig.json | 3 + types/inert/tsconfig.json | 5 - types/inert/v4/tsconfig.json | 3 + types/nes/tsconfig.json | 5 - types/optics-agent/tsconfig.json | 5 - types/swagger-express-mw/tsconfig.json | 3 + types/swagger-hapi/tsconfig.json | 3 + types/swagger-node-runner/tsconfig.json | 3 + types/swagger-restify-mw/tsconfig.json | 3 + types/swagger-sails-hook/tsconfig.json | 3 + types/vision/tsconfig.json | 5 - types/vision/v4/tsconfig.json | 3 + types/yar/tsconfig.json | 5 - 28 files changed, 464 insertions(+), 116 deletions(-) create mode 100644 types/catbox/v7/catbox-tests.ts create mode 100644 types/catbox/v7/index.d.ts create mode 100644 types/catbox/v7/tsconfig.json create mode 100644 types/catbox/v7/tslint.json diff --git a/types/catbox/catbox-tests.ts b/types/catbox/catbox-tests.ts index 565573adad..25d4826d25 100644 --- a/types/catbox/catbox-tests.ts +++ b/types/catbox/catbox-tests.ts @@ -1,26 +1,26 @@ -import Catbox = require("catbox"); +import { CacheItem, Client, Policy, EnginePrototypeOrObject } from "catbox"; -const Memory: Catbox.EnginePrototypeOrObject = { - start(callback: Catbox.CallBackNoResult) {}, - stop() {}, - get() {}, - set() {}, - drop() {}, +const Memory: EnginePrototypeOrObject = { + async start(): Promise {}, + stop(): void {}, + async get(): Promise {}, + async set(): Promise {}, + async drop(): Promise {}, isReady(): boolean { return true; }, validateSegmentName(segment: string): null { return null; }, }; -const client = new Catbox.Client(Memory, { partition: 'cache' }); +const client = new Client(Memory, { partition: 'cache' }); -const cache = new Catbox.Policy({ +const cache = new Policy({ expiresIn: 5000, }, client, 'cache'); -cache.set('foo', 'bar', 5000, () => {}); +cache.set('foo', 'bar', 5000).then(() => {}); -cache.get('foo', () => {}); +cache.get('foo').then(() => {}); -cache.drop('foo', () => {}); +cache.drop('foo').then(() => {}); cache.isReady(); diff --git a/types/catbox/index.d.ts b/types/catbox/index.d.ts index 826f1f7369..6d51e48696 100644 --- a/types/catbox/index.d.ts +++ b/types/catbox/index.d.ts @@ -1,14 +1,11 @@ -// Type definitions for catbox 7.1 +// Type definitions for catbox 10.0 // Project: https://github.com/hapijs/catbox -// Definitions by: Jason Swearingen , AJP +// Definitions by: Jason Swearingen +// AJP +// Rodrigo Saboya // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.4 -import * as Boom from 'boom'; - -export type CallBackNoResult = (err?: Boom.BoomError) => void; -export type CallBackWithResult = (err: Boom.BoomError | null | undefined, result: T) => void; - /** * Client * The Client object provides a low-level cache abstraction. The object is constructed using new Client(engine, options) where: @@ -23,34 +20,31 @@ export type CallBackWithResult = (err: Boom.BoomError | null | undefined, res export class Client implements ClientApi { constructor(engine: EnginePrototypeOrObject, options: ClientOptions); - /** start(callback) - creates a connection to the cache server. Must be called before any other method is available. The callback signature is function(err). */ - start(callback: CallBackNoResult): void; + /** start() - creates a connection to the cache server. Must be called before any other method is available. */ + start(): Promise; /** stop() - terminates the connection to the cache server. */ stop(): void; /** * get(key, callback) - retrieve an item from the cache engine if found where: * * key - a cache key object (see [ICacheKey]). - * * callback - a function with the signature function(err, cached). If the item is not found, both err and cached are null. If found, the cached object is returned */ - get(key: CacheKey, callback: CallBackWithResult): CacheItem; + get(key: CacheKey): Promise; /** * set(key, value, ttl, callback) - store an item in the cache for a specified length of time, where: * * key - a cache key object (see [ICacheKey]). * * value - the string or object value to be stored. * * ttl - a time-to-live value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). - * * callback - a function with the signature function(err). */ - set(key: CacheKey, value: CacheItem, ttl: number, callback: CallBackNoResult): void; + set(key: CacheKey, value: CacheItem, ttl: number): Promise; /** * drop(key, callback) - remove an item from cache where: * * key - a cache key object (see [ICacheKey]). - * * callback - a function with the signature function(err). */ - drop(key: CacheKey, callback: CallBackNoResult): void; + drop(key: CacheKey): Promise; /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready. */ isReady(): boolean; /** validateSegmentName(segment) - returns null if the segment name is valid (see below), otherwise should return an instance of Error with an appropriate message. */ - validateSegmentName(segment: string): null | Boom.BoomError; + validateSegmentName(segment: string): null | Error; } export type EnginePrototypeOrObject = EnginePrototype | ClientApi; @@ -68,34 +62,31 @@ export interface EnginePrototype { * @see {@link https://github.com/hapijs/catbox#api} */ export interface ClientApi { - /** start(callback) - creates a connection to the cache server. Must be called before any other method is available. The callback signature is function(err). */ - start(callback: CallBackNoResult): void; + /** start() - creates a connection to the cache server. Must be called before any other method is available. */ + start(): Promise; /** stop() - terminates the connection to the cache server. */ stop(): void; /** * get(key, callback) - retrieve an item from the cache engine if found where: * * key - a cache key object (see [ICacheKey]). - * * callback - a function with the signature function(err, cached). If the item is not found, both err and cached are null. If found, the cached object is returned */ - get(key: CacheKey, callback: CallBackWithResult): CacheItem; + get(key: CacheKey): Promise; /** - * set(key, value, ttl, callback) - store an item in the cache for a specified length of time, where: + * set(key, value, ttl) - store an item in the cache for a specified length of time, where: * * key - a cache key object (see [ICacheKey]). * * value - the string or object value to be stored. * * ttl - a time-to-live value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). - * * callback - a function with the signature function(err). */ - set(key: CacheKey, value: CacheItem, ttl: number, callback: CallBackNoResult): void; + set(key: CacheKey, value: CacheItem, ttl: number): Promise; /** - * drop(key, callback) - remove an item from cache where: + * drop(key) - remove an item from cache where: * * key - a cache key object (see [ICacheKey]). - * * callback - a function with the signature function(err). */ - drop(key: CacheKey, callback: CallBackNoResult): void; + drop(key: CacheKey): Promise; /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready. */ isReady(): boolean; /** validateSegmentName(segment) - returns null if the segment name is valid (see below), otherwise should return an instance of Error with an appropriate message. */ - validateSegmentName(segment: string): null | Boom.BoomError; + validateSegmentName(segment: string): null | Error; } /** @@ -135,27 +126,24 @@ export interface ClientOptions { export class Policy implements PolicyAPI { constructor(options: PolicyOptions, cache: Client, segment: string); /** - * get(id, callback) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, + * get(id) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, * a new value is generated, stored in the cache, and returned. Multiple concurrent requests are queued and processed once. The method arguments are: * * id - the unique item identifier (within the policy segment). Can be a string or an object with the required 'id' key. - * * callback - the return function. */ - get(id: string | {id: string}, callback: PolicyGetCallback): CacheItem; + get(id: string | { id: string }): Promise; /** - * set(id, value, ttl, callback) - store an item in the cache where: + * set(id, value, ttl) - store an item in the cache where: * * id - the unique item identifier (within the policy segment). * * value - the string or object value to be stored. * * ttl - a time-to-live override value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). * This should be set to 0 in order to use the caching rules configured when creating the Policy object. - * * callback - a function with the signature function(err). */ - set(id: string | {id: string}, value: CacheItem, ttl: number | null, callback: CallBackNoResult): void; + set(id: string | { id: string }, value: CacheItem, ttl: number | null): Promise; /** - * drop(id, callback) - remove the item from cache where: + * drop(id) - remove the item from cache where: * * id - the unique item identifier (within the policy segment). - * * callback - a function with the signature function(err). */ - drop(id: string | {id: string}, callback: CallBackNoResult): void; + drop(id: string | { id: string }): Promise; /** ttl(created) - given a created timestamp in milliseconds, returns the time-to-live left based on the configured rules. */ ttl(created: number): number; /** rules(options) - changes the policy rules after construction (note that items already stored will not be affected) */ @@ -173,27 +161,24 @@ export class Policy implements PolicyAPI { */ export interface PolicyAPI { /** - * get(id, callback) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, + * get(id) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, * a new value is generated, stored in the cache, and returned. Multiple concurrent requests are queued and processed once. The method arguments are: * * id - the unique item identifier (within the policy segment). Can be a string or an object with the required 'id' key. - * * callback - the return function. */ - get(id: string | {id: string}, callback: PolicyGetCallback): CacheItem; + get(id: string | { id: string }): Promise; /** - * set(id, value, ttl, callback) - store an item in the cache where: + * set(id, value, ttl) - store an item in the cache where: * * id - the unique item identifier (within the policy segment). * * value - the string or object value to be stored. * * ttl - a time-to-live override value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). * This should be set to 0 in order to use the caching rules configured when creating the Policy object. - * * callback - a function with the signature function(err). */ - set(id: string | {id: string}, value: CacheItem, ttl: number | null, callback: CallBackNoResult): void; + set(id: string | { id: string }, value: CacheItem, ttl: number | null): Promise; /** - * drop(id, callback) - remove the item from cache where: + * drop(id) - remove the item from cache where: * * id - the unique item identifier (within the policy segment). - * * callback - a function with the signature function(err). */ - drop(id: string | {id: string}, callback: CallBackNoResult): void; + drop(id: string | { id: string }): Promise; /** ttl(created) - given a created timestamp in milliseconds, returns the time-to-live left based on the configured rules. */ ttl(created: number): number; /** rules(options) - changes the policy rules after construction (note that items already stored will not be affected) */ @@ -204,16 +189,13 @@ export interface PolicyAPI { stats(): CacheStatisticsObject; } -/** - * The return function. The function signature is function(err, value, cached, report) where: - * @param err - any errors encountered. - * @param value - the fetched or generated value. - * @param cached - null if a valid item was not found in the cache, or IPolicyGetCallbackCachedOptions - * @param report - an object with logging information about the generation operation - */ -export type PolicyGetCallback = (err: null | Boom.BoomError, value: CacheItem, cached: PolicyGetCallbackCachedOptions, report: PolicyGetCallbackReportLog) => void; +export interface PolicyGetPromiseResult { + value: CacheItem; + cached: PolicyGetCachedOptions; + report: PolicyGetReportLog; +} -export interface PolicyGetCallbackCachedOptions { +export interface PolicyGetCachedOptions { /** item - the cached value. */ item: CacheItem; /** stored - the timestamp when the item was stored in the cache. */ @@ -262,10 +244,14 @@ export interface PolicyOptions { pendingGenerateTimeout?: number; } +export interface GenerateFuncFlags { + ttl: number; +} + /** * generateFunc * Is used in PolicyOptions - * A function used to generate a new cache item if one is not found in the cache when calling get(). The method's signature is function(id, next) + * A function used to generate a new cache item if one is not found in the cache when calling get(). The method's signature is function(id) * @param id - the id string or object provided to the get() method. * @param next - the method called when the new item is returned with the signature function(err, value, ttl) where: * * err - an error condition. @@ -273,12 +259,12 @@ export interface PolicyOptions { * * ttl - the cache ttl value in milliseconds. Set to 0 to skip storing in the cache. Defaults to the cache global policy. * @see {@link https://github.com/hapijs/catbox#policy} */ -export type GenerateFunc = (id: string, next: ((err: null | Boom.BoomError, value: CacheItem, ttl?: number) => void)) => void; +export type GenerateFunc = (id: string, flags: GenerateFuncFlags) => Promise; /** * An object with logging information about the generation operation containing the following keys (as relevant): */ -export interface PolicyGetCallbackReportLog { +export interface PolicyGetReportLog { /** msec - the cache lookup time in milliseconds. */ msec: number; /** stored - the timestamp when the item was stored in the cache. */ @@ -288,7 +274,7 @@ export interface PolicyGetCallbackReportLog { /** ttl - the cache ttl value for the record. */ ttl: number; /** error - lookup error. */ - error?: Boom.BoomError; + error?: Error; } /** diff --git a/types/catbox/tsconfig.json b/types/catbox/tsconfig.json index 24e8f7f34e..feb19f81dc 100644 --- a/types/catbox/tsconfig.json +++ b/types/catbox/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/catbox/v7/catbox-tests.ts b/types/catbox/v7/catbox-tests.ts new file mode 100644 index 0000000000..565573adad --- /dev/null +++ b/types/catbox/v7/catbox-tests.ts @@ -0,0 +1,27 @@ +import Catbox = require("catbox"); + +const Memory: Catbox.EnginePrototypeOrObject = { + start(callback: Catbox.CallBackNoResult) {}, + stop() {}, + get() {}, + set() {}, + drop() {}, + isReady(): boolean { return true; }, + validateSegmentName(segment: string): null { return null; }, +}; + +const client = new Catbox.Client(Memory, { partition: 'cache' }); + +const cache = new Catbox.Policy({ + expiresIn: 5000, +}, client, 'cache'); + +cache.set('foo', 'bar', 5000, () => {}); + +cache.get('foo', () => {}); + +cache.drop('foo', () => {}); + +cache.isReady(); + +cache.stats(); diff --git a/types/catbox/v7/index.d.ts b/types/catbox/v7/index.d.ts new file mode 100644 index 0000000000..826f1f7369 --- /dev/null +++ b/types/catbox/v7/index.d.ts @@ -0,0 +1,310 @@ +// Type definitions for catbox 7.1 +// Project: https://github.com/hapijs/catbox +// Definitions by: Jason Swearingen , AJP +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.4 + +import * as Boom from 'boom'; + +export type CallBackNoResult = (err?: Boom.BoomError) => void; +export type CallBackWithResult = (err: Boom.BoomError | null | undefined, result: T) => void; + +/** + * Client + * The Client object provides a low-level cache abstraction. The object is constructed using new Client(engine, options) where: + * engine - is an object or a prototype function implementing the cache strategy: + * * function - a prototype function with the signature function(options). catbox will call new func(options). + * * object - a pre instantiated client implementation object. Does not support passing options. + * options - the strategy configuration object. Each strategy defines its own configuration options with the following common options: + * * partition - the partition name used to isolate the cached results across multiple clients. The partition name is used as the MongoDB database name, + * the Riak bucket, or as a key prefix in Redis and Memcached. To share the cache across multiple clients, use the same partition name. + * @see {@link https://github.com/hapijs/catbox#client} + */ +export class Client implements ClientApi { + constructor(engine: EnginePrototypeOrObject, options: ClientOptions); + + /** start(callback) - creates a connection to the cache server. Must be called before any other method is available. The callback signature is function(err). */ + start(callback: CallBackNoResult): void; + /** stop() - terminates the connection to the cache server. */ + stop(): void; + /** + * get(key, callback) - retrieve an item from the cache engine if found where: + * * key - a cache key object (see [ICacheKey]). + * * callback - a function with the signature function(err, cached). If the item is not found, both err and cached are null. If found, the cached object is returned + */ + get(key: CacheKey, callback: CallBackWithResult): CacheItem; + /** + * set(key, value, ttl, callback) - store an item in the cache for a specified length of time, where: + * * key - a cache key object (see [ICacheKey]). + * * value - the string or object value to be stored. + * * ttl - a time-to-live value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). + * * callback - a function with the signature function(err). + */ + set(key: CacheKey, value: CacheItem, ttl: number, callback: CallBackNoResult): void; + /** + * drop(key, callback) - remove an item from cache where: + * * key - a cache key object (see [ICacheKey]). + * * callback - a function with the signature function(err). + */ + drop(key: CacheKey, callback: CallBackNoResult): void; + /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready. */ + isReady(): boolean; + /** validateSegmentName(segment) - returns null if the segment name is valid (see below), otherwise should return an instance of Error with an appropriate message. */ + validateSegmentName(segment: string): null | Boom.BoomError; +} + +export type EnginePrototypeOrObject = EnginePrototype | ClientApi; + +/** + * A prototype CatBox engine function + */ +export interface EnginePrototype { + new(settings: ClientOptions): ClientApi; +} + +/** + * Client API + * The Client object provides the following methods: + * @see {@link https://github.com/hapijs/catbox#api} + */ +export interface ClientApi { + /** start(callback) - creates a connection to the cache server. Must be called before any other method is available. The callback signature is function(err). */ + start(callback: CallBackNoResult): void; + /** stop() - terminates the connection to the cache server. */ + stop(): void; + /** + * get(key, callback) - retrieve an item from the cache engine if found where: + * * key - a cache key object (see [ICacheKey]). + * * callback - a function with the signature function(err, cached). If the item is not found, both err and cached are null. If found, the cached object is returned + */ + get(key: CacheKey, callback: CallBackWithResult): CacheItem; + /** + * set(key, value, ttl, callback) - store an item in the cache for a specified length of time, where: + * * key - a cache key object (see [ICacheKey]). + * * value - the string or object value to be stored. + * * ttl - a time-to-live value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). + * * callback - a function with the signature function(err). + */ + set(key: CacheKey, value: CacheItem, ttl: number, callback: CallBackNoResult): void; + /** + * drop(key, callback) - remove an item from cache where: + * * key - a cache key object (see [ICacheKey]). + * * callback - a function with the signature function(err). + */ + drop(key: CacheKey, callback: CallBackNoResult): void; + /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready. */ + isReady(): boolean; + /** validateSegmentName(segment) - returns null if the segment name is valid (see below), otherwise should return an instance of Error with an appropriate message. */ + validateSegmentName(segment: string): null | Boom.BoomError; +} + +/** + * Any method with a key argument takes an object with the following required properties: + */ +export interface CacheKey { + /** segment - a caching segment name string. Enables using a single cache server for storing different sets of items with overlapping ids. */ + segment: string; + /** id - a unique item identifier string (per segment). Can be an empty string. */ + id: string; +} + +/** Cached object contains the following: */ +export interface CachedObject { + /** item - the value stored in the cache using set(). */ + item: any; + /** stored - the timestamp when the item was stored in the cache (in milliseconds). */ + stored: number; + /** ttl - the remaining time-to-live (not the original value used when storing the object). */ + ttl: number; +} + +export type CacheItem = any; + +export interface ClientOptions { + partition: string; +} + +/** + * The Policy object provides a convenient cache interface by setting a global policy which is automatically applied to every storage action. + * The object is constructed using new Policy(options, [cache, segment]) where: + * * options - an object with the IPolicyOptions structure + * * cache - a Client instance (which has already been started). + * * segment - required when cache is provided. The segment name used to isolate cached items within the cache partition. + * @see {@link https://github.com/hapijs/catbox#policy} + */ +export class Policy implements PolicyAPI { + constructor(options: PolicyOptions, cache: Client, segment: string); + /** + * get(id, callback) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, + * a new value is generated, stored in the cache, and returned. Multiple concurrent requests are queued and processed once. The method arguments are: + * * id - the unique item identifier (within the policy segment). Can be a string or an object with the required 'id' key. + * * callback - the return function. + */ + get(id: string | {id: string}, callback: PolicyGetCallback): CacheItem; + /** + * set(id, value, ttl, callback) - store an item in the cache where: + * * id - the unique item identifier (within the policy segment). + * * value - the string or object value to be stored. + * * ttl - a time-to-live override value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). + * This should be set to 0 in order to use the caching rules configured when creating the Policy object. + * * callback - a function with the signature function(err). + */ + set(id: string | {id: string}, value: CacheItem, ttl: number | null, callback: CallBackNoResult): void; + /** + * drop(id, callback) - remove the item from cache where: + * * id - the unique item identifier (within the policy segment). + * * callback - a function with the signature function(err). + */ + drop(id: string | {id: string}, callback: CallBackNoResult): void; + /** ttl(created) - given a created timestamp in milliseconds, returns the time-to-live left based on the configured rules. */ + ttl(created: number): number; + /** rules(options) - changes the policy rules after construction (note that items already stored will not be affected) */ + rules(options: PolicyOptions): void; + /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready or if there is no cache engine set. */ + isReady(): boolean; + /** stats - an object with cache statistics */ + stats(): CacheStatisticsObject; +} + +/** + * Policy API + * The Policy object provides the following methods: + * @see {@link https://github.com/hapijs/catbox#api-1} + */ +export interface PolicyAPI { + /** + * get(id, callback) - retrieve an item from the cache. If the item is not found and the generateFunc method was provided, + * a new value is generated, stored in the cache, and returned. Multiple concurrent requests are queued and processed once. The method arguments are: + * * id - the unique item identifier (within the policy segment). Can be a string or an object with the required 'id' key. + * * callback - the return function. + */ + get(id: string | {id: string}, callback: PolicyGetCallback): CacheItem; + /** + * set(id, value, ttl, callback) - store an item in the cache where: + * * id - the unique item identifier (within the policy segment). + * * value - the string or object value to be stored. + * * ttl - a time-to-live override value in milliseconds after which the item is automatically removed from the cache (or is marked invalid). + * This should be set to 0 in order to use the caching rules configured when creating the Policy object. + * * callback - a function with the signature function(err). + */ + set(id: string | {id: string}, value: CacheItem, ttl: number | null, callback: CallBackNoResult): void; + /** + * drop(id, callback) - remove the item from cache where: + * * id - the unique item identifier (within the policy segment). + * * callback - a function with the signature function(err). + */ + drop(id: string | {id: string}, callback: CallBackNoResult): void; + /** ttl(created) - given a created timestamp in milliseconds, returns the time-to-live left based on the configured rules. */ + ttl(created: number): number; + /** rules(options) - changes the policy rules after construction (note that items already stored will not be affected) */ + rules(options: PolicyOptions): void; + /** isReady() - returns true if cache engine determines itself as ready, false if it is not ready or if there is no cache engine set. */ + isReady(): boolean; + /** stats - an object with cache statistics */ + stats(): CacheStatisticsObject; +} + +/** + * The return function. The function signature is function(err, value, cached, report) where: + * @param err - any errors encountered. + * @param value - the fetched or generated value. + * @param cached - null if a valid item was not found in the cache, or IPolicyGetCallbackCachedOptions + * @param report - an object with logging information about the generation operation + */ +export type PolicyGetCallback = (err: null | Boom.BoomError, value: CacheItem, cached: PolicyGetCallbackCachedOptions, report: PolicyGetCallbackReportLog) => void; + +export interface PolicyGetCallbackCachedOptions { + /** item - the cached value. */ + item: CacheItem; + /** stored - the timestamp when the item was stored in the cache. */ + stored: number; + /** ttl - the cache ttl value for the record. */ + ttl: number; + /** isStale - true if the item is stale. */ + isStale: boolean; +} + +/** + * @see {@link https://github.com/hapijs/catbox#policy} + */ +export interface PolicyOptions { + /** expiresIn - relative expiration expressed in the number of milliseconds since the item was saved in the cache. Cannot be used together with expiresAt. */ + expiresIn?: number; + /** expiresAt - time of day expressed in 24h notation using the 'HH:MM' format, at which point all cache records for the route expire. Uses local time. Cannot be used together with expiresIn. */ + expiresAt?: string; + /** generateFunc - a function used to generate a new cache item if one is not found in the cache when calling get(). The method's signature is function(id, next) where: */ + generateFunc?: GenerateFunc; + /** + * staleIn - number of milliseconds to mark an item stored in cache as stale and attempt to regenerate it when generateFunc is provided. + * Must be less than expiresIn. Alternatively function that returns staleIn value in milliseconds. The function signature is function(stored, ttl) where: + * * stored - the timestamp when the item was stored in the cache (in milliseconds). + * * ttl - the remaining time-to-live (not the original value used when storing the object). + */ + staleIn?: number | ((stored: number, ttl: number) => number); + /** staleTimeout - number of milliseconds to wait before returning a stale value while generateFunc is generating a fresh value. */ + staleTimeout?: number; + /** + * generateTimeout - number of milliseconds to wait before returning a timeout error when the generateFunc function takes too long to return a value. + * When the value is eventually returned, it is stored in the cache for future requests. Required if generateFunc is present. + * Set to false to disable timeouts which may cause all get() requests to get stuck forever. + */ + generateTimeout?: number | false; + /** dropOnError - if true, an error or timeout in the generateFunc causes the stale value to be evicted from the cache. Defaults to true. */ + dropOnError?: boolean; + /** generateOnReadError - if false, an upstream cache read error will stop the get() method from calling the generate function and will instead pass back the cache error. Defaults to true. */ + generateOnReadError?: boolean; + /** generateIgnoreWriteError - if false, an upstream cache write error will be passed back with the generated value when calling the get() method. Defaults to true. */ + generateIgnoreWriteError?: boolean; + /** + * pendingGenerateTimeout - number of milliseconds while generateFunc call is in progress for a given id, before a subsequent generateFunc call is allowed. + * Defaults to 0, no blocking of concurrent generateFunc calls beyond staleTimeout. + */ + pendingGenerateTimeout?: number; +} + +/** + * generateFunc + * Is used in PolicyOptions + * A function used to generate a new cache item if one is not found in the cache when calling get(). The method's signature is function(id, next) + * @param id - the id string or object provided to the get() method. + * @param next - the method called when the new item is returned with the signature function(err, value, ttl) where: + * * err - an error condition. + * * value - the new value generated. + * * ttl - the cache ttl value in milliseconds. Set to 0 to skip storing in the cache. Defaults to the cache global policy. + * @see {@link https://github.com/hapijs/catbox#policy} + */ +export type GenerateFunc = (id: string, next: ((err: null | Boom.BoomError, value: CacheItem, ttl?: number) => void)) => void; + +/** + * An object with logging information about the generation operation containing the following keys (as relevant): + */ +export interface PolicyGetCallbackReportLog { + /** msec - the cache lookup time in milliseconds. */ + msec: number; + /** stored - the timestamp when the item was stored in the cache. */ + stored: number; + /** isStale - true if the item is stale. */ + isStale: boolean; + /** ttl - the cache ttl value for the record. */ + ttl: number; + /** error - lookup error. */ + error?: Boom.BoomError; +} + +/** + * an object with cache statistics where: + */ +export interface CacheStatisticsObject { + /** sets - number of cache writes. */ + sets: number; + /** gets - number of cache get() requests. */ + gets: number; + /** hits - number of cache get() requests in which the requested id was found in the cache (can be stale). */ + hits: number; + /** stales - number of cache reads with stale requests (only counts the first request in a queued get() operation). */ + stales: number; + /** generates - number of calls to the generate function. */ + generates: number; + /** errors - cache operations errors. TODO check this */ + errors: number; +} diff --git a/types/catbox/v7/tsconfig.json b/types/catbox/v7/tsconfig.json new file mode 100644 index 0000000000..48b4d9f014 --- /dev/null +++ b/types/catbox/v7/tsconfig.json @@ -0,0 +1,31 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../../", + "typeRoots": [ + "../../" + ], + "types": [], + "paths": { + "boom": [ + "boom/v4" + ], + "catbox": [ + "catbox/v7" + ] + }, + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "catbox-tests.ts" + ] +} \ No newline at end of file diff --git a/types/catbox/v7/tslint.json b/types/catbox/v7/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/catbox/v7/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/h2o2/tsconfig.json b/types/h2o2/tsconfig.json index eb41a55289..767fa4e7b7 100644 --- a/types/h2o2/tsconfig.json +++ b/types/h2o2/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/hapi-auth-basic/tsconfig.json b/types/hapi-auth-basic/tsconfig.json index 191d992f70..80aa0fbace 100644 --- a/types/hapi-auth-basic/tsconfig.json +++ b/types/hapi-auth-basic/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/hapi-auth-jwt2/tsconfig.json b/types/hapi-auth-jwt2/tsconfig.json index ada8a3f94d..19a6e785ac 100644 --- a/types/hapi-auth-jwt2/tsconfig.json +++ b/types/hapi-auth-jwt2/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/hapi-decorators/tsconfig.json b/types/hapi-decorators/tsconfig.json index a018c33c53..6434d0422e 100644 --- a/types/hapi-decorators/tsconfig.json +++ b/types/hapi-decorators/tsconfig.json @@ -19,6 +19,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/hapi/index.d.ts b/types/hapi/index.d.ts index f65cee14d4..01586dd3bf 100644 --- a/types/hapi/index.d.ts +++ b/types/hapi/index.d.ts @@ -453,7 +453,7 @@ export interface Request extends Podium { * The response object when set. The object can be modified but must not be assigned another object. To replace the response with another from within an extension point, use reply(response) to * override with a different response. Contains null when no response has been set (e.g. when a request terminates prematurely when the client disconnects). */ - response: ResponseObject | Boom.BoomError | null; + response: ResponseObject | Boom.Boom | null; /** * Same as pre but represented as the response object created by the pre method. @@ -3847,7 +3847,7 @@ export namespace Lifecycle { type ReturnValueTypes = (null | string | number | boolean) | (Buffer) | - (Error | Boom.BoomError) | + (Error | Boom.Boom) | (stream.Stream) | (object | object[]) | symbol | diff --git a/types/hapi/test/server/server-cache-provision.ts b/types/hapi/test/server/server-cache-provision.ts index f30ce65cd6..1e120348b2 100644 --- a/types/hapi/test/server/server-cache-provision.ts +++ b/types/hapi/test/server/server-cache-provision.ts @@ -9,8 +9,8 @@ server.initialize(); server.cache.provision({engine: require('catbox-memory'), name: 'countries' }); const cache: catbox.Policy = server.cache({segment: 'countries', cache: 'countries', expiresIn: 60 * 60 * 1000 }); -cache.set('norway', 'oslo', 10 * 1000, () => {}); -const value = cache.get('norway', () => {}); +cache.set('norway', 'oslo', 10 * 1000).then(() => {}); +const value = cache.get('norway').then(() => {}); server.start(); diff --git a/types/hapi/test/server/server-cache.ts b/types/hapi/test/server/server-cache.ts index 64f8c85e80..6aa612f3f1 100644 --- a/types/hapi/test/server/server-cache.ts +++ b/types/hapi/test/server/server-cache.ts @@ -11,9 +11,9 @@ const catboxOptions: ServerOptionsCache = { expiresIn: 60 * 60 * 1000 }; const cache: catbox.Policy = server.cache(catboxOptions); -cache.set('norway', 'oslo', 10 * 1000, () => {}); +cache.set('norway', 'oslo', 10 * 1000).then(() => {}); -const value = cache.get('norway', () => {}); +const value = cache.get('norway').then(() => {}); console.log("Value: " + value); server.start(); diff --git a/types/hapi/tsconfig.json b/types/hapi/tsconfig.json index f8db3fc828..c93f0dfc7f 100644 --- a/types/hapi/tsconfig.json +++ b/types/hapi/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/hapi/v16/tsconfig.json b/types/hapi/v16/tsconfig.json index 517d678910..23087e8eff 100644 --- a/types/hapi/v16/tsconfig.json +++ b/types/hapi/v16/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/inert/tsconfig.json b/types/inert/tsconfig.json index 238aa1a3eb..866d1c4884 100644 --- a/types/inert/tsconfig.json +++ b/types/inert/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/inert/v4/tsconfig.json b/types/inert/v4/tsconfig.json index fd468493b4..f742ec35d5 100644 --- a/types/inert/v4/tsconfig.json +++ b/types/inert/v4/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/nes/tsconfig.json b/types/nes/tsconfig.json index 05fc49c647..18fc2712d8 100644 --- a/types/nes/tsconfig.json +++ b/types/nes/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/optics-agent/tsconfig.json b/types/optics-agent/tsconfig.json index 010406be2f..046bfaad81 100644 --- a/types/optics-agent/tsconfig.json +++ b/types/optics-agent/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/swagger-express-mw/tsconfig.json b/types/swagger-express-mw/tsconfig.json index c1db9f10a4..de623e0eca 100644 --- a/types/swagger-express-mw/tsconfig.json +++ b/types/swagger-express-mw/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/swagger-hapi/tsconfig.json b/types/swagger-hapi/tsconfig.json index df8e735e23..0b6f0cf5ed 100644 --- a/types/swagger-hapi/tsconfig.json +++ b/types/swagger-hapi/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/swagger-node-runner/tsconfig.json b/types/swagger-node-runner/tsconfig.json index d8bb8c8f52..43f153e823 100644 --- a/types/swagger-node-runner/tsconfig.json +++ b/types/swagger-node-runner/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/swagger-restify-mw/tsconfig.json b/types/swagger-restify-mw/tsconfig.json index ec732988fc..89ba456bbf 100644 --- a/types/swagger-restify-mw/tsconfig.json +++ b/types/swagger-restify-mw/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/swagger-sails-hook/tsconfig.json b/types/swagger-sails-hook/tsconfig.json index 98768dd651..0fd1188f61 100644 --- a/types/swagger-sails-hook/tsconfig.json +++ b/types/swagger-sails-hook/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/vision/tsconfig.json b/types/vision/tsconfig.json index 8f34e356c5..3c6377bfea 100644 --- a/types/vision/tsconfig.json +++ b/types/vision/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true }, diff --git a/types/vision/v4/tsconfig.json b/types/vision/v4/tsconfig.json index 2ab1f666a0..832edc4057 100644 --- a/types/vision/v4/tsconfig.json +++ b/types/vision/v4/tsconfig.json @@ -17,6 +17,9 @@ "boom": [ "boom/v4" ], + "catbox": [ + "catbox/v7" + ], "hapi": [ "hapi/v16" ], diff --git a/types/yar/tsconfig.json b/types/yar/tsconfig.json index 3843d1296e..c2723ded55 100644 --- a/types/yar/tsconfig.json +++ b/types/yar/tsconfig.json @@ -13,11 +13,6 @@ "../" ], "types": [], - "paths": { - "boom": [ - "boom/v4" - ] - }, "noEmit": true, "forceConsistentCasingInFileNames": true },