@polywrap/core-client-js

@polywrap/core-client-js

The Polywrap JavaScript core client invokes wrapper functions. It's designed to run in any environment that can execute JavaScript (think websites, node scripts, etc.). It has TypeScript support.

Installation

npm install --save @polywrap/core-client-js

Usage

Instantiate

Use the @polywrap/client-config-builder-js package to build a CoreClientConfig for your project, then use the PolywrapCoreClient constructor to instantiate the client with your config.

  const config = new PolywrapClientConfigBuilder().addDefaults().build();

  const client = new PolywrapCoreClient(config);

Invoke

Invoke a wrapper.

  const result = await client.invoke({
    uri: Uri.from("wrapscan.io/polywrap/logging@1.0"),
    method: "info",
    args: {
      message: "Hello World!",
    },
  });

  if (!result.ok) throw result.error;

  const value = result.value;

Reference

PolywrapCoreClient

Constructor

  /**
   * Instantiate a PolywrapClient
   *
   * @param config - a core client configuration
   */
  constructor(private _config: CoreClientConfig) 

getConfig

  /**
   * Returns the configuration used to instantiate the client
   *
   * @returns an immutable Polywrap client config
   */
  public getConfig(): CoreClientConfig 

getInterfaces

  /**
   * returns all interfaces from the configuration used to instantiate the client
   *
   * @returns an array of interfaces and their registered implementations
   */
  public getInterfaces(): ReadonlyUriMap<readonly Uri[]> | undefined 

getEnvs

  /**
   * returns all env registrations from the configuration used to instantiate the client
   *
   * @returns an array of env objects containing wrapper environmental variables
   */
  public getEnvs(): ReadonlyUriMap<WrapperEnv> | undefined 

getResolver

  /**
   * returns the URI resolver from the configuration used to instantiate the client
   *
   * @returns an object that implements the IUriResolver interface
   */
  public getResolver(): IUriResolver<unknown> 

getEnvByUri

  /**
   * returns an env (a set of environmental variables) from the configuration used to instantiate the client
   *
   * @param uri - the URI used to register the env
   * @returns an env, or undefined if an env is not found at the given URI
   */
  public getEnvByUri(uri: Uri): WrapperEnv | undefined 

getManifest

  /**
   * returns a package's wrap manifest
   *
   * @param uri - a wrap URI
   * @returns a Result containing the WrapManifest if the request was successful
   */
  public async getManifest(
    uri: Uri
  ): Promise<Result<WrapManifest, WrapError>> 

getFile

  /**
   * returns a file contained in a wrap package
   *
   * @param uri - a wrap URI
   * @param options - { path: string; encoding?: "utf-8" | string }
   * @returns a Promise of a Result containing a file if the request was successful
   */
  public async getFile(
    uri: Uri,
    options: GetFileOptions
  ): Promise<Result<string | Uint8Array, WrapError>> 

getImplementations

  /**
   * returns the interface implementations associated with an interface URI
   *  from the configuration used to instantiate the client
   *
   * @param uri - a wrap URI
   * @param options - { applyResolution?: boolean; resolutionContext?: IUriResolutionContext }
   * @returns a Result containing URI array if the request was successful
   */
  public async getImplementations(
    uri: Uri,
    options: GetImplementationsOptions = {}
  ): Promise<Result<Uri[], WrapError>> 

invokeWrapper

  /**
   * Invoke a wrapper using an instance of the wrapper.
   *
   * @param options - {
   *   // The Wrapper's URI
   *   uri: TUri;
   *
   *   // Method to be executed.
   *   method: string;
   *
   *   //Arguments for the method, structured as a map, removing the chance of incorrectly ordered arguments.
   *    args?: Record<string, unknown> | Uint8Array;
   *
   *   // Env variables for the wrapper invocation.
   *    env?: Record<string, unknown>;
   *
   *   // A Uri resolution context
   *   resolutionContext?: IUriResolutionContext;
   *
   *   // if true, return value is a msgpack-encoded byte array
   *   encodeResult?: boolean;
   *
   *   // The wrapper to invoke
   *   wrapper: Wrapper
   * }
   * @returns A Promise with a Result containing the return value or an error
   */
  public async invokeWrapper<TData = unknown>(
    options: InvokerOptions & { wrapper: Wrapper }
  ): Promise<InvokeResult<TData>> 

invoke

  /**
   * Invoke a wrapper.
   *
   * @remarks
   * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper.
   *
   * @param options - {
   *   // The Wrapper's URI
   *   uri: TUri;
   *
   *   // Method to be executed.
   *   method: string;
   *
   *   //Arguments for the method, structured as a map, removing the chance of incorrectly ordered arguments.
   *    args?: Record<string, unknown> | Uint8Array;
   *
   *   // Env variables for the wrapper invocation.
   *    env?: Record<string, unknown>;
   *
   *   // A Uri resolution context
   *   resolutionContext?: IUriResolutionContext;
   *
   *   // if true, return value is a msgpack-encoded byte array
   *   encodeResult?: boolean;
   * }
   * @returns A Promise with a Result containing the return value or an error
   */
  public async invoke<TData = unknown>(
    options: InvokerOptions
  ): Promise<InvokeResult<TData>> 

tryResolveUri

  /**
   * Resolve a URI to a wrap package, a wrapper, or a uri
   *
   * @param options - { uri: TUri; resolutionContext?: IUriResolutionContext }
   * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful
   */
  public async tryResolveUri(
    options: TryResolveUriOptions
  ): Promise<Result<UriPackageOrWrapper, unknown>> 

loadWrapper

  /**
   * Resolve a URI to a wrap package or wrapper.
   * If the URI resolves to wrap package, load the wrapper.
   *
   * @remarks
   * Unlike other methods, `loadWrapper` does not accept a string URI.
   * You can create a Uri (from the `@polywrap/core-js` package) using `Uri.from("wrap://...")`
   *
   * @param uri - the Uri to resolve
   * @param resolutionContext? - a resolution context
   * @param options - { noValidate?: boolean }
   * @returns A Promise with a Result containing a Wrapper or Error
   */
  public async loadWrapper(
    uri: Uri,
    resolutionContext?: IUriResolutionContext,
    options?: DeserializeManifestOptions
  ): Promise<Result<Wrapper, WrapError>> 

Development

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

Build

nvm use && yarn install && yarn build

Test

yarn test
``