deno.land / x / cockatiel@v3.1.2 / src / Policy.ts
نووسراو ببینە
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487import { ConstantBackoff, IBackoffFactory } from './backoff/Backoff';import { IBreaker } from './breaker/Breaker';import { BulkheadPolicy } from './BulkheadPolicy';import { CircuitBreakerPolicy } from './CircuitBreakerPolicy';import { Event } from './common/Event';import { ExecuteWrapper } from './common/Executor';import { FallbackPolicy } from './FallbackPolicy';import { NoopPolicy } from './NoopPolicy';import { IRetryBackoffContext, RetryPolicy } from './RetryPolicy';import { TimeoutPolicy, TimeoutStrategy } from './TimeoutPolicy';
type Constructor<T> = new (...args: any) => T;
const typeFilter = <T>(cls: Constructor<T>, predicate?: (error: T) => boolean) => predicate ? (v: unknown) => v instanceof cls && predicate(v) : (v: unknown) => v instanceof cls;
const always = () => true;const never = () => false;
export interface IBasePolicyOptions { errorFilter: (error: Error) => boolean; resultFilter: (result: unknown) => boolean;}
/** * The reason for a call failure. Either an error, or the a value that was * marked as a failure (when using result filtering). */export type FailureReason<ReturnType> = { error: Error } | { value: ReturnType };
/** * Event emitted on the `onFailure` calls. */export interface IFailureEvent { /** * Call duration, in milliseconds (with nanosecond precision, as the OS allows). */ duration: number;
/** * Whether the error was handled by the policy. */ handled: boolean;
/** * The reason for the error. */ reason: FailureReason<unknown>;}
/** * Event emitted on the `onSuccess` calls. */export interface ISuccessEvent { /** * Call duration, in milliseconds (with nanosecond precision, as the OS allows). */ duration: number;}
export interface IDefaultPolicyContext { /** * Abort signal for the operation. This is propagated through multiple * retry policies. */ signal: AbortSignal;}
/** * IPolicy is the type of all policies that Cockatiel provides. It describes * an execute() function which takes a generic argument. */export interface IPolicy< ContextType extends IDefaultPolicyContext = IDefaultPolicyContext, AltReturn = never,> { /** * Virtual property only used for TypeScript--will not actually be defined. * @deprecated This property does not exist */ readonly _altReturn: AltReturn;
/** * Fires on the policy when a request successfully completes and some * successful value will be returned. In a retry policy, this is fired once * even if the request took multiple retries to succeed. */ readonly onSuccess: Event<ISuccessEvent>;
/** * Fires on the policy when a request fails *due to a handled reason* fails * and will give rejection to the called. */ readonly onFailure: Event<IFailureEvent>;
/** * Runs the function through behavior specified by the policy. */ execute<T>( fn: (context: ContextType) => PromiseLike<T> | T, signal?: AbortSignal, ): Promise<T | AltReturn>;}
export interface IMergedPolicy<A extends IDefaultPolicyContext, B, W extends IPolicy<any, any>[]> extends IPolicy<A, B> { readonly wrapped: W;}
type MergePolicies<A, B> = A extends IPolicy<infer A1, any> ? B extends IPolicy<infer B1, any> ? IMergedPolicy< A1 & B1, A['_altReturn'] | B['_altReturn'], B extends IMergedPolicy<any, any, infer W> ? [A, ...W] : [A, B] > : never : never;
export class Policy { /** * Factory that builds a base set of filters that can be used in circuit * breakers, retries, etc. */ constructor(public readonly options: Readonly<IBasePolicyOptions>) {}
/** * Allows the policy to additionally handles errors of the given type. * * @param cls Class constructor to check that the error is an instance of. * @param predicate If provided, a function to be called with the error * which should return "true" if we want to handle this error. * @example * ```js * // retry both network errors and response errors with a 503 status code * new Policy() * .orType(NetworkError) * .orType(ResponseError, err => err.statusCode === 503) * .retry() * .attempts(3) * .execute(() => getJsonFrom('https://example.com')); * ``` */ public orType<T>(cls: Constructor<T>, predicate?: (error: T) => boolean) { const filter = typeFilter(cls, predicate); return new Policy({ ...this.options, errorFilter: e => this.options.errorFilter(e) || filter(e), }); }
/** * Allows the policy to additionally handles errors that pass the given * predicate function. * * @param predicate Takes any thrown error, and returns true if it should * be retried by this policy. * @example * ```js * // only retry if the error has a "shouldBeRetried" property set * new Policy() * .orWhen(err => err.shouldBeRetried === true) * .retry() * .attempts(3) * .execute(() => getJsonFrom('https://example.com')); * ``` */ public orWhen(predicate: (error: Error) => boolean) { return new Policy({ ...this.options, errorFilter: e => this.options.errorFilter(e) || predicate(e), }); }
/** * Adds handling for return values. The predicate will be called with * the return value of the executed function, * * @param predicate Takes the returned value, and returns true if it * should be retried by this policy. * @example * ```js * // retry when the response status code is a 5xx * new Policy() * .orResultWhen(res => res.statusCode >= 500) * .retry() * .attempts(3) * .execute(() => getJsonFrom('https://example.com')); * ``` */ public orWhenResult(predicate: (r: unknown) => boolean) { return new Policy({ ...this.options, resultFilter: r => this.options.resultFilter(r) || predicate(r), }); }
/** * Adds handling for return values. The predicate will be called with * the return value of the executed function, * * @param predicate Takes the returned value, and returns true if it * should be retried by this policy. * @example * ```js * // retry when the response status code is a 5xx * new Policy() * .orResultType(res => res.statusCode >= 500) * .retry() * .attempts(3) * .execute(() => getJsonFrom('https://example.com')); * ``` */ public orResultType<T>(cls: Constructor<T>, predicate?: (error: T) => boolean) { const filter = typeFilter(cls, predicate); return new Policy({ ...this.options, resultFilter: r => this.options.resultFilter(r) || filter(r), }); }}
export const noop = new NoopPolicy();
/** * A policy that handles all errors. */export const handleAll = new Policy({ errorFilter: always, resultFilter: never });
/** * See {@link Policy.orType} for usage. */export function handleType<T>(cls: Constructor<T>, predicate?: (error: T) => boolean) { return new Policy({ errorFilter: typeFilter(cls, predicate), resultFilter: never });}
/** * See {@link Policy.orWhen} for usage. */export function handleWhen(predicate: (error: Error) => boolean) { return new Policy({ errorFilter: predicate, resultFilter: never });}/** * See {@link Policy.orResultType} for usage. */export function handleResultType<T>(cls: Constructor<T>, predicate?: (error: T) => boolean) { return new Policy({ errorFilter: never, resultFilter: typeFilter(cls, predicate) });}
/** * See {@link Policy.orWhenResult} for usage. */export function handleWhenResult(predicate: (error: unknown) => boolean) { return new Policy({ errorFilter: never, resultFilter: predicate });}
/** * Creates a bulkhead--a policy that limits the number of concurrent calls. */export function bulkhead(limit: number, queue: number = 0) { return new BulkheadPolicy(limit, queue);}
/** * A decorator that can be used to wrap class methods and apply the given * policy to them. It also adds the last argument normally given in * {@link Policy.execute} as the last argument in the function call. * For example: * * ```ts * import { usePolicy, retry, handleAll } from 'cockatiel'; * * const retry = retry(handleAll, { maxAttempts: 3 }); * * class Database { * @usePolicy(retry) * public getUserInfo(userId, context, cancellationToken) { * console.log('Retry attempt number', context.attempt); * // implementation here * } * } * * const db = new Database(); * db.getUserInfo(3).then(info => console.log('User 3 info:', info)) * ``` * * Note that it will force the return type to be a Promise, since that's * what policies return. */export function usePolicy(policy: IPolicy<IDefaultPolicyContext, never>) { return (_target: unknown, _key: string, descriptor: PropertyDescriptor) => { const inner = descriptor.value; if (typeof inner !== 'function') { throw new Error(`Can only decorate functions with @cockatiel, got ${typeof inner}`); }
descriptor.value = function (this: unknown, ...args: any[]) { const signal = args[args.length - 1] instanceof AbortSignal ? args.pop() : undefined; return policy.execute(context => inner.apply(this, [...args, context]), signal); }; };}
/** * Creates a timeout policy. * @param duration - How long to wait before timing out execute()'d functions * @param strategy - Strategy for timeouts, "Cooperative" or "Aggressive". * A {@link CancellationToken} will be pass to any executed function, and in * cooperative timeouts we'll simply wait for that function to return or * throw. In aggressive timeouts, we'll immediately throw a * {@link TaskCancelledError} when the timeout is reached, in addition to * marking the passed token as failed. */export function timeout( duration: number, strategyOrOpts: TimeoutStrategy | { strategy: TimeoutStrategy; abortOnReturn: boolean },) { return new TimeoutPolicy( duration, typeof strategyOrOpts === 'string' ? { strategy: strategyOrOpts } : strategyOrOpts, );}
/** * Wraps the given set of policies into a single policy. For instance, this: * * ```js * retry.execute(() => * breaker.execute(() => * timeout.execute(({ cancellationToken }) => getData(cancellationToken)))) * ``` * * Is the equivalent to: * * ```js * Policy * .wrap(retry, breaker, timeout) * .execute(({ cancellationToken }) => getData(cancellationToken))); * ``` * * The `context` argument passed to the executed function is the merged object * of all previous policies. * */// The types here a certain unattrative. Ideally we could do// `wrap<A, B>(p: IPolicy<A, B>): IPolicy<A, B>`, but TS doesn't narrow the// types well in that scenario (unless p is explicitly typed as an IPolicy// and not some implementation) and returns `IPolicy<void, unknown>` and// the like. This is the best solution I've found for it.export function wrap<A extends IPolicy<IDefaultPolicyContext, unknown>>(p1: A): A;export function wrap< A extends IPolicy<IDefaultPolicyContext, unknown>, B extends IPolicy<IDefaultPolicyContext, unknown>,>(p1: A, p2: B): MergePolicies<A, B>;export function wrap< A extends IPolicy<IDefaultPolicyContext, unknown>, B extends IPolicy<IDefaultPolicyContext, unknown>, C extends IPolicy<IDefaultPolicyContext, unknown>,>(p1: A, p2: B, p3: C): MergePolicies<C, MergePolicies<A, B>>;export function wrap< A extends IPolicy<IDefaultPolicyContext, unknown>, B extends IPolicy<IDefaultPolicyContext, unknown>, C extends IPolicy<IDefaultPolicyContext, unknown>, D extends IPolicy<IDefaultPolicyContext, unknown>,>(p1: A, p2: B, p3: C, p4: D): MergePolicies<D, MergePolicies<C, MergePolicies<A, B>>>;export function wrap< A extends IPolicy<IDefaultPolicyContext, unknown>, B extends IPolicy<IDefaultPolicyContext, unknown>, C extends IPolicy<IDefaultPolicyContext, unknown>, D extends IPolicy<IDefaultPolicyContext, unknown>, E extends IPolicy<IDefaultPolicyContext, unknown>,>( p1: A, p2: B, p3: C, p4: D, p5: E,): MergePolicies<E, MergePolicies<D, MergePolicies<C, MergePolicies<A, B>>>>;export function wrap<C extends IDefaultPolicyContext, A>(...p: Array<IPolicy<C, A>>): IPolicy<C, A>;export function wrap<C extends IDefaultPolicyContext, A>( ...p: Array<IPolicy<C, A>>): IMergedPolicy<C, A, IPolicy<C, A>[]> { return { _altReturn: undefined as any, onFailure: p[0].onFailure, onSuccess: p[0].onSuccess, wrapped: p, execute<T>(fn: (context: C) => PromiseLike<T> | T, signal: AbortSignal): Promise<T | A> { const run = (context: C, i: number): PromiseLike<T | A> | T | A => i === p.length ? fn(context) : p[i].execute(next => run({ ...context, ...next }, i + 1), context.signal); return Promise.resolve(run({ signal } as C, 0)); }, };}
/** * Creates a retry policy. The options should contain the backoff strategy to * use. Included strategies are: * - {@link ConstantBackoff} * - {@link ExponentialBackoff} * - {@link IterableBackoff} * - {@link DelegateBackoff} (advanced) * * For example: * * ``` * import { handleAll, retry } from 'cockatiel'; * * const policy = retry(handleAll, { backoff: new ExponentialBackoff() }); * ``` * * You can optionally pass in the `attempts` to limit the maximum number of * retry attempts per call. */export function retry( policy: Policy, opts: { maxAttempts?: number; backoff?: IBackoffFactory<IRetryBackoffContext<unknown>>; },) { return new RetryPolicy( { backoff: opts.backoff || new ConstantBackoff(0), maxAttempts: opts.maxAttempts ?? Infinity }, new ExecuteWrapper(policy.options.errorFilter, policy.options.resultFilter), );}
/** * Returns a circuit breaker for the policy. **Important**: you should share * your circuit breaker between executions of whatever function you're * wrapping for it to function! * * ```ts * import { SamplingBreaker, Policy } from 'cockatiel'; * * // Break if more than 20% of requests fail in a 30 second time window: * const breaker = Policy * .handleAll() * .circuitBreaker(10_000, new SamplingBreaker(0.2, 30 * 1000)); * * export function handleRequest() { * return breaker.execute(() => getInfoFromDatabase()); * } * ``` * * @param halfOpenAfter Time after failures to try to open the circuit * breaker again. * @param breaker The circuit breaker to use. This package exports * ConsecutiveBreaker and SamplingBreakers for you to use. */export function circuitBreaker(policy: Policy, opts: { halfOpenAfter: number; breaker: IBreaker }) { return new CircuitBreakerPolicy( opts, new ExecuteWrapper(policy.options.errorFilter, policy.options.resultFilter), );}
/** * Falls back to the given value in the event of an error. * * ```ts * import { Policy } from 'cockatiel'; * * const fallback = Policy * .handleType(DatabaseError) * .fallback(() => getStaleData()); * * export function handleRequest() { * return fallback.execute(() => getInfoFromDatabase()); * } * ``` * * @param toValue Value to fall back to, or a function that creates the * value to return (any may return a promise) */export function fallback<R>(policy: Policy, valueOrFactory: (() => Promise<R> | R) | R) { return new FallbackPolicy( new ExecuteWrapper(policy.options.errorFilter, policy.options.resultFilter), // not technically type-safe, since if they actually want to _return_ // a function, that gets lost here. We'll just advice in the docs to // use a higher-order function if necessary. (typeof valueOrFactory === 'function' ? valueOrFactory : () => valueOrFactory) as () => R, );}
cockatiel
Version Info
5 months ago
