@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

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

Usage

$3

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.

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

const client = new PolywrapCoreClient(config);
`

$3

Invoke a wrapper.

`ts
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

$3


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

$3

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

$3

`ts
/**
* returns all interfaces from the configuration used to instantiate the client
*
* @returns an array of interfaces and their registered implementations
*/
public getInterfaces(): ReadonlyUriMap | undefined
`

$3

`ts
/**
* 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 | undefined
`

$3

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

$3

`ts
/**
* 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
`

$3

`ts
/**
* 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>
`

$3

`ts
/**
* 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>
`

$3

`ts
/**
* 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>
`

$3

`ts
/**
* 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 | Uint8Array;
*
* // Env variables for the wrapper invocation.
* env?: Record;
*
* // 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(
options: InvokerOptions & { wrapper: Wrapper }
): Promise>
`

$3

`ts
/**
* 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 | Uint8Array;
*
* // Env variables for the wrapper invocation.
* env?: Record;
*
* // 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(
options: InvokerOptions
): Promise>
`

$3

`ts
/**
* 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>
`

$3

`ts
/**
* 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>
`

Development

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

$3

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

$3

`bash
yarn test
`