@polywrap/uri-resolvers

URI resolvers to customize URI resolution in the Polywrap Client.

Installation

1npm install --save @polywrap/uri-resolvers-js

Usage

This example is similar to the default resolver used by the PolywrapClientConfigBuilder in the @polywrap/client-config-builder-js package.

1  const resolver = RecursiveResolver.from(
2    WrapperCacheResolver.from(
3      [
4        StaticResolver.from([
5            ...redirects,
6            ...wrappers,
7            ...packages,
8          ]),
9      ],
10      new WrapperCache()
11    )
12  );

Reference

UriResolverAggregatorBase

1/**
2 * Abstract class for IUriResolver implementations that aggregate multiple resolvers.
3 * The UriResolverAggregatorBase class attempts to resolve a URI by sequentially
4 * attempting resolution with each of its composite resolvers.
5 * */
6export abstract class UriResolverAggregatorBase<
7  TResolutionError = undefined,
8  TGetResolversError = undefined
9> implements IUriResolver<TResolutionError | TGetResolversError> 

Methods

getUriResolvers

1  /**
2   * Get a list of URI Resolvers
3   *
4   * @param uri - the URI to query for resolvers
5   * @param client - a CoreClient instance that can be used to make an invocation
6   * @param resolutionContext - a resolution context to update when resolving URIs
7   *
8   * @returns a list of IUriResolver or an error
9   * */
10  abstract getUriResolvers(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<IUriResolver<unknown>[], TGetResolversError>>;

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * Attempts to resolve the URI using each of the aggregated resolvers sequentially.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  async tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<
15    Result<UriPackageOrWrapper, TResolutionError | TGetResolversError>
16  > 

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @param uri - the URI being resolved
5   * @param result - the result of a resolution attempt
6   *
7   * @returns text describing the URI resolution step
8   * */
9  protected abstract getStepDescription(
10    uri: Uri,
11    result: Result<UriPackageOrWrapper, TResolutionError>
12  ): string;

tryResolveUriWithResolvers (protected)

1  /**
2   * Using each of the aggregated resolvers, attempt to resolve a URI
3   *
4   * @param uri - the URI to resolve
5   * @param client - a CoreClient instance that can be used to make an invocation
6   * @param resolvers - a list of IUriResolver implementations
7   * @param resolutionContext - a resolution context to update when resolving URIs
8   *
9   * @returns a URI, a Wrap Package, or a Wrapper (or an error)
10   * */
11  protected async tryResolveUriWithResolvers(
12    uri: Uri,
13    client: CoreClient,
14    resolvers: IUriResolver<unknown>[],
15    resolutionContext: IUriResolutionContext
16  ): Promise<Result<UriPackageOrWrapper, TResolutionError>> 

UriResolverAggregator

1/**
2 * An implementation of UriResolverAggregatorBase
3 */
4export class UriResolverAggregator<
5  TResolutionError = undefined,
6  TGetResolversError = undefined
7> extends UriResolverAggregatorBase<
8  TResolutionError,
9  TGetResolversError
10> 

Types

GetResolversFunc

1/**
2 * A function that returns a list of resolvers
3 *
4 * @param uri - the URI to query
5 * @param client - a CoreClient instance
6 * */
7export type GetResolversFunc = (
8  uri: Uri,
9  client: CoreClient
10) => Promise<IUriResolver<unknown>[]>;

GetResolversWithErrorFunc

1/**
2 * A function that returns a list of resolvers or an error
3 *
4 * @param uri - the URI to query
5 * @param client - a CoreClient instance
6 * */
7export type GetResolversWithErrorFunc<TError> = (
8  uri: Uri,
9  client: CoreClient
10) => Promise<Result<IUriResolver<unknown>[], TError>>;

Methods

constructor

1  /**
2   * Creates a UriResolverAggregator from a list of resolvers, or from a function
3   * that returns a list of resolvers
4   * */
5  constructor(resolvers: UriResolverLike[], resolverName?: string);
6  constructor(
7    resolvers: (
8      uri: Uri,
9      client: CoreClient
10    ) => Promise<Result<IUriResolver<unknown>[], TGetResolversError>>,
11    resolverName?: string
12  );
13  constructor(resolvers: GetResolversFunc, resolverName?: string);
14  constructor(
15    resolvers:
16      | UriResolverLike[]
17      | GetResolversFunc
18      | GetResolversWithErrorFunc<TGetResolversError>,
19    private _resolverName?: string
20  ) 

getUriResolvers

1  /**
2   * Get a list of URI Resolvers
3   *
4   * @param uri - the URI to query for resolvers
5   * @param client - a CoreClient instance that can be used to make an invocation
6   *
7   * @returns a list of IUriResolver or an error
8   * */
9  async getUriResolvers(
10    uri: Uri,
11    client: CoreClient
12  ): Promise<Result<IUriResolver<unknown>[], TGetResolversError>> 

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @returns text describing the URI resolution step
5   * */
6  protected getStepDescription = (): string 

IWrapperCache

1/** A Wrapper cache */
2export interface IWrapperCache {
3  /** get a Wrapper from the cache, given its URI index */
4  get(uri: Uri): MaybeAsync<Wrapper | undefined>;
5
6  /** add a Wrapper to the cache, indexed by a URI */
7  set(uri: Uri, wrapper: Wrapper): MaybeAsync<void>;
8}

WrapperCache

1/**
2 * A minimal implementation of IWrapperCache
3 * */
4export class WrapperCache implements IWrapperCache 

Methods

get

1  /** get a Wrapper from the cache, given its URI index */
2  get(uri: Uri): Wrapper | undefined 

set

1  /** add a Wrapper to the cache, indexed by a URI */
2  set(uris: Uri, wrapper: Wrapper): void 

WrapperCacheResolver

1/**
2 * An IUriResolver implementation that caches wrappers once they are resolved.
3 * As it is a wrapper cache resolver, URI and package caching is outside of the scope for this resolver
4 * and can be achieved through other resolvers if necessary.
5 * The WrapperCacheResolver wraps an IUriResolver implementation and delegates resolution to it.
6 * */
7export class WrapperCacheResolver<TError>
8  implements IUriResolver<TError | Error> 

constructor

1  /**
2   * Creates a WrapperCacheResolver
3   *
4   * @param _innerResolver - a resolver to delegate resolution to
5   * @param _cache - a wrapper cache
6   * */
7  constructor(
8    private _innerResolver: IUriResolver<TError>,
9    private _cache: IWrapperCache
10  ) 

Methods

from

1  /**
2   * Creates a WrapperCacheResolver from a resolver-like object
3   *
4   * @param innerResolver - a resolver-like item to delegate resolution to
5   * @param cache - a wrapper cache
6   * @param options - control wrapper manifest deserialization
7   *
8   * @returns a WrapperCacheResolver
9   * */
10  static from<TResolverError = unknown>(
11    innerResolver: UriResolverLike,
12    cache: IWrapperCache
13  ): WrapperCacheResolver<TResolverError> 

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * If successful, cache the result.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  async tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<UriPackageOrWrapper, TError | Error>> 

getUriResolutionPath

1/**
2 * Get a resolution path from the history of a URI resolution attempt
3 *
4 * @param history - the resolution context
5 * @returns the URI's resolution path
6 * */
7export const getUriResolutionPath = (
8  history: IUriResolutionStep<unknown>[]
9): IUriResolutionStep<unknown>[] 

InfiniteLoopError

1/**
2 * Error used if the URI resolution path contains an infinite loop
3 * */
4export class InfiniteLoopError extends Error 

constructor

1  /**
2   * Create an InfiniteLoopError
3   *
4   * @param _uri - URI being resolved
5   * @param _history - URI resolution history
6   * */
7  constructor(
8    private readonly _uri: Uri,
9    private readonly _history: IUriResolutionStep<unknown>[]
10  ) 

ResolverWithHistory

1/** An abstract IUriResolver implementation that updates the resolution context */
2export abstract class ResolverWithHistory<TError = undefined>
3  implements IUriResolver<TError> 

Methods

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * Updates the resolution context with the result.
4   *
5   * @remarks
6   * This method calls the internal abstract method _tryResolveUri before
7   * updating the resolution context. Implementations are expect to place
8   * resolution logic in _tryResolveUri.
9   *
10   * @param uri - the URI to resolve
11   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
12   * @param resolutionContext - the current URI resolution context
13   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
14   */
15  async tryResolveUri(
16    uri: Uri,
17    client: CoreClient,
18    resolutionContext: IUriResolutionContext
19  ): Promise<Result<UriPackageOrWrapper, TError>> 

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @param uri - the URI being resolved
5   * @param result - the result of a resolution attempt
6   *
7   * @returns text describing the URI resolution step
8   * */
9  protected abstract getStepDescription(
10    uri: Uri,
11    result: Result<UriPackageOrWrapper, TError>
12  ): string;

_tryResolveUri (protected)

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * Updates the resolution context with the result.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  protected abstract _tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<UriPackageOrWrapper, TError>>;

ResolverWithLoopGuard

1/** An IUriResolver implementation that prevents infinite loops in the resolution path. */
2export class ResolverWithLoopGuard<TError = undefined>
3  implements IUriResolver<TError | InfiniteLoopError> 

constructor

1  /**
2   * Construct a ResolverWithLoopGuard
3   *
4   * @param _resolver - a resolution to delegate resolution to
5   * */
6  constructor(private _resolver: IUriResolver<TError>) 

Methods

from

1  /**
2   * Create a ResolverWithLoopGuard from a resolver-like object
3   *
4   * @param resolver - a resolver-like item to delegate resolution to
5   *
6   * @returns a ResolverWithLoopGuard
7   * */
8  static from<TResolverError = unknown>(
9    resolver: UriResolverLike
10  ): ResolverWithLoopGuard<TResolverError> 

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * Ensures the URI is not caught in an infinite loop by checking if it is already resolving.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  async tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<UriPackageOrWrapper, TError | InfiniteLoopError>> 

PackageToWrapperResolver

1/**
2 * An IUriResolver implementation that initalizes wrappers from resolved packages.
3 * The PackageToWrapperResolver wraps an IUriResolver implementation and delegates resolution to it.
4 * */
5export class PackageToWrapperResolver<TError>
6  implements IUriResolver<TError | Error> 

constructor

1  /**
2   * Creates a PackageToWrapperResolver
3   *
4   * @param _innerResolver - a resolver to delegate resolution to
5   * @param _options - control wrapper manifest deserialization
6   * */
7  constructor(
8    private _innerResolver: IUriResolver<TError>,
9    private _options?: {
10      deserializeManifestOptions?: DeserializeManifestOptions;
11    }
12  ) 

Methods

from

1  /**
2   * Creates a PackageToWrapperResolver from a resolver-like object
3   *
4   * @param innerResolver - a resolver-like item to delegate resolution to
5   * @param options - control wrapper manifest deserialization
6   *
7   * @returns a PackageToWrapperResolver
8   * */
9  static from<TResolverError = unknown>(
10    innerResolver: UriResolverLike,
11    options?: { deserializeManifestOptions?: DeserializeManifestOptions }
12  ): PackageToWrapperResolver<TResolverError> 

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * If successful, cache the result.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  async tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<UriPackageOrWrapper, TError | Error>> 

UriResolver

1/** An IUriResolver factory */
2export class UriResolver 

Methods

from

1  /**
2   * Create an IUriResolver instance
3   *
4   * @param resolverLike - an object that can be transformed into a resolver
5   * @param resolverName - a name to assign to the resolver in resolution history output
6   * */
7  static from<TError = undefined>(
8    resolverLike: UriResolverLike,
9    resolverName?: string
10  ): IUriResolver<TError> 

UriResolverLike

1/** An UriResolverLike can be one of three things:
2 * - An IUriResolver
3 * - An object that can be transformed into a static IUriResolver
4 * - An array of UriResolverLike
5 * */
6export type UriResolverLike =
7  | IUriResolver<unknown>
8  | IUriRedirect
9  | IUriPackage
10  | IUriWrapper
11  | UriResolverLike[];

UriResolutionResult

1/** Factory for creating Result from URI resolution output */
2export class UriResolutionResult<TError = undefined> 

Methods

ok

1  /** Returns a Result with `ok` set to true */
2  static ok<TError = undefined>(uri: Uri): Result<UriPackageOrWrapper, TError>;
3  static ok<TError = undefined>(
4    uri: Uri,
5    wrapPackage: IWrapPackage
6  ): Result<UriPackageOrWrapper, TError>;
7  static ok<TError = undefined>(
8    uri: Uri,
9    wrapper: Wrapper
10  ): Result<UriPackageOrWrapper, TError>;
11  static ok<TError = undefined>(
12    uriPackageOrWrapper: UriPackageOrWrapper
13  ): Result<UriPackageOrWrapper, TError>;
14  static ok<TError = undefined>(
15    uriPackageOrWrapper: Uri | UriPackageOrWrapper,
16    packageOrWrapper?: IWrapPackage | Wrapper
17  ): Result<UriPackageOrWrapper, TError> 

err

1  /** Returns a Result with `ok` set to false */
2  static err<TError = unknown>(
3    error: TError
4  ): Result<UriPackageOrWrapper, TError> 

PackageResolver

1/**
2 * A Uri Resolver that resolves to an embedded wrap package and correctly updates
3 * the resolution history.
4 * */
5export class PackageResolver extends ResolverWithHistory 

constructor

1  /**
2   * Construct a PackageResolver
3   *
4   * @param _uri - the URI to redirect to the wrap package
5   * @param wrapPackage - a wrap package
6   * */
7  constructor(private _uri: Uri, private wrapPackage: IWrapPackage) 

Methods

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @returns text describing the URI resolution step
5   * */
6  protected getStepDescription = (): string 

_tryResolveUri (protected)

1  /**
2   * Resolve a URI to a wrap package
3   *
4   * @param uri - the URI to resolve
5   * @returns A Promise with a Result containing a wrap package if successful
6   */
7  protected async _tryResolveUri(
8    uri: Uri
9  ): Promise<Result<UriPackageOrWrapper>> 

RedirectResolver

1/**
2 * A Uri Resolver that resolves to a new URI and correctly updates the
3 * resolution history.
4 * */
5export class RedirectResolver<
6  TUri extends string | Uri = string
7> extends ResolverWithHistory 

constructor

1  /**
2   * Construct a RedirectResolver
3   *
4   * @param from - the URI to redirect from
5   * @param to - the URI to redirect to
6   * */
7  constructor(from: TUri, to: TUri) 

Methods

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @returns text describing the URI resolution step
5   * */
6  protected getStepDescription = (): string 

_tryResolveUri (protected)

1  /**
2   * Resolve a URI to a new URI
3   *
4   * @param uri - the URI to resolve
5   * @returns A Promise with a Result containing a URI if successful
6   */
7  protected async _tryResolveUri(
8    uri: Uri
9  ): Promise<Result<UriPackageOrWrapper>> 

WrapperResolver

1/**
2 * A Uri Resolver that resolves to an embedded wrapper and correctly updates
3 * the resolution history.
4 * */
5export class WrapperResolver extends ResolverWithHistory 

constructor

1  /**
2   * Construct a WrapperResolver
3   *
4   * @param _uri - the URI to redirect to the wrapper instance
5   * @param _wrapper - a wrapper
6   * */
7  constructor(private _uri: Uri, private _wrapper: Wrapper) 

Methods

getStepDescription (protected)

1  /**
2   * A utility function for generating step descriptions to facilitate resolution context updates
3   *
4   * @returns text describing the URI resolution step
5   * */
6  protected getStepDescription = (): string 

_tryResolveUri

1  /**
2   * Resolve a URI to a wrapper
3   *
4   * @param uri - the URI to resolve
5   * @returns A Promise with a Result containing a wrapper if successful
6   */
7  protected async _tryResolveUri(
8    uri: Uri
9  ): Promise<Result<UriPackageOrWrapper>> 

StaticResolver

1/**
2 * An IUriResolver implementation that efficiently delegates URI resolution to
3 * static resolvers--i.e. those that resolve to embedded URIs, Wrappers, and Packages
4 * */
5export class StaticResolver<TError = undefined>
6  implements IUriResolver<TError> 

constructor

1  /**
2   * Construct a Static Resolver
3   *
4   * @param uriMap - a mapping of URI to embedded URI, package, or wrapper
5   * */
6  constructor(public uriMap: Map<string, UriPackageOrWrapper>) 

Methods

from

1  /**
2   * Create a StaticResolver from a static-resolver-like object
3   *
4   * @param staticResolverLikes - an array of resolver-like objects to delegate resolution to
5   *
6   * @returns a StaticResolver
7   * */
8  static from<TError = undefined>(
9    staticResolverLikes: UriResolverLike[]
10  ): StaticResolver<TError> 

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   *
4   * @param uri - the URI to resolve
5   * @param _ - not used
6   * @param resolutionContext - the current URI resolution context
7   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
8   */
9  async tryResolveUri(
10    uri: Uri,
11    _: CoreClient,
12    resolutionContext: IUriResolutionContext
13  ): Promise<Result<UriPackageOrWrapper, TError>> 

StaticResolverLike

1/** A StaticResolverLike can be one of two things:
2 * - An object that can be transformed into a static IUriResolver
3 * - An array of StaticResolverLike
4 * */
5export type StaticResolverLike =
6  | IUriRedirect
7  | IUriPackage
8  | IUriWrapper
9  | StaticResolverLike[];

RequestSynchronizerResolver

1/* Uri resolver that synchronizes requests to the same URI
2 * Multiple requests to the same URI will be resolved only once
3 * and the result will be cached for subsequent requests (only for the duration of that first request)
4 * Can use the `shouldIgnoreCache` option to determine whether to ignore the cached request in case of an error
5 * (default is to use the cache)
6 */
7export class RequestSynchronizerResolver<TError>
8  implements IUriResolver<TError> 

constructor

1  /**
2   * Construct a RequestSynchronizerResolver
3   *
4   * @param resolverToSynchronize - the inner resolve whose resolution will be synchronized
5   * @param options - the optional options containing the `shouldIgnoreCache` error handler
6   * */
7  constructor(
8    private resolverToSynchronize: IUriResolver<TError>,
9    private options?: {
10      shouldIgnoreCache?: (error: TError | undefined) => boolean;
11    }
12  ) 

Methods

from

1  /**
2   * Create a RequestSynchronizerResolver from a static-resolver-like object
3   *
4   * @param resolver - a resolver-like object whose resolution will be synchronized
5   * @param options - the optional options containing the `shouldIgnoreCache` error handler
6   *
7   * @returns a RequestSynchronizerResolver
8   * */
9  static from<TResolverError = unknown>(
10    resolver: UriResolverLike,
11    options?: {
12      shouldIgnoreCache?: (error: TResolverError | undefined) => boolean;
13    }
14  ): RequestSynchronizerResolver<TResolverError> 

tryResolveUri

1  /**
2   * Resolve a URI to a wrap package, a wrapper, or a URI.
3   * Attempts to resolve the URI using each of the aggregated resolvers sequentially.
4   *
5   * @param uri - the URI to resolve
6   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
7   * @param resolutionContext - the current URI resolution context
8   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
9   */
10  async tryResolveUri(
11    uri: Uri,
12    client: CoreClient,
13    resolutionContext: IUriResolutionContext
14  ): Promise<Result<UriPackageOrWrapper, TError>> 

Development

This package is open-source. It lives within the Polywrap JavaScript Client repository. Contributions from the community are welcomed!

Build

1nvm use && yarn install && yarn build

Test

1yarn test
2``