npm package: @polywrap/uri-resolver-extensions-js
Description: Polywrap URI resolver extensions
Latest version: 0.12.2

# @polywrap/uri-resolver-extensions-js

<a href="https://www.npmjs.com/package/@polywrap/uri-resolver-extensions-js" target="_blank" rel="noopener noreferrer">
<img src="https://img.shields.io/npm/v/@polywrap/uri-resolver-extensions-js.svg" alt="npm"/>
</a>

<br/>
<br/>
Polywrap URI resolver extensions to customize resolution in the Polywrap Client.

## Installation

```bash
npm install --save @polywrap/uri-resolver-extensions-js
```

## Usage

If you build a configuration for the Polywrap client using the `PolywrapClientConfigBuilder` in the `@polywrap/client-config-builder-js` package, the `ExtendableUriResovler` is included by default. In that case you only need to register implementations of the URI Resolver Extension interface.

Otherwise, you must also add the `ExtendableUriResolver` to your resolver.

```ts
  const clientConfig: CoreClientConfig = {
    interfaces: new UriMap<Uri[]>([
      [
        Uri.from("wrapscan.io/polywrap/uri-resolver@1.0"),
        [
          Uri.from("wrapscan.io/polywrap/file-system-uri-resolver@1.0.0"),
          Uri.from("wrapscan.io/polywrap/http-uri-resolver@1.0.0"),
          Uri.from("wrapscan.io/polywrap/ipfs-uri-resolver-async@1.0.0"),
          Uri.from("wrapscan.io/polywrap/wrapscan-uri-resolver@1.0.0"),
        ],
      ],
    ]),
    resolver: RecursiveResolver.from(
      [
        StaticResolver.from([
          ...redirects,
          ...wrappers,
          ...packages,
        ]),
        new ExtendableUriResolver(),
      ]
    )
  };
```

# Reference

## ExtendableUriResolver

```ts
/**
 * A Uri Resolver that delegates resolution to wrappers implementing the
 * URI Resolver Extension Interface.
 * */
export class ExtendableUriResolver extends UriResolverAggregatorBase<
  Error,
  Error
> 
```

### Properties

#### extInterfaceUri (static)

```ts
  /** The supported interface URIs to which resolver-ext implementations should be registered */
  public static defaultExtInterfaceUris: Uri[] = [
    Uri.from("wrapscan.io/polywrap/uri-resolver@1.0"),
  ];
```

#### extInterfaceUri

```ts
  /** The active interface URIs to which implementations should be registered */
  public readonly extInterfaceUris: Uri[];
```

### constructor

```ts
  /**
   * Create an ExtendableUriResolver
   *
   * @param extInterfaceUris - URI Resolver Interface URIs
   * @param resolverName - Name to use in resolution history output
   * */
  constructor(
    extInterfaceUris: Uri[] = ExtendableUriResolver.defaultExtInterfaceUris,
    resolverName = "ExtendableUriResolver"
  ) 
```

### Methods

#### getUriResolvers

```ts
  /**
   * Get a list of URI Resolvers
   *
   * @param uri - the URI to query for resolvers
   * @param client - a CoreClient instance that can be used to make an invocation
   * @param resolutionContext - the current URI resolution context
   *
   * @returns a list of IUriResolver or an error
   * */
  async getUriResolvers(
    uri: Uri,
    client: CoreClient,
    resolutionContext: IUriResolutionContext
  ): Promise<Result<IUriResolver<unknown>[], Error>> 
```

#### tryResolverUri

```ts
  /**
   * Resolve a URI to a wrap package, a wrapper, or a URI.
   * Attempts resolution with each the URI Resolver Extension wrappers sequentially.
   *
   * @param uri - the URI to resolve
   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
   * @param resolutionContext - the current URI resolution context
   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
   */
  async tryResolveUri(
    uri: Uri,
    client: CoreClient,
    resolutionContext: IUriResolutionContext
  ): Promise<Result<UriPackageOrWrapper, Error>> 
```

#### getStepDescription (protected)

```ts
  /**
   * A utility function for generating step descriptions to facilitate resolution context updates
   *
   * @returns text describing the URI resolution step
   * */
  protected getStepDescription = (): string 
```

## UriResolverExtensionFileReader

```ts
/** An IFileReader that reads files by invoking URI Resolver Extension wrappers */
export class UriResolverExtensionFileReader implements IFileReader 
```

### constructor

```ts
  /**
   * Construct a UriResolverExtensionFileReader
   *
   * @param _resolverExtensionUri - URI of the URI Resolver Extension wrapper
   * @param _wrapperUri - URI of the wrap package to read from
   * @param _client - A CoreClient instance
   * */
  constructor(
    private readonly _resolverExtensionUri: Uri,
    private readonly _wrapperUri: Uri,
    private readonly _client: CoreClient
  ) 
```

### Methods

#### readFile

```ts
  /**
   * Read a file
   *
   * @param filePath - the file's path from the wrap package root
   *
   * @returns a Result containing a buffer if successful, or an error
   * */
  async readFile(filePath: string): Promise<Result<Uint8Array, Error>> 
```

## UriResolverWrapper

```ts
/**
 * An IUriResolver that delegates resolution to a wrapper that implements
 * the URI Resolver Extension Interface
 * */
export class UriResolverWrapper implements IUriResolver<unknown> 
```

### constructor

```ts
  /**
   * construct a UriResolverWrapper
   *
   * @param implementationUri - URI that resolves to a URI Resolver Extension implementation
   * */
  constructor(public readonly implementationUri: Uri) 
```

### Methods

#### tryResolverUri

```ts
  /**
   * Attempt to resolve a URI by invoking a URI Resolver Extension wrapper, then
   * parse the result to a wrap package, a wrapper, or a URI
   *
   * @param uri - the URI to resolve
   * @param client - a CoreClient instance that may be used to invoke a wrapper that implements the UriResolver interface
   * @param resolutionContext - the current URI resolution context
   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
   */
  async tryResolveUri(
    uri: Uri,
    client: CoreClient,
    resolutionContext: IUriResolutionContext
  ): Promise<Result<UriPackageOrWrapper, unknown>> 
```

## Development

This package is open-source. It lives within the [Polywrap JavaScript Client repository](https://github.com/polywrap/javascript-client). Contributions from the community are welcomed!

### Build

```bash
nvm use && yarn install && yarn build
```

### Test

```bash
yarn test
```