From a095840fd059aefc45b992dd57221de19e50ee23 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 20 Dec 2022 21:20:57 +0530 Subject: [PATCH 01/25] updated readme for client and core-client --- packages/js/client/README.md | 310 ++------------ packages/js/core-client/README.md | 379 ++++++++++++++++++ .../js/core-client/src/PolywrapCoreClient.ts | 22 +- 3 files changed, 415 insertions(+), 296 deletions(-) diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 1ff5cf7bd4..490480b018 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -7,6 +7,8 @@
The Polywrap JavaScript client invokes functions of wrappers and plugins. It's designed to run in any environment that can execute JavaScript (think websites, node scripts, etc.). It has TypeScript support. +The Polywrap client extends the PolywrapCoreClient to provide UX features, such as an additional constructor and additional configuration options. + ## Installation ```bash @@ -45,11 +47,21 @@ const config = { to: "wrap://ens/to.eth", } ], - // declare and configure plugin wrappers - plugins: [ + // add embedded Wasm wrappers + wrappers: [ + { + uri: "wrap://fs/simple/wrapper/uri/build", + wrapper: WasmWrapper.from( + fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.info")), + fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.wasm")) + ) + } + ], + // add and configure embedded plugin wrappers + packages: [ { uri: "wrap://ens/ipfs.polywrap.eth", - plugin: ipfsPlugin({}), + package: ipfsPlugin({}), }, ], // declare interface implementations @@ -70,15 +82,14 @@ const config = { }, }, ], - - // ADVANCED USAGE: - // customize URI resolution - resolver: new RecursiveResolver( - new PackageToWrapperCacheResolver(wrapperCache, [ - new ExtendableUriResolver(), - ]) - ), + resolvers: [ + new RecursiveResolver( + new PackageToWrapperCacheResolver(wrapperCache, [ + new ExtendableUriResolver(), + ]) + ) + ], // custom wrapper cache wrapperCache: new WrapperCache(), @@ -105,277 +116,10 @@ const altClient = new PolywrapClient(config, { noDefaults: true }); * @param config - a whole or partial client configuration * @param options - { noDefaults?: boolean } */ -constructor(config?: Partial>, options?: { - noDefaults?: boolean; +constructor(config?: Partial, options?: { + noDefaults?: false; +}); +constructor(config: PolywrapCoreClientConfig, options: { + noDefaults: true; }); -``` - -### getConfig -```ts -/** - * Returns the configuration used to instantiate the client - * - * @returns an immutable Polywrap client config - */ -getConfig(): PolywrapCoreClientConfig; -``` - -### setTracingEnabled -```ts -/** - * Enable tracing for intricate debugging - * - * @remarks - * Tracing uses the @polywrap/tracing-js package - * - * @param tracerConfig - configure options such as the tracing level - * @returns void - */ -setTracingEnabled(tracerConfig?: Partial): void; -``` - -### getInterfaces -```ts -/** - * returns all interfaces from the configuration used to instantiate the client - * - * @returns an array of interfaces and their registered implementations - */ -getInterfaces(): readonly InterfaceImplementations[]; -``` - -### getEnvs -```ts -/** - * returns all env registrations from the configuration used to instantiate the client - * - * @returns an array of env objects containing wrapper environmental variables - */ -getEnvs(): readonly Env[]; -``` - -### getResolver -```ts -/** - * returns the URI resolver from the configuration used to instantiate the client - * - * @returns an object that implements the IUriResolver interface - */ -getResolver(): IUriResolver; -``` - -### getEnvByUri -```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 - */ -getEnvByUri(uri: TUri): Env | undefined; -``` - -### getManifest -```ts -/** - * returns a package's wrap manifest - * - * @param uri - a wrap URI - * @param options - { noValidate?: boolean } - * @returns a Result containing the WrapManifest if the request was successful - */ -getManifest(uri: TUri, options?: GetManifestOptions): Promise>; -``` - -### getFile -```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 - */ -getFile(uri: TUri, options: GetFileOptions): Promise>; -``` - -### getImplementations -```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 } - * @returns a Result containing URI array if the request was successful - */ -getImplementations(uri: TUri, options?: GetImplementationsOptions): Result; -``` - -### query -```ts -/** - * Invoke a wrapper using GraphQL query syntax - * - * @remarks - * This method behaves similar to the invoke method and allows parallel requests, - * but the syntax is more verbose. If the query is successful, data will be returned - * and the `error` value of the returned object will be undefined. If the query fails, - * the data property will be undefined and the error property will be populated. - * - * @param options - { - * // The Wrapper's URI - * uri: TUri; - * - * // The GraphQL query to parse and execute, leading to one or more Wrapper invocations. - * query: string | QueryDocument; - * - * // Variables referenced within the query string via GraphQL's '$variable' syntax. - * variables?: TVariables; - * } - * - * @returns A Promise containing an object with either the data or an error - */ -query = Record, TVariables extends Record = Record, TUri extends Uri | string = string>(options: QueryOptions): Promise>; -``` - -### invokeWrapper -```ts -/** - * Invoke a wrapper using standard syntax and 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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * 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 - */ -invokeWrapper(options: InvokerOptions & { - wrapper: Wrapper; -}): Promise>; -``` - -### invoke -```ts -/** - * Invoke a wrapper using standard syntax. - * 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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * 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 - */ -invoke(options: InvokerOptions): Promise>; -``` - -### subscribe -```ts -/** - * Invoke a wrapper at a regular frequency (within ~16ms) - * - * @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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * resolutionContext?: IUriResolutionContext; - * - * // if true, return value is a msgpack-encoded byte array - * encodeResult?: boolean; - * - * // the frequency at which to perform the invocation - * frequency?: { - * ms?: number; - * sec?: number; - * min?: number; - * hours?: number; - * } - * } - * - * @returns A Promise with a Result containing the return value or an error - */ -subscribe(options: SubscribeOptions): Subscription; -``` - -### tryResolveUri -```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 - */ -tryResolveUri(options: TryResolveUriOptions): Promise>; -``` - -### loadWrapper -```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 either a wrapper if successful - */ -loadWrapper(uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions): Promise>; -``` - -## Development - -The Polywrap JavaScript client is open-source. It lives within the [Polywrap toolchain monorepo](https://github.com/polywrap/toolchain/tree/origin/packages/js/client). Contributions from the community are welcomed! - -### Build -```bash -nvm use && yarn install && yarn build -``` - -### Test -```bash -yarn test ``` \ No newline at end of file diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index 9c8f008f36..0d06c8610a 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -6,3 +6,382 @@

The Polywrap JavaScript core client. + +## Installation + +```bash +npm install --save @polywrap/core-client-js +``` + +## Usage + +### Instantiate the client +```ts +import { PolywrapCoreClient } from "@polywrap/core-client-js"; + +const config = { ... }; +const client = new PolywrapCoreClient(config); +``` + +### Invoke a wrapper + +```ts +await client.invoke({ + uri: "ens/rinkeby/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } +}); +``` + +### Configure the core client + +```ts +const config = { + // declare interface implementations + interfaces: [ + { + interface: "wrap://ens/uri-resolver.core.polywrap.eth", + implementations: [ + "wrap://ens/ipfs-resolver.polywrap.eth", + ], + }, + ], + // set environmental variables for a wrapper + envs: [ + { + uri: "wrap://ens/ipfs.polywrap.eth", + env: { + provider: "https://ipfs.wrappers.io", + }, + }, + ], + // customize URI resolution by adding redirects and embedded wrappers/packages + resolver: + RecursiveResolver.from( + PackageToWrapperCacheResolver.from( + [ + StaticResolver.from([ + ...redirects, + ...wrappers, + ...packages, + ]), + ...this.config.resolvers, + new ExtendableUriResolver(), + ], + new WrapperCache() + ) + ), + // tracer configuration - see @polywrap/tracing-js package + tracerConfig: { ... }, +}; +``` +```ts +// create a client by modifying the default configuration bundle +const client = new PolywrapCoreClient(config); +``` + +## Reference + +### Constructor +```ts +/** + * Instantiate a PolywrapClient + * + * @param config - a core client configuration + */ +constructor(config: PolywrapCoreClientConfig); +``` + +### getConfig +```ts +/** + * Returns the configuration used to instantiate the client + * + * @returns an immutable Polywrap client config + */ +getConfig(): PolywrapCoreClientConfig; +``` + +### setTracingEnabled +```ts +/** + * Enable tracing for intricate debugging + * + * @remarks + * Tracing uses the @polywrap/tracing-js package + * + * @param tracerConfig - configure options such as the tracing level + * @returns void + */ +setTracingEnabled(tracerConfig?: Partial): void; +``` + +### getInterfaces +```ts +/** + * returns all interfaces from the configuration used to instantiate the client + * + * @returns an array of interfaces and their registered implementations + */ +getInterfaces(): readonly InterfaceImplementations[] | undefined; +``` + +### getEnvs +```ts +/** + * returns all env registrations from the configuration used to instantiate the client + * + * @returns an array of env objects containing wrapper environmental variables + */ +getEnvs(): readonly Env[] | undefined; +``` + +### getResolver +```ts +/** + * returns the URI resolver from the configuration used to instantiate the client + * + * @returns an object that implements the IUriResolver interface + */ +getResolver(): IUriResolver; +``` + +### getEnvByUri +```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 + */ +getEnvByUri(uri: TUri): Env | undefined; +``` + +### getResolver +```ts +/** + * returns the URI resolver from the configuration used to instantiate the client + * + * @returns an object that implements the IUriResolver interface + */ +getResolver(): IUriResolver; +``` + +### getManifest +```ts +/** + * returns a package's wrap manifest + * + * @param uri - a wrap URI + * @returns a Result containing the WrapManifest if the request was successful + */ +getManifest(uri: TUri): Promise>; +``` + +### getFile +```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 + */ +getFile(uri: TUri, options: GetFileOptions): Promise>; +``` + +### getImplementations +```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 } + * @returns a Result containing URI array if the request was successful + */ +getImplementations(uri: TUri, options?: GetImplementationsOptions): Promise>; +``` + +### query +```ts +/** + * Invoke a wrapper using GraphQL query syntax + * + * @remarks + * This method behaves similar to the invoke method and allows parallel requests, + * but the syntax is more verbose. If the query is successful, data will be returned + * and the `error` value of the returned object will be undefined. If the query fails, + * the data property will be undefined and the error property will be populated. + * + * @param options - { + * // The Wrapper's URI + * uri: TUri; + * + * // The GraphQL query to parse and execute, leading to one or more Wrapper invocations. + * query: string | QueryDocument; + * + * // Variables referenced within the query string via GraphQL's '$variable' syntax. + * variables?: TVariables; + * } + * + * @returns A Promise containing an object with either the data or an error + */ +query = Record, TVariables extends Record = Record, TUri extends Uri | string = string>(options: QueryOptions): Promise>; +``` + +### invokeWrapper +```ts +/** + * Invoke a wrapper using standard syntax and 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 ordering arguments. + * args?: Record | Uint8Array; + * + * // Env variables for the wrapper invocation. + * env?: Record; + * + * 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 + */ +invokeWrapper(options: InvokerOptions & { + wrapper: Wrapper; +}): Promise>; +``` + +### invoke +```ts +/** + * Invoke a wrapper using standard syntax. + * 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 ordering arguments. + * args?: Record | Uint8Array; + * + * // Env variables for the wrapper invocation. + * env?: Record; + * + * 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 + */ +invoke(options: InvokerOptions): Promise>; +``` + +### subscribe +```ts +/** + * Invoke a wrapper at a regular frequency (within ~16ms) + * + * @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 ordering arguments. + * args?: Record | Uint8Array; + * + * // Env variables for the wrapper invocation. + * env?: Record; + * + * resolutionContext?: IUriResolutionContext; + * + * // if true, return value is a msgpack-encoded byte array + * encodeResult?: boolean; + * + * // the frequency at which to perform the invocation + * frequency?: { + * ms?: number; + * sec?: number; + * min?: number; + * hours?: number; + * } + * } + * + * @returns A Promise with a Result containing the return value or an error + */ +subscribe(options: SubscribeOptions): Subscription; +``` + +### tryResolveUri +```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 + */ +tryResolveUri(options: TryResolveUriOptions): Promise>; +``` + +### loadWrapper +```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 either a wrapper if successful + */ +loadWrapper(uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions): Promise>; +``` + +### validate +```ts +/** + * Validate a wrapper, given a URI. + * Optionally, validate the full ABI and/or recursively validate imports. + * + * @param uri: the Uri to resolve + * @param options - { abi?: boolean; recursive?: boolean } + * @returns A Promise with a Result containing a boolean or Error + */ +validate(uri: TUri, options: ValidateOptions): Promise>; +``` + +## Development + +The Polywrap JavaScript client is open-source. It lives within the [Polywrap toolchain monorepo](https://github.com/polywrap/toolchain/tree/origin/packages/js/client). Contributions from the community are welcomed! + +### Build +```bash +nvm use && yarn install && yarn build +``` + +### Test +```bash +yarn test +`` \ No newline at end of file diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index b08e57d4fe..2d4c55856b 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -89,17 +89,6 @@ export class PolywrapCoreClient implements CoreClient { } } - /** - * returns all plugin registrations from the configuration used to instantiate the client - * - * @returns an array of plugin registrations - */ - /** - * returns a plugin package from the configuration used to instantiate the client - * - * @param uri - the uri used to register the plugin - * @returns a plugin package, or undefined if a plugin is not found at the given uri - */ /** * returns all interfaces from the configuration used to instantiate the client * @@ -154,7 +143,6 @@ export class PolywrapCoreClient implements CoreClient { * returns a package's wrap manifest * * @param uri - a wrap URI - * @param options - { noValidate?: boolean } * @returns a Result containing the WrapManifest if the request was successful */ @Tracer.traceMethod("PolywrapClient: getManifest") @@ -612,7 +600,7 @@ export class PolywrapCoreClient implements CoreClient { * @param uri: the Uri to resolve * @param resolutionContext? a resolution context * @param options - { noValidate?: boolean } - * @returns A Promise with a Result containing either a wrapper if successful + * @returns A Promise with a Result containing a Wrapper or Error */ @Tracer.traceMethod("PolywrapClient: loadWrapper", TracingLevel.High) public async loadWrapper( @@ -677,6 +665,14 @@ export class PolywrapCoreClient implements CoreClient { } } + /** + * Validate a wrapper, given a URI. + * Optionally, validate the full ABI and/or recursively validate imports. + * + * @param uri: the Uri to resolve + * @param options - { abi?: boolean; recursive?: boolean } + * @returns A Promise with a Result containing a boolean or Error + */ @Tracer.traceMethod("PolywrapClient: validateConfig") public async validate( uri: TUri, From 611951edda07ff509b1bd77a1a2a325d818cfca9 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Thu, 22 Dec 2022 15:01:27 +0530 Subject: [PATCH 02/25] removed "rinkeby" from client readme invocation example; moved description of polywrap client in readme to core client; replaced "queries" word with "invocations" --- packages/js/client/README.md | 6 ++---- packages/js/core-client/README.md | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 490480b018..3ba75a2666 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -5,8 +5,6 @@

-The Polywrap JavaScript client invokes functions of wrappers and plugins. It's designed to run in any environment that can execute JavaScript (think websites, node scripts, etc.). It has TypeScript support. - The Polywrap client extends the PolywrapCoreClient to provide UX features, such as an additional constructor and additional configuration options. ## Installation @@ -28,7 +26,7 @@ const client = new PolywrapClient(); ```ts await client.invoke({ - uri: "ens/rinkeby/helloworld.dev.polywrap.eth", + uri: "ens/helloworld.dev.polywrap.eth", method: "logMessage", args: { message: "Hello World!" @@ -40,7 +38,7 @@ await client.invoke({ ```ts const config = { - // redirect queries from one uri to another + // redirect invocations from one uri to another redirects: [ { from: "wrap://ens/from.eth", diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index 0d06c8610a..e6928384dc 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -5,7 +5,7 @@

-The Polywrap JavaScript core client. +The Polywrap JavaScript core client invokes functions of wrappers and plugins. It's designed to run in any environment that can execute JavaScript (think websites, node scripts, etc.). It has TypeScript support. ## Installation From 195f3b32cb19c3c99138ec13cb74a23ea88d9aad Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 18:57:20 +0530 Subject: [PATCH 03/25] removed "rinkeby" from core client readme invocation example --- packages/js/core-client/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index e6928384dc..af7be25471 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -27,7 +27,7 @@ const client = new PolywrapCoreClient(config); ```ts await client.invoke({ - uri: "ens/rinkeby/helloworld.dev.polywrap.eth", + uri: "ens/helloworld.dev.polywrap.eth", method: "logMessage", args: { message: "Hello World!" From e4c1226ccae9a75301dc06ab9bf525e4bb2ffdb1 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 20:01:57 +0530 Subject: [PATCH 04/25] added TSDoc comments to client config builder and added reference section to client config builder README.md --- packages/js/client-config-builder/README.md | 292 +++++++++++++++++- .../src/ClientConfigBuilder.ts | 6 + .../src/IClientConfigBuilder.ts | 178 +++++++++++ 3 files changed, 468 insertions(+), 8 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index 50d55ab4ee..a5a01c561a 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -42,15 +42,291 @@ const config = builder.build(); let client = new PolywrapClient(config); ``` -## Methods +## Reference -The config builder currently supports 3 methods: +### Constructor +```ts +/** + * Instantiate a ClientConfigBuilder + * + * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache + * @param resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig + */ +constructor(wrapperCache?: IWrapperCache | undefined, resolver?: IUriResolver | undefined); +``` + +### build +```ts +/** + * Build a sanitized client configuration that can be passed to the PolywrapClient constructor + * + * @returns ClientConfig that results from applying all the steps in the builder pipeline + */ +build(): ClientConfig; +``` -#### `add(config: Partial)` -Appends each property of the supplied config object to the corresponding array of the builder's config. +### buildCoreConfig +```ts +/** + * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors + * + * @returns CoreClientConfig that results from applying all the steps in the builder pipeline + */ +buildCoreConfig(): CoreClientConfig; +``` + +### add +```ts +/** + * Add a partial ClientConfig + * This is equivalent to calling each of the plural add functions: `addEnvs`, `addWrappers`, etc. + * + * @param config: a partial CliengConfig + * @returns IClientConfigBuilder (mutated self) + */ +add(config: Partial): IClientConfigBuilder; +``` -#### `addDefaults()` -Adds the `defaultClientConfig` object. +### addDefaults +```ts +/** + * Add the default configuration bundle + * + * @returns IClientConfigBuilder (mutated self) + */ +addDefaults(): IClientConfigBuilder; +``` + +### addWrapper +```ts +/** + * Add an embedded wrapper + * + * @param uriWrapper: a wrapper and its URI + * @returns IClientConfigBuilder (mutated self) + */ +addWrapper(uriWrapper: IUriWrapper): IClientConfigBuilder; +``` + +### addWrappers +```ts +/** + * Add one or more embedded wrappers. + * This is equivalent to calling addWrapper for each wrapper. + * + * @param uriWrappers: a list of wrappers and their URIs + * @returns IClientConfigBuilder (mutated self) + */ +addWrappers(uriWrappers: IUriWrapper[]): IClientConfigBuilder; +``` + +### removeWrapper +```ts +/** + * Remove an embedded wrapper + * + * @param uri: the wrapper's URI + * @returns IClientConfigBuilder (mutated self) + */ +removeWrapper(uri: Uri | string): IClientConfigBuilder; +``` + +### addPackage +```ts +/** + * Add an embedded wrap package + * + * @param uriPackage: a package and its URI + * @returns IClientConfigBuilder (mutated self) + */ +addPackage(uriPackage: IUriPackage): IClientConfigBuilder; +``` + +### addPackages +```ts +/** + * Add one or more embedded wrap packages + * This is equivalent to calling addPackage for each package + * + * @param uriPackages: a list of packages and their URIs + * @returns IClientConfigBuilder (mutated self) + */ +addPackages(uriPackages: IUriPackage[]): IClientConfigBuilder; +``` + +### removePackage +```ts +/** + * Remove an embedded wrap package + * + * @param uri: the package's URI + * @returns IClientConfigBuilder (mutated self) + */ +removePackage(uri: Uri | string): IClientConfigBuilder; +``` + +### addEnv +```ts +/** + * Add an Env. + * If an Env is already associated with the uri, it is modified. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ +addEnv(uri: Uri | string, env: Record): IClientConfigBuilder; +``` + +### addEnvs +```ts +/** + * Add one or more Envs + * This is equivalent to calling addEnv for each Env + * + * @param envs: a list of Envs + * @returns IClientConfigBuilder (mutated self) + */ +addEnvs(envs: Env[]): IClientConfigBuilder; +``` + +### removeEnv +```ts +/** + * Remove an Env + * + * @param uri: the URI associated with the Env + * @returns IClientConfigBuilder (mutated self) + */ +removeEnv(uri: Uri | string): IClientConfigBuilder; +``` + +### setEnv +```ts +/** + * Add an Env. + * If an Env is already associated with the uri, it is replaced. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ +setEnv(uri: Uri | string, env: Record): IClientConfigBuilder; +``` + +### addInterfaceImplementation +```ts +/** + * Register an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ +addInterfaceImplementation( + interfaceUri: Uri | string, + implementationUri: Uri | string +): IClientConfigBuilder; +``` + +### addInterfaceImplementations +```ts +/** + * Register one or more implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUris: a list of URIs for the implementations + * @returns IClientConfigBuilder (mutated self) + */ +addInterfaceImplementations( + interfaceUri: Uri | string, + implementationUris: Array +): IClientConfigBuilder; +``` + +### removeInterfaceImplementation +```ts +/** + * Remove an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ +removeInterfaceImplementation( + interfaceUri: Uri | string, + implementationUri: Uri | string +): IClientConfigBuilder; +``` + +### addRedirect +```ts +/** + * Add a redirect from one URI to another + * + * @param from: the URI to redirect from + * @param to: the URI to redirect to + * @returns IClientConfigBuilder (mutated self) + */ +addRedirect(from: Uri | string, to: Uri | string): IClientConfigBuilder; +``` + +### addRedirects +```ts +/** + * Add an array of URI redirects + * + * @param redirects: a list of URI redirects + * @returns IClientConfigBuilder (mutated self) + */ +addRedirects(redirects: IUriRedirect[]): IClientConfigBuilder; +``` + +### removeRedirect +```ts +/** + * Remove a URI redirect + * + * @param from: the URI that is being redirected + * @returns IClientConfigBuilder (mutated self) + */ +removeRedirect(from: Uri | string): IClientConfigBuilder; +``` + +### addResolver +```ts +/** + * Add a URI Resolver, capable of resolving a URI to a wrapper + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolver: A UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ +addResolver(resolver: UriResolverLike): IClientConfigBuilder; +``` -#### `build()` -Returns a sanitized config object from the builder's config. +### addResolvers +```ts +/** + * Add one or more URI Resolvers, capable of resolving URIs to wrappers + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolvers: A list of UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ +addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; +``` \ No newline at end of file diff --git a/packages/js/client-config-builder/src/ClientConfigBuilder.ts b/packages/js/client-config-builder/src/ClientConfigBuilder.ts index 4cc1e04edb..901338fcca 100644 --- a/packages/js/client-config-builder/src/ClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/ClientConfigBuilder.ts @@ -12,6 +12,12 @@ import { import { ExtendableUriResolver } from "@polywrap/uri-resolver-extensions-js"; export class ClientConfigBuilder extends BaseClientConfigBuilder { + /** + * Instantiate a ClientConfigBuilder + * + * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache + * @param resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig + */ constructor( private readonly wrapperCache?: IWrapperCache, private readonly resolver?: IUriResolver diff --git a/packages/js/client-config-builder/src/IClientConfigBuilder.ts b/packages/js/client-config-builder/src/IClientConfigBuilder.ts index a9da5352ba..36d1fb36cd 100644 --- a/packages/js/client-config-builder/src/IClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/IClientConfigBuilder.ts @@ -11,35 +11,213 @@ import { import { UriResolverLike } from "@polywrap/uri-resolvers-js"; export interface IClientConfigBuilder { + /** + * Build a sanitized client configuration that can be passed to the PolywrapClient constructor + * + * @returns ClientConfig that results from applying all the steps in the builder pipeline + */ build(): ClientConfig; + + /** + * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors + * + * @returns CoreClientConfig that results from applying all the steps in the builder pipeline + */ buildCoreConfig(): CoreClientConfig; + + /** + * Add a partial ClientConfig + * This is equivalent to calling each of the plural add functions: `addEnvs`, `addWrappers`, etc. + * + * @param config: a partial CliengConfig + * @returns IClientConfigBuilder (mutated self) + */ add(config: Partial): IClientConfigBuilder; + + /** + * Add the default configuration bundle + * + * @returns IClientConfigBuilder (mutated self) + */ addDefaults(): IClientConfigBuilder; + + /** + * Add an embedded wrapper + * + * @param uriWrapper: a wrapper and its URI + * @returns IClientConfigBuilder (mutated self) + */ addWrapper(uriWrapper: IUriWrapper): IClientConfigBuilder; + + /** + * Add one or more embedded wrappers. + * This is equivalent to calling addWrapper for each wrapper. + * + * @param uriWrappers: a list of wrappers and their URIs + * @returns IClientConfigBuilder (mutated self) + */ addWrappers(uriWrappers: IUriWrapper[]): IClientConfigBuilder; + + /** + * Remove an embedded wrapper + * + * @param uri: the wrapper's URI + * @returns IClientConfigBuilder (mutated self) + */ removeWrapper(uri: Uri | string): IClientConfigBuilder; + + /** + * Add an embedded wrap package + * + * @param uriPackage: a package and its URI + * @returns IClientConfigBuilder (mutated self) + */ addPackage(uriPackage: IUriPackage): IClientConfigBuilder; + + /** + * Add one or more embedded wrap packages + * This is equivalent to calling addPackage for each package + * + * @param uriPackages: a list of packages and their URIs + * @returns IClientConfigBuilder (mutated self) + */ addPackages(uriPackages: IUriPackage[]): IClientConfigBuilder; + + /** + * Remove an embedded wrap package + * + * @param uri: the package's URI + * @returns IClientConfigBuilder (mutated self) + */ removePackage(uri: Uri | string): IClientConfigBuilder; + + /** + * Add an Env. + * If an Env is already associated with the uri, it is modified. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ addEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + + /** + * Add one or more Envs + * This is equivalent to calling addEnv for each Env + * + * @param envs: a list of Envs + * @returns IClientConfigBuilder (mutated self) + */ addEnvs(envs: Env[]): IClientConfigBuilder; + + /** + * Remove an Env + * + * @param uri: the URI associated with the Env + * @returns IClientConfigBuilder (mutated self) + */ removeEnv(uri: Uri | string): IClientConfigBuilder; + + /** + * Add an Env. + * If an Env is already associated with the uri, it is replaced. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ setEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + + /** + * Register an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ addInterfaceImplementation( interfaceUri: Uri | string, implementationUri: Uri | string ): IClientConfigBuilder; + + /** + * Register one or more implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUris: a list of URIs for the implementations + * @returns IClientConfigBuilder (mutated self) + */ addInterfaceImplementations( interfaceUri: Uri | string, implementationUris: Array ): IClientConfigBuilder; + + /** + * Remove an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ removeInterfaceImplementation( interfaceUri: Uri | string, implementationUri: Uri | string ): IClientConfigBuilder; + + /** + * Add a redirect from one URI to another + * + * @param from: the URI to redirect from + * @param to: the URI to redirect to + * @returns IClientConfigBuilder (mutated self) + */ addRedirect(from: Uri | string, to: Uri | string): IClientConfigBuilder; + + /** + * Add an array of URI redirects + * + * @param redirects: a list of URI redirects + * @returns IClientConfigBuilder (mutated self) + */ addRedirects(redirects: IUriRedirect[]): IClientConfigBuilder; + + /** + * Remove a URI redirect + * + * @param from: the URI that is being redirected + * @returns IClientConfigBuilder (mutated self) + */ removeRedirect(from: Uri | string): IClientConfigBuilder; + + /** + * Add a URI Resolver, capable of resolving a URI to a wrapper + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolver: A UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ addResolver(resolver: UriResolverLike): IClientConfigBuilder; + + /** + * Add one or more URI Resolvers, capable of resolving URIs to wrappers + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolvers: A list of UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; } From 3eec7e9eabc2f4298b9f54e0bd9364135f67f21d Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 21:00:45 +0530 Subject: [PATCH 05/25] added client configs to client, core client, and config builder readmes --- packages/js/client-config-builder/README.md | 34 +++++++++++++++++- .../client-config-builder/src/ClientConfig.ts | 19 ++++++++++ packages/js/client/README.md | 35 ++++++++++++++++++- .../js/client/src/PolywrapClientConfig.ts | 23 ++++++++++++ packages/js/core-client/README.md | 31 +++++++++++++++- .../js/core-client/src/PolywrapCoreClient.ts | 6 ++-- .../src/PolywrapCoreClientConfig.ts | 19 ++++++++++ 7 files changed, 161 insertions(+), 6 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index a5a01c561a..a842d74972 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -42,7 +42,39 @@ const config = builder.build(); let client = new PolywrapClient(config); ``` -## Reference +## Types + +```ts +/** + * Client configuration that can be passed to the PolywrapClient + * + * @remarks + * The PolywrapClient converts the ClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property redirects - redirect invocations from one uri to another + * @property wrappers - add embedded wrappers + * @property packages - add and configure embedded packages + * @property resolvers - customize URI resolution + */ +export interface ClientConfig { + readonly envs: Env[]; + readonly interfaces: InterfaceImplementations[]; + readonly redirects: IUriRedirect[]; + readonly wrappers: IUriWrapper[]; + readonly packages: IUriPackage[]; + readonly resolvers: UriResolverLike[]; +} +``` + +## ClientConfigBuilder ### Constructor ```ts diff --git a/packages/js/client-config-builder/src/ClientConfig.ts b/packages/js/client-config-builder/src/ClientConfig.ts index bb6593efd5..b9de0cd01b 100644 --- a/packages/js/client-config-builder/src/ClientConfig.ts +++ b/packages/js/client-config-builder/src/ClientConfig.ts @@ -8,6 +8,25 @@ import { } from "@polywrap/core-js"; import { UriResolverLike } from "@polywrap/uri-resolvers-js"; +/** + * Client configuration that can be passed to the PolywrapClient + * + * @remarks + * The PolywrapClient converts the ClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property redirects - redirect invocations from one uri to another + * @property wrappers - add embedded wrappers + * @property packages - add and configure embedded packages + * @property resolvers - customize URI resolution + */ export interface ClientConfig { readonly envs: Env[]; readonly interfaces: InterfaceImplementations[]; diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 3ba75a2666..5e62a86c5e 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -104,7 +104,40 @@ const client = new PolywrapClient(config); const altClient = new PolywrapClient(config, { noDefaults: true }); ``` -## Reference +## Types + +```ts +/** + * Client configuration that can be passed to the PolywrapClient. + * Extends ClientConfig from @polywrap/client-config-builder-js. + * + * @remarks + * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property redirects - redirect invocations from one uri to another + * @property wrappers - add embedded wrappers + * @property packages - add and configure embedded packages + * @property resolvers - customize URI resolution + * + * @property wrapperCache? - a wrapper cache to be used in place of the default wrapper cache + * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging + */ +export interface PolywrapClientConfig + extends ClientConfig { + readonly wrapperCache?: IWrapperCache; + readonly tracerConfig?: Readonly>; +} +``` + +## PolywrapClient ### Constructor ```ts diff --git a/packages/js/client/src/PolywrapClientConfig.ts b/packages/js/client/src/PolywrapClientConfig.ts index d20f424276..e5985d2c25 100644 --- a/packages/js/client/src/PolywrapClientConfig.ts +++ b/packages/js/client/src/PolywrapClientConfig.ts @@ -3,6 +3,29 @@ import { IWrapperCache } from "@polywrap/uri-resolvers-js"; import { TracerConfig } from "@polywrap/tracing-js"; import { ClientConfig } from "@polywrap/client-config-builder-js"; +/** + * Client configuration that can be passed to the PolywrapClient. + * Extends ClientConfig from @polywrap/client-config-builder-js. + * + * @remarks + * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property redirects - redirect invocations from one uri to another + * @property wrappers - add embedded wrappers + * @property packages - add and configure embedded packages + * @property resolvers - customize URI resolution + * + * @property wrapperCache? - a wrapper cache to be used in place of the default wrapper cache + * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging + */ export interface PolywrapClientConfig extends ClientConfig { readonly wrapperCache?: IWrapperCache; diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index af7be25471..f4fac7a928 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -82,7 +82,36 @@ const config = { const client = new PolywrapCoreClient(config); ``` -## Reference +## Types + +```ts +/** + * Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors. + * Extends CoreClientConfig from @polywrap/core-js. + * + * @remarks + * The PolywrapClient and PolywrapCoreClient convert the PolywrapCoreClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property resolver - configure URI resolution for redirects, packages, and wrappers + * + * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging + */ +export interface PolywrapCoreClientConfig< + TUri extends Uri | string = Uri | string +> extends CoreClientConfig { + readonly tracerConfig?: Readonly>; +} +``` + +## PolywrapCoreClient ### Constructor ```ts diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index fd9eaa740f..43b9959996 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -380,8 +380,8 @@ export class PolywrapCoreClient implements CoreClient { * 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 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 */ @@ -452,7 +452,7 @@ export class PolywrapCoreClient implements CoreClient { * Validate a wrapper, given a URI. * Optionally, validate the full ABI and/or recursively validate imports. * - * @param uri: the Uri to resolve + * @param uri - the Uri to resolve * @param options - { abi?: boolean; recursive?: boolean } * @returns A Promise with a Result containing a boolean or Error */ diff --git a/packages/js/core-client/src/PolywrapCoreClientConfig.ts b/packages/js/core-client/src/PolywrapCoreClientConfig.ts index aa5baf913c..5567cfa390 100644 --- a/packages/js/core-client/src/PolywrapCoreClientConfig.ts +++ b/packages/js/core-client/src/PolywrapCoreClientConfig.ts @@ -1,6 +1,25 @@ import { CoreClientConfig, Uri } from "@polywrap/core-js"; import { TracerConfig } from "@polywrap/tracing-js"; +/** + * Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors. + * Extends CoreClientConfig from @polywrap/core-js. + * + * @remarks + * The PolywrapClient and PolywrapCoreClient convert the PolywrapCoreClientConfig to a CoreClientConfig. + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @property envs - set environmental variables for a wrapper + * @property interfaces - register interface implementations + * @property resolver - configure URI resolution for redirects, packages, and wrappers + * + * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging + */ export interface PolywrapCoreClientConfig< TUri extends Uri | string = Uri | string > extends CoreClientConfig { From 4a8122166838738675f74391e61e2cb27f72c876 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 21:11:36 +0530 Subject: [PATCH 06/25] adjusted client config comments to more closely match formatting used elsewhere for interface types --- packages/js/client-config-builder/README.md | 33 +++++++++++-------- .../client-config-builder/src/ClientConfig.ts | 33 +++++++++++-------- packages/js/client/README.md | 21 +++--------- .../js/client/src/PolywrapClientConfig.ts | 21 +++--------- packages/js/core-client/README.md | 15 ++------- .../src/PolywrapCoreClientConfig.ts | 15 ++------- packages/js/core/src/types/CoreClient.ts | 6 ++++ 7 files changed, 58 insertions(+), 86 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index a842d74972..65863c42cb 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -50,26 +50,33 @@ let client = new PolywrapClient(config); * * @remarks * The PolywrapClient converts the ClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property redirects - redirect invocations from one uri to another - * @property wrappers - add embedded wrappers - * @property packages - add and configure embedded packages - * @property resolvers - customize URI resolution */ export interface ClientConfig { + /** set environmental variables for a wrapper */ readonly envs: Env[]; + + /** redirect invocations from one uri to another */ readonly interfaces: InterfaceImplementations[]; + + /** register interface implementations */ readonly redirects: IUriRedirect[]; + + /** add embedded wrappers */ readonly wrappers: IUriWrapper[]; + + /** add and configure embedded packages */ readonly packages: IUriPackage[]; + + /** customize URI resolution + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[] + * */ readonly resolvers: UriResolverLike[]; } ``` diff --git a/packages/js/client-config-builder/src/ClientConfig.ts b/packages/js/client-config-builder/src/ClientConfig.ts index b9de0cd01b..5bad83f779 100644 --- a/packages/js/client-config-builder/src/ClientConfig.ts +++ b/packages/js/client-config-builder/src/ClientConfig.ts @@ -13,25 +13,32 @@ import { UriResolverLike } from "@polywrap/uri-resolvers-js"; * * @remarks * The PolywrapClient converts the ClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property redirects - redirect invocations from one uri to another - * @property wrappers - add embedded wrappers - * @property packages - add and configure embedded packages - * @property resolvers - customize URI resolution */ export interface ClientConfig { + /** set environmental variables for a wrapper */ readonly envs: Env[]; + + /** redirect invocations from one uri to another */ readonly interfaces: InterfaceImplementations[]; + + /** register interface implementations */ readonly redirects: IUriRedirect[]; + + /** add embedded wrappers */ readonly wrappers: IUriWrapper[]; + + /** add and configure embedded packages */ readonly packages: IUriPackage[]; + + /** customize URI resolution + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[] + * */ readonly resolvers: UriResolverLike[]; } diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 5e62a86c5e..57a930f388 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -109,30 +109,17 @@ const altClient = new PolywrapClient(config, { noDefaults: true }); ```ts /** * Client configuration that can be passed to the PolywrapClient. - * Extends ClientConfig from @polywrap/client-config-builder-js. * * @remarks + * Extends ClientConfig from @polywrap/client-config-builder-js. * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property redirects - redirect invocations from one uri to another - * @property wrappers - add embedded wrappers - * @property packages - add and configure embedded packages - * @property resolvers - customize URI resolution - * - * @property wrapperCache? - a wrapper cache to be used in place of the default wrapper cache - * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging */ export interface PolywrapClientConfig extends ClientConfig { + /** a wrapper cache to be used in place of the default wrapper cache */ readonly wrapperCache?: IWrapperCache; + + /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } ``` diff --git a/packages/js/client/src/PolywrapClientConfig.ts b/packages/js/client/src/PolywrapClientConfig.ts index e5985d2c25..812f6f68ea 100644 --- a/packages/js/client/src/PolywrapClientConfig.ts +++ b/packages/js/client/src/PolywrapClientConfig.ts @@ -5,29 +5,16 @@ import { ClientConfig } from "@polywrap/client-config-builder-js"; /** * Client configuration that can be passed to the PolywrapClient. - * Extends ClientConfig from @polywrap/client-config-builder-js. * * @remarks + * Extends ClientConfig from @polywrap/client-config-builder-js. * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property redirects - redirect invocations from one uri to another - * @property wrappers - add embedded wrappers - * @property packages - add and configure embedded packages - * @property resolvers - customize URI resolution - * - * @property wrapperCache? - a wrapper cache to be used in place of the default wrapper cache - * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging */ export interface PolywrapClientConfig extends ClientConfig { + /** a wrapper cache to be used in place of the default wrapper cache */ readonly wrapperCache?: IWrapperCache; + + /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index f4fac7a928..e600b9e881 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -87,26 +87,15 @@ const client = new PolywrapCoreClient(config); ```ts /** * Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors. - * Extends CoreClientConfig from @polywrap/core-js. * * @remarks + * Extends CoreClientConfig from @polywrap/core-js. * The PolywrapClient and PolywrapCoreClient convert the PolywrapCoreClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property resolver - configure URI resolution for redirects, packages, and wrappers - * - * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging */ export interface PolywrapCoreClientConfig< TUri extends Uri | string = Uri | string > extends CoreClientConfig { + /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } ``` diff --git a/packages/js/core-client/src/PolywrapCoreClientConfig.ts b/packages/js/core-client/src/PolywrapCoreClientConfig.ts index 5567cfa390..b0fa62f4e6 100644 --- a/packages/js/core-client/src/PolywrapCoreClientConfig.ts +++ b/packages/js/core-client/src/PolywrapCoreClientConfig.ts @@ -3,25 +3,14 @@ import { TracerConfig } from "@polywrap/tracing-js"; /** * Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors. - * Extends CoreClientConfig from @polywrap/core-js. * * @remarks + * Extends CoreClientConfig from @polywrap/core-js. * The PolywrapClient and PolywrapCoreClient convert the PolywrapCoreClientConfig to a CoreClientConfig. - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @property envs - set environmental variables for a wrapper - * @property interfaces - register interface implementations - * @property resolver - configure URI resolution for redirects, packages, and wrappers - * - * @property tracerConfig? - configuration for opentelemetry tracing to aid in debugging */ export interface PolywrapCoreClientConfig< TUri extends Uri | string = Uri | string > extends CoreClientConfig { + /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } diff --git a/packages/js/core/src/types/CoreClient.ts b/packages/js/core/src/types/CoreClient.ts index a81768fdc3..3435d3f983 100644 --- a/packages/js/core/src/types/CoreClient.ts +++ b/packages/js/core/src/types/CoreClient.ts @@ -5,9 +5,15 @@ import { UriResolverHandler } from "./UriResolver"; import { WrapManifest } from "@polywrap/wrap-manifest-types-js"; import { Result } from "@polywrap/result"; +/** Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors */ export interface CoreClientConfig { + /** set environmental variables for a wrapper */ readonly interfaces?: Readonly[]>; + + /** register interface implementations */ readonly envs?: Readonly[]>; + + /** configure URI resolution for redirects, packages, and wrappers */ readonly resolver: Readonly>; } From 18f98be61f1648a03da739062b86965d8bbb5229 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 21:47:57 +0530 Subject: [PATCH 07/25] added TSDoc comments for CoreClient.ts --- packages/js/core-client/README.md | 70 +----------------- .../js/core-client/src/PolywrapCoreClient.ts | 2 +- packages/js/core/src/types/CoreClient.ts | 72 +++++++++++++++++-- packages/js/core/src/types/IWrapPackage.ts | 7 +- 4 files changed, 78 insertions(+), 73 deletions(-) diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index e600b9e881..b03bcec45a 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -5,7 +5,7 @@

-The Polywrap JavaScript core client invokes functions of wrappers and plugins. It's designed to run in any environment that can execute JavaScript (think websites, node scripts, etc.). It has TypeScript support. +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 @@ -117,7 +117,7 @@ constructor(config: PolywrapCoreClientConfig); /** * Returns the configuration used to instantiate the client * - * @returns an immutable Polywrap client config + * @returns an immutable Polywrap core client config */ getConfig(): PolywrapCoreClientConfig; ``` @@ -217,39 +217,12 @@ getFile(uri: TUri, options: GetFileOptions): Promise< * from the configuration used to instantiate the client * * @param uri - a wrap URI - * @param options - { applyResolution?: boolean } + * @param options - { applyResolution?: boolean; resolutionContext?: IUriResolutionContext } * @returns a Result containing URI array if the request was successful */ getImplementations(uri: TUri, options?: GetImplementationsOptions): Promise>; ``` -### query -```ts -/** - * Invoke a wrapper using GraphQL query syntax - * - * @remarks - * This method behaves similar to the invoke method and allows parallel requests, - * but the syntax is more verbose. If the query is successful, data will be returned - * and the `error` value of the returned object will be undefined. If the query fails, - * the data property will be undefined and the error property will be populated. - * - * @param options - { - * // The Wrapper's URI - * uri: TUri; - * - * // The GraphQL query to parse and execute, leading to one or more Wrapper invocations. - * query: string | QueryDocument; - * - * // Variables referenced within the query string via GraphQL's '$variable' syntax. - * variables?: TVariables; - * } - * - * @returns A Promise containing an object with either the data or an error - */ -query = Record, TVariables extends Record = Record, TUri extends Uri | string = string>(options: QueryOptions): Promise>; -``` - ### invokeWrapper ```ts /** @@ -311,43 +284,6 @@ invokeWrapper(options: Invo invoke(options: InvokerOptions): Promise>; ``` -### subscribe -```ts -/** - * Invoke a wrapper at a regular frequency (within ~16ms) - * - * @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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * resolutionContext?: IUriResolutionContext; - * - * // if true, return value is a msgpack-encoded byte array - * encodeResult?: boolean; - * - * // the frequency at which to perform the invocation - * frequency?: { - * ms?: number; - * sec?: number; - * min?: number; - * hours?: number; - * } - * } - * - * @returns A Promise with a Result containing the return value or an error - */ -subscribe(options: SubscribeOptions): Subscription; -``` - ### tryResolveUri ```ts /** diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index 43b9959996..2e4ce5150f 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -179,7 +179,7 @@ export class PolywrapCoreClient implements CoreClient { * from the configuration used to instantiate the client * * @param uri - a wrap URI - * @param options - { applyResolution?: boolean } + * @param options - { applyResolution?: boolean; resolutionContext?: IUriResolutionContext } * @returns a Result containing URI array if the request was successful */ @Tracer.traceMethod("PolywrapClient: getImplementations") diff --git a/packages/js/core/src/types/CoreClient.ts b/packages/js/core/src/types/CoreClient.ts index 3435d3f983..5ce606995e 100644 --- a/packages/js/core/src/types/CoreClient.ts +++ b/packages/js/core/src/types/CoreClient.ts @@ -17,50 +17,114 @@ export interface CoreClientConfig { readonly resolver: Readonly>; } -export interface GetManifestOptions { - noValidate?: boolean; -} - +/** Options for CoreClient's getFile method */ export interface GetFileOptions { + /** file path from wrapper root */ path: string; + + /** file encoding */ encoding?: "utf-8" | string; } +/** Options for CoreClient's getImplementations method */ export interface GetImplementationsOptions { + /** If true, follow redirects to resolve URIs */ applyResolution?: boolean; + + /** Use and update an existing resolution context */ resolutionContext?: IUriResolutionContext; } +/** Options for CoreClient's validate method */ export interface ValidateOptions { + /** Validate full ABI */ abi?: boolean; + + /** Recursively validate import URIs */ recursive?: boolean; } +/** CoreClient invokes wrapper functions, and interacts with wrap packages. */ export interface CoreClient extends Invoker, UriResolverHandler { + /** + * Returns the configuration used to instantiate the client + * + * @returns an immutable core client config + */ getConfig(): CoreClientConfig; + /** + * returns all interfaces from the configuration used to instantiate the client + * + * @returns an array of interfaces and their registered implementations + */ getInterfaces(): readonly InterfaceImplementations[] | undefined; + /** + * returns all env registrations from the configuration used to instantiate the client + * + * @returns an array of env objects containing wrapper environmental variables + */ getEnvs(): readonly Env[] | undefined; + /** + * 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 + */ getEnvByUri(uri: TUri): Env | undefined; + /** + * returns the URI resolver from the configuration used to instantiate the client + * + * @returns an object that implements the IUriResolver interface + */ getResolver(): IUriResolver; + /** + * returns a package's wrap manifest + * + * @param uri - a wrap URI + * @returns a Result containing the WrapManifest if the request was successful + */ getManifest( uri: TUri ): Promise>; + /** + * 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 + */ getFile( uri: TUri, options: GetFileOptions ): Promise>; + /** + * 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 + */ getImplementations( uri: TUri, options: GetImplementationsOptions ): Promise>; + /** + * Validate a wrapper, given a URI. + * Optionally, validate the full ABI and/or recursively validate imports. + * + * @param uri: the Uri to resolve + * @param options - { abi?: boolean; recursive?: boolean } + * @returns A Promise with a Result containing a boolean or Error + */ validate( uri: TUri, options?: ValidateOptions diff --git a/packages/js/core/src/types/IWrapPackage.ts b/packages/js/core/src/types/IWrapPackage.ts index 9afe7fc5aa..a5c5db9979 100644 --- a/packages/js/core/src/types/IWrapPackage.ts +++ b/packages/js/core/src/types/IWrapPackage.ts @@ -1,4 +1,4 @@ -import { Wrapper, GetManifestOptions } from "."; +import { Wrapper } from "."; import { DeserializeManifestOptions, @@ -6,6 +6,11 @@ import { } from "@polywrap/wrap-manifest-types-js"; import { Result } from "@polywrap/result"; +/** Options for IWrapPackage's getManifest method */ +export interface GetManifestOptions { + noValidate?: boolean; +} + export interface IWrapPackage { getManifest( options?: GetManifestOptions From 618afcd97b22785db91b9526d1122ea87f9b6b47 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 22:14:24 +0530 Subject: [PATCH 08/25] replaced @polywrap/client-js readme reference content with doc snippet markers --- packages/js/client/README.md | 30 ++----------------- packages/js/client/src/PolywrapClient.ts | 2 ++ .../js/client/src/PolywrapClientConfig.ts | 2 ++ 3 files changed, 7 insertions(+), 27 deletions(-) diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 57a930f388..6f544c11fa 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -107,37 +107,13 @@ const altClient = new PolywrapClient(config, { noDefaults: true }); ## Types ```ts -/** - * Client configuration that can be passed to the PolywrapClient. - * - * @remarks - * Extends ClientConfig from @polywrap/client-config-builder-js. - * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. - */ -export interface PolywrapClientConfig - extends ClientConfig { - /** a wrapper cache to be used in place of the default wrapper cache */ - readonly wrapperCache?: IWrapperCache; - - /** configuration for opentelemetry tracing to aid in debugging */ - readonly tracerConfig?: Readonly>; -} +// $snippet: PolywrapClientConfig ``` ## PolywrapClient ### Constructor ```ts -/** - * Instantiate a PolywrapClient - * - * @param config - a whole or partial client configuration - * @param options - { noDefaults?: boolean } - */ -constructor(config?: Partial, options?: { - noDefaults?: false; -}); -constructor(config: PolywrapCoreClientConfig, options: { - noDefaults: true; -}); +// $snippet: PolywrapClient-constructor + ) ``` \ No newline at end of file diff --git a/packages/js/client/src/PolywrapClient.ts b/packages/js/client/src/PolywrapClient.ts index 53357ac841..3079c83fa4 100644 --- a/packages/js/client/src/PolywrapClient.ts +++ b/packages/js/client/src/PolywrapClient.ts @@ -7,6 +7,7 @@ import { } from "@polywrap/core-client-js"; export class PolywrapClient extends PolywrapCoreClient { + // $start: PolywrapClient-constructor /** * Instantiate a PolywrapClient * @@ -24,6 +25,7 @@ export class PolywrapClient extends PolywrapCoreClient { | undefined | PolywrapCoreClientConfig, options?: { noDefaults?: boolean } + // $end ) { super( !options?.noDefaults diff --git a/packages/js/client/src/PolywrapClientConfig.ts b/packages/js/client/src/PolywrapClientConfig.ts index 812f6f68ea..ee72627faa 100644 --- a/packages/js/client/src/PolywrapClientConfig.ts +++ b/packages/js/client/src/PolywrapClientConfig.ts @@ -3,6 +3,7 @@ import { IWrapperCache } from "@polywrap/uri-resolvers-js"; import { TracerConfig } from "@polywrap/tracing-js"; import { ClientConfig } from "@polywrap/client-config-builder-js"; +// $start: PolywrapClientConfig /** * Client configuration that can be passed to the PolywrapClient. * @@ -18,3 +19,4 @@ export interface PolywrapClientConfig /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } +// $end From 8e4ad88f651c8bae7afb2c30644d91bc4849f4b2 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 22:40:18 +0530 Subject: [PATCH 09/25] using doc-snippets package to build readme in @polywrap/client-js --- packages/js/client/README.md | 34 +++++++- packages/js/client/package.json | 20 ++++- packages/js/client/readme/README.md | 119 ++++++++++++++++++++++++++++ yarn.lock | 26 +++++- 4 files changed, 195 insertions(+), 4 deletions(-) create mode 100644 packages/js/client/readme/README.md diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 6f544c11fa..126aceba42 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -107,13 +107,43 @@ const altClient = new PolywrapClient(config, { noDefaults: true }); ## Types ```ts -// $snippet: PolywrapClientConfig +/** + * Client configuration that can be passed to the PolywrapClient. + * + * @remarks + * Extends ClientConfig from @polywrap/client-config-builder-js. + * The PolywrapClient converts the PolywrapClientConfig to a CoreClientConfig. + */ +export interface PolywrapClientConfig + extends ClientConfig { + /** a wrapper cache to be used in place of the default wrapper cache */ + readonly wrapperCache?: IWrapperCache; + + /** configuration for opentelemetry tracing to aid in debugging */ + readonly tracerConfig?: Readonly>; +} ``` ## PolywrapClient ### Constructor ```ts -// $snippet: PolywrapClient-constructor + /** + * Instantiate a PolywrapClient + * + * @param config - a whole or partial client configuration + * @param options - { noDefaults?: boolean } + */ + constructor( + config?: Partial, + options?: { noDefaults?: false } + ); + constructor(config: PolywrapCoreClientConfig, options: { noDefaults: true }); + constructor( + config: + | Partial + | undefined + | PolywrapCoreClientConfig, + options?: { noDefaults?: boolean } ) ``` \ No newline at end of file diff --git a/packages/js/client/package.json b/packages/js/client/package.json index 5bf108bd18..d3e553b1fb 100644 --- a/packages/js/client/package.json +++ b/packages/js/client/package.json @@ -17,7 +17,8 @@ "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", "test:ci": "jest --passWithNoTests --runInBand --verbose --detectOpenHandles --forceExit", "test:rust": "jest --passWithNoTests --runInBand --verbose --detectOpenHandles --forceExit --config ./jest.rs.config.js", - "test:watch": "jest --watch --passWithNoTests --verbose --detectOpenHandles" + "test:watch": "jest --watch --passWithNoTests --verbose --detectOpenHandles", + "build:readme": "yarn doc-snippets combine" }, "dependencies": { "@polywrap/client-config-builder-js": "0.10.0-pre.6", @@ -32,6 +33,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { + "doc-snippets": "^0.4.0-pre.1", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", "@polywrap/fs-plugin-js": "0.10.0-pre.6", @@ -59,5 +61,21 @@ "gitHead": "7346adaf5adb7e6bbb70d9247583e995650d390a", "publishConfig": { "access": "public" + }, + "doc-snippets": { + "extract": { + "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./src" + }, + "inject": { + "dir": "./readme", + "include": "./README.md" + }, + "outputDir": "./" } } diff --git a/packages/js/client/readme/README.md b/packages/js/client/readme/README.md new file mode 100644 index 0000000000..e47938f66e --- /dev/null +++ b/packages/js/client/readme/README.md @@ -0,0 +1,119 @@ +# @polywrap/client-js + +npm + + +
+
+The Polywrap client extends the PolywrapCoreClient to provide UX features, such as an additional constructor and additional configuration options. + +## Installation + +```bash +npm install --save @polywrap/client-js +``` + +## Usage + +### Instantiate the client +```ts +import { PolywrapClient } from "@polywrap/client-js"; + +const client = new PolywrapClient(); +``` + +### Invoke a wrapper + +```ts +await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } +}); +``` + +### Configure the client + +```ts +const config = { + // redirect invocations from one uri to another + redirects: [ + { + from: "wrap://ens/from.eth", + to: "wrap://ens/to.eth", + } + ], + // add embedded Wasm wrappers + wrappers: [ + { + uri: "wrap://fs/simple/wrapper/uri/build", + wrapper: WasmWrapper.from( + fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.info")), + fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.wasm")) + ) + } + ], + // add and configure embedded plugin wrappers + packages: [ + { + uri: "wrap://ens/ipfs.polywrap.eth", + package: ipfsPlugin({}), + }, + ], + // declare interface implementations + interfaces: [ + { + interface: "wrap://ens/uri-resolver.core.polywrap.eth", + implementations: [ + "wrap://ens/ipfs-resolver.polywrap.eth", + ], + }, + ], + // set environmental variables for a wrapper + envs: [ + { + uri: "wrap://ens/ipfs.polywrap.eth", + env: { + provider: "https://ipfs.wrappers.io", + }, + }, + ], + // customize URI resolution + resolvers: [ + new RecursiveResolver( + new PackageToWrapperCacheResolver(wrapperCache, [ + new ExtendableUriResolver(), + ]) + ) + ], + + // custom wrapper cache + wrapperCache: new WrapperCache(), + + // tracer configuration - see @polywrap/tracing-js package + tracerConfig: { ... }, +}; +``` +```ts +// create a client by modifying the default configuration bundle +const client = new PolywrapClient(config); + +// or remove and replace the default configuration +const altClient = new PolywrapClient(config, { noDefaults: true }); +``` + +## Types + +```ts +$snippet: PolywrapClientConfig +``` + +## PolywrapClient + +### Constructor +```ts +$snippet: PolywrapClient-constructor + ) +``` \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index f0b7604aae..3a26f49c5d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5948,6 +5948,11 @@ commander@^4.1.1: resolved "https://registry.yarnpkg.com/commander/-/commander-4.1.1.tgz#9fd602bd936294e9e9ef46a3f4d6964044b18068" integrity sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA== +commander@^9.4.1: + version "9.4.1" + resolved "https://registry.yarnpkg.com/commander/-/commander-9.4.1.tgz#d1dd8f2ce6faf93147295c0df13c7c21141cfbdd" + integrity sha512-5EEkTNyHNGFPD2H+c/dXXfQZYa/scCKasxWcXJaWnNJ99pnQN9Vnmqow+p+PlFPE63Q6mThaZws1T+HxfpgtPw== + common-tags@^1.8.0: version "1.8.2" resolved "https://registry.yarnpkg.com/common-tags/-/common-tags-1.8.2.tgz#94ebb3c076d26032745fd54face7f688ef5ac9c6" @@ -6983,6 +6988,14 @@ dns-txt@^2.0.2: dependencies: buffer-indexof "^1.0.0" +doc-snippets@^0.4.0-pre.1: + version "0.4.0-pre.1" + resolved "https://registry.yarnpkg.com/doc-snippets/-/doc-snippets-0.4.0-pre.1.tgz#50d41ad18d0a5a10bc49eade4073dd94dc32eb21" + integrity sha512-hKIkvzgd64Q6zEFNO+PEbsiLIQWvwMrmWnMhR22s0EsL4534H177K/ycyMZ90xnvLiFvckTHUUYXWAWN1ZEkRA== + dependencies: + commander "^9.4.1" + glob "^8.0.3" + docker-compose@0.23.17: version "0.23.17" resolved "https://registry.yarnpkg.com/docker-compose/-/docker-compose-0.23.17.tgz#8816bef82562d9417dc8c790aa4871350f93a2ba" @@ -8715,6 +8728,17 @@ glob@^7.0.3, glob@^7.0.5, glob@^7.1.1, glob@^7.1.2, glob@^7.1.3, glob@^7.1.4, gl once "^1.3.0" path-is-absolute "^1.0.0" +glob@^8.0.3: + version "8.0.3" + resolved "https://registry.yarnpkg.com/glob/-/glob-8.0.3.tgz#415c6eb2deed9e502c68fa44a272e6da6eeca42e" + integrity sha512-ull455NHSHI/Y1FqGaaYFaLGkNMMJbavMrEGFXG/PGrg6y7sutWHUHrz6gy6WEBH6akM1M414dWKCNs+IhKdiQ== + dependencies: + fs.realpath "^1.0.0" + inflight "^1.0.4" + inherits "2" + minimatch "^5.0.1" + once "^1.3.0" + global-modules@2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/global-modules/-/global-modules-2.0.0.tgz#997605ad2345f27f51539bea26574421215c7780" @@ -12085,7 +12109,7 @@ minimalistic-crypto-utils@^1.0.1: resolved "https://registry.yarnpkg.com/minimalistic-crypto-utils/-/minimalistic-crypto-utils-1.0.1.tgz#f6c00c1c0b082246e5c4d99dfb8c7c083b2b582a" integrity sha512-JIYlbt6g8i5jKfJ3xz7rF0LXmv2TkDxBLUkiBeZ7bAx4GnnNMr8xFpGnOxn6GhTEHx3SjRrZEoU+j04prX1ktg== -minimatch@*: +minimatch@*, minimatch@^5.0.1: version "5.1.2" resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-5.1.2.tgz#0939d7d6f0898acbd1508abe534d1929368a8fff" integrity sha512-bNH9mmM9qsJ2X4r2Nat1B//1dJVcn3+iBLa3IgqJ7EbGaDNepL9QSHOxN4ng33s52VMMhhIfgCYDk3C4ZmlDAg== From 7217c664426ce2bccdd0f4d5a9c35d349bc5cd20 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 23:21:40 +0530 Subject: [PATCH 10/25] using doc-snippets package to build readme in @polywrap/core-client-js --- packages/js/client/README.md | 2 +- packages/js/client/readme/README.md | 1 - packages/js/client/src/PolywrapClient.ts | 2 +- packages/js/core-client/README.md | 354 ++++++++++-------- packages/js/core-client/package.json | 20 +- packages/js/core-client/readme/README.md | 180 +++++++++ .../js/core-client/src/PolywrapCoreClient.ts | 30 ++ .../src/PolywrapCoreClientConfig.ts | 2 + 8 files changed, 423 insertions(+), 168 deletions(-) create mode 100644 packages/js/core-client/readme/README.md diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 126aceba42..dd9ffb48cd 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -145,5 +145,5 @@ export interface PolywrapClientConfig | undefined | PolywrapCoreClientConfig, options?: { noDefaults?: boolean } - ) + ) { ``` \ No newline at end of file diff --git a/packages/js/client/readme/README.md b/packages/js/client/readme/README.md index e47938f66e..e90e185184 100644 --- a/packages/js/client/readme/README.md +++ b/packages/js/client/readme/README.md @@ -115,5 +115,4 @@ $snippet: PolywrapClientConfig ### Constructor ```ts $snippet: PolywrapClient-constructor - ) ``` \ No newline at end of file diff --git a/packages/js/client/src/PolywrapClient.ts b/packages/js/client/src/PolywrapClient.ts index 3079c83fa4..7734316c4c 100644 --- a/packages/js/client/src/PolywrapClient.ts +++ b/packages/js/client/src/PolywrapClient.ts @@ -25,8 +25,8 @@ export class PolywrapClient extends PolywrapCoreClient { | undefined | PolywrapCoreClientConfig, options?: { noDefaults?: boolean } - // $end ) { + // $end super( !options?.noDefaults ? buildPolywrapCoreClientConfig( diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index b03bcec45a..a4a5ae1fa9 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -104,226 +104,252 @@ export interface PolywrapCoreClientConfig< ### Constructor ```ts -/** - * Instantiate a PolywrapClient - * - * @param config - a core client configuration - */ -constructor(config: PolywrapCoreClientConfig); + /** + * Instantiate a PolywrapClient + * + * @param config - a core client configuration + */ + constructor(config: PolywrapCoreClientConfig) { ``` ### getConfig ```ts -/** - * Returns the configuration used to instantiate the client - * - * @returns an immutable Polywrap core client config - */ -getConfig(): PolywrapCoreClientConfig; + /** + * Returns the configuration used to instantiate the client + * + * @returns an immutable Polywrap client config + */ + public getConfig(): PolywrapCoreClientConfig { ``` ### setTracingEnabled ```ts -/** - * Enable tracing for intricate debugging - * - * @remarks - * Tracing uses the @polywrap/tracing-js package - * - * @param tracerConfig - configure options such as the tracing level - * @returns void - */ -setTracingEnabled(tracerConfig?: Partial): void; + /** + * Enable tracing for intricate debugging + * + * @remarks + * Tracing uses the @polywrap/tracing-js package + * + * @param tracerConfig - configure options such as the tracing level + * @returns void + */ + public setTracingEnabled(tracerConfig?: Partial): void { ``` ### getInterfaces ```ts -/** - * returns all interfaces from the configuration used to instantiate the client - * - * @returns an array of interfaces and their registered implementations - */ -getInterfaces(): readonly InterfaceImplementations[] | undefined; + /** + * returns all interfaces from the configuration used to instantiate the client + * + * @returns an array of interfaces and their registered implementations + */ + @Tracer.traceMethod("PolywrapClient: getInterfaces") + public getInterfaces(): readonly InterfaceImplementations[] | undefined { ``` ### getEnvs ```ts -/** - * returns all env registrations from the configuration used to instantiate the client - * - * @returns an array of env objects containing wrapper environmental variables - */ -getEnvs(): readonly Env[] | undefined; + /** + * returns all env registrations from the configuration used to instantiate the client + * + * @returns an array of env objects containing wrapper environmental variables + */ + @Tracer.traceMethod("PolywrapClient: getEnvs") + public getEnvs(): readonly Env[] | undefined { ``` ### getResolver ```ts -/** - * returns the URI resolver from the configuration used to instantiate the client - * - * @returns an object that implements the IUriResolver interface - */ -getResolver(): IUriResolver; + /** + * returns the URI resolver from the configuration used to instantiate the client + * + * @returns an object that implements the IUriResolver interface + */ + @Tracer.traceMethod("PolywrapClient: getUriResolver") + public getResolver(): IUriResolver { ``` ### getEnvByUri ```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 - */ -getEnvByUri(uri: TUri): Env | undefined; -``` - -### getResolver -```ts -/** - * returns the URI resolver from the configuration used to instantiate the client - * - * @returns an object that implements the IUriResolver interface - */ -getResolver(): IUriResolver; + /** + * 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 + */ + @Tracer.traceMethod("PolywrapClient: getEnvByUri") + public getEnvByUri( + uri: TUri + ): Env | undefined { ``` ### getManifest ```ts -/** - * returns a package's wrap manifest - * - * @param uri - a wrap URI - * @returns a Result containing the WrapManifest if the request was successful - */ -getManifest(uri: TUri): Promise>; + /** + * returns a package's wrap manifest + * + * @param uri - a wrap URI + * @returns a Result containing the WrapManifest if the request was successful + */ + @Tracer.traceMethod("PolywrapClient: getManifest") + public async getManifest( + uri: TUri + ): Promise> { ``` ### getFile ```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 - */ -getFile(uri: TUri, options: GetFileOptions): Promise>; + /** + * 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 + */ + @Tracer.traceMethod("PolywrapClient: getFile") + public async getFile( + uri: TUri, + options: GetFileOptions + ): Promise> { ``` ### getImplementations ```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 - */ -getImplementations(uri: TUri, options?: GetImplementationsOptions): Promise>; + /** + * 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 + */ + @Tracer.traceMethod("PolywrapClient: getImplementations") + public async getImplementations( + uri: TUri, + options: GetImplementationsOptions = {} + ): Promise> { ``` ### invokeWrapper ```ts -/** - * Invoke a wrapper using standard syntax and 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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * 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 - */ -invokeWrapper(options: InvokerOptions & { - wrapper: Wrapper; -}): Promise>; + /** + * Invoke a wrapper using standard syntax and 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 ordering arguments. + * args?: Record | Uint8Array; + * + * // Env variables for the wrapper invocation. + * env?: Record; + * + * 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 + */ + @Tracer.traceMethod("PolywrapClient: invokeWrapper") + public async invokeWrapper< + TData = unknown, + TUri extends Uri | string = string + >( + options: InvokerOptions & { wrapper: Wrapper } + ): Promise> { ``` ### invoke ```ts -/** - * Invoke a wrapper using standard syntax. - * 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 ordering arguments. - * args?: Record | Uint8Array; - * - * // Env variables for the wrapper invocation. - * env?: Record; - * - * 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 - */ -invoke(options: InvokerOptions): Promise>; + /** + * Invoke a wrapper using standard syntax. + * 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 ordering arguments. + * args?: Record | Uint8Array; + * + * // Env variables for the wrapper invocation. + * env?: Record; + * + * 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 + */ + @Tracer.traceMethod("PolywrapClient: invoke") + public async invoke( + options: InvokerOptions + ): Promise> { ``` ### tryResolveUri ```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 - */ -tryResolveUri(options: TryResolveUriOptions): Promise>; + /** + * 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 + */ + @Tracer.traceMethod("PolywrapClient: tryResolveUri", TracingLevel.High) + public async tryResolveUri( + options: TryResolveUriOptions + ): Promise> { ``` ### loadWrapper ```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 either a wrapper if successful - */ -loadWrapper(uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions): Promise>; + /** + * 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 + */ + @Tracer.traceMethod("PolywrapClient: loadWrapper", TracingLevel.High) + public async loadWrapper( + uri: Uri, + resolutionContext?: IUriResolutionContext, + options?: DeserializeManifestOptions + ): Promise> { ``` ### validate ```ts -/** - * Validate a wrapper, given a URI. - * Optionally, validate the full ABI and/or recursively validate imports. - * - * @param uri: the Uri to resolve - * @param options - { abi?: boolean; recursive?: boolean } - * @returns A Promise with a Result containing a boolean or Error - */ -validate(uri: TUri, options: ValidateOptions): Promise>; + /** + * Validate a wrapper, given a URI. + * Optionally, validate the full ABI and/or recursively validate imports. + * + * @param uri - the Uri to resolve + * @param options - { abi?: boolean; recursive?: boolean } + * @returns A Promise with a Result containing a boolean or Error + */ + @Tracer.traceMethod("PolywrapClient: validateConfig") + public async validate( + uri: TUri, + options: ValidateOptions + ): Promise> { ``` ## Development diff --git a/packages/js/core-client/package.json b/packages/js/core-client/package.json index e37dc60978..dababd77a9 100644 --- a/packages/js/core-client/package.json +++ b/packages/js/core-client/package.json @@ -14,7 +14,8 @@ "scripts": { "build": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", - "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit" + "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", + "build:readme": "yarn doc-snippets combine" }, "dependencies": { "@polywrap/core-js": "0.10.0-pre.6", @@ -24,6 +25,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { + "doc-snippets": "^0.4.0-pre.1", "@polywrap/uri-resolvers-js": "0.10.0-pre.6", "@types/jest": "26.0.8", "@types/uuid": "8.3.0", @@ -37,5 +39,21 @@ "gitHead": "7346adaf5adb7e6bbb70d9247583e995650d390a", "publishConfig": { "access": "public" + }, + "doc-snippets": { + "extract": { + "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./src" + }, + "inject": { + "dir": "./readme", + "include": "./README.md" + }, + "outputDir": "./" } } diff --git a/packages/js/core-client/readme/README.md b/packages/js/core-client/readme/README.md new file mode 100644 index 0000000000..568a52e164 --- /dev/null +++ b/packages/js/core-client/readme/README.md @@ -0,0 +1,180 @@ +# @polywrap/core-client-js + +npm + + +
+
+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 + +### Instantiate the client +```ts +import { PolywrapCoreClient } from "@polywrap/core-client-js"; + +const config = { ... }; +const client = new PolywrapCoreClient(config); +``` + +### Invoke a wrapper + +```ts +await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } +}); +``` + +### Configure the core client + +```ts +const config = { + // declare interface implementations + interfaces: [ + { + interface: "wrap://ens/uri-resolver.core.polywrap.eth", + implementations: [ + "wrap://ens/ipfs-resolver.polywrap.eth", + ], + }, + ], + // set environmental variables for a wrapper + envs: [ + { + uri: "wrap://ens/ipfs.polywrap.eth", + env: { + provider: "https://ipfs.wrappers.io", + }, + }, + ], + // customize URI resolution by adding redirects and embedded wrappers/packages + resolver: + RecursiveResolver.from( + PackageToWrapperCacheResolver.from( + [ + StaticResolver.from([ + ...redirects, + ...wrappers, + ...packages, + ]), + ...this.config.resolvers, + new ExtendableUriResolver(), + ], + new WrapperCache() + ) + ), + // tracer configuration - see @polywrap/tracing-js package + tracerConfig: { ... }, +}; +``` +```ts +// create a client by modifying the default configuration bundle +const client = new PolywrapCoreClient(config); +``` + +## Types + +```ts +$snippet: PolywrapCoreClientConfig +``` + +## PolywrapCoreClient + +### Constructor +```ts +$snippet: PolywrapCoreClient-constructor +``` + +### getConfig +```ts +$snippet: PolywrapCoreClient-getConfig +``` + +### setTracingEnabled +```ts +$snippet: PolywrapCoreClient-setTracingEnabled +``` + +### getInterfaces +```ts +$snippet: PolywrapCoreClient-getInterfaces +``` + +### getEnvs +```ts +$snippet: PolywrapCoreClient-getEnvs +``` + +### getResolver +```ts +$snippet: PolywrapCoreClient-getResolver +``` + +### getEnvByUri +```ts +$snippet: PolywrapCoreClient-getEnvByUri +``` + +### getManifest +```ts +$snippet: PolywrapCoreClient-getManifest +``` + +### getFile +```ts +$snippet: PolywrapCoreClient-getFile +``` + +### getImplementations +```ts +$snippet: PolywrapCoreClient-getImplementations +``` + +### invokeWrapper +```ts +$snippet: PolywrapCoreClient-invokeWrapper +``` + +### invoke +```ts +$snippet: PolywrapCoreClient-invoke +``` + +### tryResolveUri +```ts +$snippet: PolywrapCoreClient-tryResolveUri +``` + +### loadWrapper +```ts +$snippet: PolywrapCoreClient-loadWrapper +``` + +### validate +```ts +$snippet: PolywrapCoreClient-validate +``` + +## Development + +The Polywrap JavaScript client is open-source. It lives within the [Polywrap toolchain monorepo](https://github.com/polywrap/toolchain/tree/origin/packages/js/client). Contributions from the community are welcomed! + +### Build +```bash +nvm use && yarn install && yarn build +``` + +### Test +```bash +yarn test +`` \ No newline at end of file diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index 2e4ce5150f..e0f7c44138 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -35,12 +35,14 @@ import { Result, ResultErr, ResultOk } from "@polywrap/result"; export class PolywrapCoreClient implements CoreClient { private _config: PolywrapCoreClientConfig; + // $start: PolywrapCoreClient-constructor /** * Instantiate a PolywrapClient * * @param config - a core client configuration */ constructor(config: PolywrapCoreClientConfig) { + // $end try { this.setTracingEnabled(config?.tracerConfig); @@ -57,15 +59,18 @@ export class PolywrapCoreClient implements CoreClient { } } + // $start: PolywrapCoreClient-getConfig /** * Returns the configuration used to instantiate the client * * @returns an immutable Polywrap client config */ public getConfig(): PolywrapCoreClientConfig { + // $end return this._config; } + // $start: PolywrapCoreClient-setTracingEnabled /** * Enable tracing for intricate debugging * @@ -76,6 +81,7 @@ export class PolywrapCoreClient implements CoreClient { * @returns void */ public setTracingEnabled(tracerConfig?: Partial): void { + // $end if (tracerConfig?.consoleEnabled || tracerConfig?.httpEnabled) { Tracer.enableTracing("PolywrapClient", tracerConfig); } else { @@ -83,6 +89,7 @@ export class PolywrapCoreClient implements CoreClient { } } + // $start: PolywrapCoreClient-getInterfaces /** * returns all interfaces from the configuration used to instantiate the client * @@ -90,9 +97,11 @@ export class PolywrapCoreClient implements CoreClient { */ @Tracer.traceMethod("PolywrapClient: getInterfaces") public getInterfaces(): readonly InterfaceImplementations[] | undefined { + // $end return this._config.interfaces; } + // $start: PolywrapCoreClient-getEnvs /** * returns all env registrations from the configuration used to instantiate the client * @@ -100,9 +109,11 @@ export class PolywrapCoreClient implements CoreClient { */ @Tracer.traceMethod("PolywrapClient: getEnvs") public getEnvs(): readonly Env[] | undefined { + // $end return this._config.envs; } + // $start: PolywrapCoreClient-getResolver /** * returns the URI resolver from the configuration used to instantiate the client * @@ -110,9 +121,11 @@ export class PolywrapCoreClient implements CoreClient { */ @Tracer.traceMethod("PolywrapClient: getUriResolver") public getResolver(): IUriResolver { + // $end return this._config.resolver; } + // $start: PolywrapCoreClient-getEnvByUri /** * returns an env (a set of environmental variables) from the configuration used to instantiate the client * @@ -123,6 +136,7 @@ export class PolywrapCoreClient implements CoreClient { public getEnvByUri( uri: TUri ): Env | undefined { + // $end const uriUri = Uri.from(uri); const envs = this.getEnvs(); @@ -133,6 +147,7 @@ export class PolywrapCoreClient implements CoreClient { return envs.find((environment) => Uri.equals(environment.uri, uriUri)); } + // $start: PolywrapCoreClient-getManifest /** * returns a package's wrap manifest * @@ -143,6 +158,7 @@ export class PolywrapCoreClient implements CoreClient { public async getManifest( uri: TUri ): Promise> { + // $end const load = await this.loadWrapper(Uri.from(uri), undefined); if (!load.ok) { return load; @@ -153,6 +169,7 @@ export class PolywrapCoreClient implements CoreClient { return ResultOk(manifest); } + // $start: PolywrapCoreClient-getFile /** * returns a file contained in a wrap package * @@ -165,6 +182,7 @@ export class PolywrapCoreClient implements CoreClient { uri: TUri, options: GetFileOptions ): Promise> { + // $end const load = await this.loadWrapper(Uri.from(uri), undefined); if (!load.ok) { return load; @@ -174,6 +192,7 @@ export class PolywrapCoreClient implements CoreClient { return await wrapper.getFile(options); } + // $start: PolywrapCoreClient-getImplementations /** * returns the interface implementations associated with an interface URI * from the configuration used to instantiate the client @@ -187,6 +206,7 @@ export class PolywrapCoreClient implements CoreClient { uri: TUri, options: GetImplementationsOptions = {} ): Promise> { + // $end const isUriTypeString = typeof uri === "string"; const applyResolution = !!options.applyResolution; @@ -208,6 +228,7 @@ export class PolywrapCoreClient implements CoreClient { return ResultOk(uris); } + // $start: PolywrapCoreClient-invokeWrapper /** * Invoke a wrapper using standard syntax and an instance of the wrapper * @@ -239,6 +260,7 @@ export class PolywrapCoreClient implements CoreClient { >( options: InvokerOptions & { wrapper: Wrapper } ): Promise> { + // $end try { const typedOptions: InvokeOptions = { ...options, @@ -268,6 +290,7 @@ export class PolywrapCoreClient implements CoreClient { } } + // $start: PolywrapCoreClient-invoke /** * Invoke a wrapper using standard syntax. * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper. @@ -297,6 +320,7 @@ export class PolywrapCoreClient implements CoreClient { public async invoke( options: InvokerOptions ): Promise> { + // $end try { const typedOptions: InvokeOptions = { ...options, @@ -338,6 +362,7 @@ export class PolywrapCoreClient implements CoreClient { } } + // $start: PolywrapCoreClient-tryResolveUri /** * Resolve a URI to a wrap package, a wrapper, or a uri * @@ -348,6 +373,7 @@ export class PolywrapCoreClient implements CoreClient { public async tryResolveUri( options: TryResolveUriOptions ): Promise> { + // $end const uri = Uri.from(options.uri); const uriResolver = this.getResolver(); @@ -372,6 +398,7 @@ export class PolywrapCoreClient implements CoreClient { return response; } + // $start: PolywrapCoreClient-loadWrapper /** * Resolve a URI to a wrap package or wrapper. * If the URI resolves to wrap package, load the wrapper. @@ -391,6 +418,7 @@ export class PolywrapCoreClient implements CoreClient { resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions ): Promise> { + // $end Tracer.setAttribute("label", `Wrapper loaded: ${uri}`, TracingLevel.High); if (!resolutionContext) { @@ -448,6 +476,7 @@ export class PolywrapCoreClient implements CoreClient { } } + // $start: PolywrapCoreClient-validate /** * Validate a wrapper, given a URI. * Optionally, validate the full ABI and/or recursively validate imports. @@ -461,6 +490,7 @@ export class PolywrapCoreClient implements CoreClient { uri: TUri, options: ValidateOptions ): Promise> { + // $end const wrapper = await this.loadWrapper(Uri.from(uri)); if (!wrapper.ok) { return ResultErr(new Error(wrapper.error?.message)); diff --git a/packages/js/core-client/src/PolywrapCoreClientConfig.ts b/packages/js/core-client/src/PolywrapCoreClientConfig.ts index b0fa62f4e6..134298c6a3 100644 --- a/packages/js/core-client/src/PolywrapCoreClientConfig.ts +++ b/packages/js/core-client/src/PolywrapCoreClientConfig.ts @@ -1,6 +1,7 @@ import { CoreClientConfig, Uri } from "@polywrap/core-js"; import { TracerConfig } from "@polywrap/tracing-js"; +// $start: PolywrapCoreClientConfig /** * Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors. * @@ -14,3 +15,4 @@ export interface PolywrapCoreClientConfig< /** configuration for opentelemetry tracing to aid in debugging */ readonly tracerConfig?: Readonly>; } +// $end From baca401f71e8c4c826791cd1d9e2e3ceac316da3 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 27 Dec 2022 23:34:44 +0530 Subject: [PATCH 11/25] using doc-snippets package to build readme in @polywrap/client-config-builder-js --- packages/js/client-config-builder/README.md | 393 +++++++++--------- .../js/client-config-builder/package.json | 20 +- .../js/client-config-builder/readme/README.md | 166 ++++++++ .../client-config-builder/src/ClientConfig.ts | 2 + .../src/ClientConfigBuilder.ts | 2 + .../src/IClientConfigBuilder.ts | 44 ++ 6 files changed, 431 insertions(+), 196 deletions(-) create mode 100644 packages/js/client-config-builder/readme/README.md diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index 65863c42cb..3c4f4e6ab7 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -85,287 +85,290 @@ export interface ClientConfig { ### Constructor ```ts -/** - * Instantiate a ClientConfigBuilder - * - * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache - * @param resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig - */ -constructor(wrapperCache?: IWrapperCache | undefined, resolver?: IUriResolver | undefined); + /** + * Instantiate a ClientConfigBuilder + * + * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache + * @param resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig + */ + constructor( + private readonly wrapperCache?: IWrapperCache, + private readonly resolver?: IUriResolver + ) { ``` ### build ```ts -/** - * Build a sanitized client configuration that can be passed to the PolywrapClient constructor - * - * @returns ClientConfig that results from applying all the steps in the builder pipeline - */ -build(): ClientConfig; + /** + * Build a sanitized client configuration that can be passed to the PolywrapClient constructor + * + * @returns ClientConfig that results from applying all the steps in the builder pipeline + */ + build(): ClientConfig; ``` ### buildCoreConfig ```ts -/** - * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors - * - * @returns CoreClientConfig that results from applying all the steps in the builder pipeline - */ -buildCoreConfig(): CoreClientConfig; + /** + * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors + * + * @returns CoreClientConfig that results from applying all the steps in the builder pipeline + */ + buildCoreConfig(): CoreClientConfig; ``` ### add ```ts -/** - * Add a partial ClientConfig - * This is equivalent to calling each of the plural add functions: `addEnvs`, `addWrappers`, etc. - * - * @param config: a partial CliengConfig - * @returns IClientConfigBuilder (mutated self) - */ -add(config: Partial): IClientConfigBuilder; + /** + * Add a partial ClientConfig + * This is equivalent to calling each of the plural add functions: `addEnvs`, `addWrappers`, etc. + * + * @param config: a partial CliengConfig + * @returns IClientConfigBuilder (mutated self) + */ + add(config: Partial): IClientConfigBuilder; ``` ### addDefaults ```ts -/** - * Add the default configuration bundle - * - * @returns IClientConfigBuilder (mutated self) - */ -addDefaults(): IClientConfigBuilder; + /** + * Add the default configuration bundle + * + * @returns IClientConfigBuilder (mutated self) + */ + addDefaults(): IClientConfigBuilder; ``` ### addWrapper ```ts -/** - * Add an embedded wrapper - * - * @param uriWrapper: a wrapper and its URI - * @returns IClientConfigBuilder (mutated self) - */ -addWrapper(uriWrapper: IUriWrapper): IClientConfigBuilder; + /** + * Add an embedded wrapper + * + * @param uriWrapper: a wrapper and its URI + * @returns IClientConfigBuilder (mutated self) + */ + addWrapper(uriWrapper: IUriWrapper): IClientConfigBuilder; ``` ### addWrappers ```ts -/** - * Add one or more embedded wrappers. - * This is equivalent to calling addWrapper for each wrapper. - * - * @param uriWrappers: a list of wrappers and their URIs - * @returns IClientConfigBuilder (mutated self) - */ -addWrappers(uriWrappers: IUriWrapper[]): IClientConfigBuilder; + /** + * Add one or more embedded wrappers. + * This is equivalent to calling addWrapper for each wrapper. + * + * @param uriWrappers: a list of wrappers and their URIs + * @returns IClientConfigBuilder (mutated self) + */ + addWrappers(uriWrappers: IUriWrapper[]): IClientConfigBuilder; ``` ### removeWrapper ```ts -/** - * Remove an embedded wrapper - * - * @param uri: the wrapper's URI - * @returns IClientConfigBuilder (mutated self) - */ -removeWrapper(uri: Uri | string): IClientConfigBuilder; + /** + * Remove an embedded wrapper + * + * @param uri: the wrapper's URI + * @returns IClientConfigBuilder (mutated self) + */ + removeWrapper(uri: Uri | string): IClientConfigBuilder; ``` ### addPackage ```ts -/** - * Add an embedded wrap package - * - * @param uriPackage: a package and its URI - * @returns IClientConfigBuilder (mutated self) - */ -addPackage(uriPackage: IUriPackage): IClientConfigBuilder; + /** + * Add an embedded wrap package + * + * @param uriPackage: a package and its URI + * @returns IClientConfigBuilder (mutated self) + */ + addPackage(uriPackage: IUriPackage): IClientConfigBuilder; ``` ### addPackages ```ts -/** - * Add one or more embedded wrap packages - * This is equivalent to calling addPackage for each package - * - * @param uriPackages: a list of packages and their URIs - * @returns IClientConfigBuilder (mutated self) - */ -addPackages(uriPackages: IUriPackage[]): IClientConfigBuilder; + /** + * Add one or more embedded wrap packages + * This is equivalent to calling addPackage for each package + * + * @param uriPackages: a list of packages and their URIs + * @returns IClientConfigBuilder (mutated self) + */ + addPackages(uriPackages: IUriPackage[]): IClientConfigBuilder; ``` ### removePackage ```ts -/** - * Remove an embedded wrap package - * - * @param uri: the package's URI - * @returns IClientConfigBuilder (mutated self) - */ -removePackage(uri: Uri | string): IClientConfigBuilder; + /** + * Remove an embedded wrap package + * + * @param uri: the package's URI + * @returns IClientConfigBuilder (mutated self) + */ + removePackage(uri: Uri | string): IClientConfigBuilder; ``` ### addEnv ```ts -/** - * Add an Env. - * If an Env is already associated with the uri, it is modified. - * - * @param uri: the wrapper's URI to associate with the Env - * @param env: a string-index map of msgpack-serializable environmental variables - * @returns IClientConfigBuilder (mutated self) - */ -addEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + /** + * Add an Env. + * If an Env is already associated with the uri, it is modified. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ + addEnv(uri: Uri | string, env: Record): IClientConfigBuilder; ``` ### addEnvs ```ts -/** - * Add one or more Envs - * This is equivalent to calling addEnv for each Env - * - * @param envs: a list of Envs - * @returns IClientConfigBuilder (mutated self) - */ -addEnvs(envs: Env[]): IClientConfigBuilder; + /** + * Add one or more Envs + * This is equivalent to calling addEnv for each Env + * + * @param envs: a list of Envs + * @returns IClientConfigBuilder (mutated self) + */ + addEnvs(envs: Env[]): IClientConfigBuilder; ``` ### removeEnv ```ts -/** - * Remove an Env - * - * @param uri: the URI associated with the Env - * @returns IClientConfigBuilder (mutated self) - */ -removeEnv(uri: Uri | string): IClientConfigBuilder; + /** + * Remove an Env + * + * @param uri: the URI associated with the Env + * @returns IClientConfigBuilder (mutated self) + */ + removeEnv(uri: Uri | string): IClientConfigBuilder; ``` ### setEnv ```ts -/** - * Add an Env. - * If an Env is already associated with the uri, it is replaced. - * - * @param uri: the wrapper's URI to associate with the Env - * @param env: a string-index map of msgpack-serializable environmental variables - * @returns IClientConfigBuilder (mutated self) - */ -setEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + /** + * Add an Env. + * If an Env is already associated with the uri, it is replaced. + * + * @param uri: the wrapper's URI to associate with the Env + * @param env: a string-index map of msgpack-serializable environmental variables + * @returns IClientConfigBuilder (mutated self) + */ + setEnv(uri: Uri | string, env: Record): IClientConfigBuilder; ``` ### addInterfaceImplementation ```ts -/** - * Register an implementation of a single interface - * - * @param interfaceUri: the URI of the interface - * @param implementationUri: the URI of the implementation - * @returns IClientConfigBuilder (mutated self) - */ -addInterfaceImplementation( - interfaceUri: Uri | string, - implementationUri: Uri | string -): IClientConfigBuilder; + /** + * Register an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ + addInterfaceImplementation( + interfaceUri: Uri | string, + implementationUri: Uri | string + ): IClientConfigBuilder; ``` ### addInterfaceImplementations ```ts -/** - * Register one or more implementation of a single interface - * - * @param interfaceUri: the URI of the interface - * @param implementationUris: a list of URIs for the implementations - * @returns IClientConfigBuilder (mutated self) - */ -addInterfaceImplementations( - interfaceUri: Uri | string, - implementationUris: Array -): IClientConfigBuilder; + /** + * Register one or more implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUris: a list of URIs for the implementations + * @returns IClientConfigBuilder (mutated self) + */ + addInterfaceImplementations( + interfaceUri: Uri | string, + implementationUris: Array + ): IClientConfigBuilder; ``` ### removeInterfaceImplementation ```ts -/** - * Remove an implementation of a single interface - * - * @param interfaceUri: the URI of the interface - * @param implementationUri: the URI of the implementation - * @returns IClientConfigBuilder (mutated self) - */ -removeInterfaceImplementation( - interfaceUri: Uri | string, - implementationUri: Uri | string -): IClientConfigBuilder; + /** + * Remove an implementation of a single interface + * + * @param interfaceUri: the URI of the interface + * @param implementationUri: the URI of the implementation + * @returns IClientConfigBuilder (mutated self) + */ + removeInterfaceImplementation( + interfaceUri: Uri | string, + implementationUri: Uri | string + ): IClientConfigBuilder; ``` ### addRedirect ```ts -/** - * Add a redirect from one URI to another - * - * @param from: the URI to redirect from - * @param to: the URI to redirect to - * @returns IClientConfigBuilder (mutated self) - */ -addRedirect(from: Uri | string, to: Uri | string): IClientConfigBuilder; + /** + * Add a redirect from one URI to another + * + * @param from: the URI to redirect from + * @param to: the URI to redirect to + * @returns IClientConfigBuilder (mutated self) + */ + addRedirect(from: Uri | string, to: Uri | string): IClientConfigBuilder; ``` ### addRedirects ```ts -/** - * Add an array of URI redirects - * - * @param redirects: a list of URI redirects - * @returns IClientConfigBuilder (mutated self) - */ -addRedirects(redirects: IUriRedirect[]): IClientConfigBuilder; + /** + * Add an array of URI redirects + * + * @param redirects: a list of URI redirects + * @returns IClientConfigBuilder (mutated self) + */ + addRedirects(redirects: IUriRedirect[]): IClientConfigBuilder; ``` ### removeRedirect ```ts -/** - * Remove a URI redirect - * - * @param from: the URI that is being redirected - * @returns IClientConfigBuilder (mutated self) - */ -removeRedirect(from: Uri | string): IClientConfigBuilder; + /** + * Remove a URI redirect + * + * @param from: the URI that is being redirected + * @returns IClientConfigBuilder (mutated self) + */ + removeRedirect(from: Uri | string): IClientConfigBuilder; ``` ### addResolver ```ts -/** - * Add a URI Resolver, capable of resolving a URI to a wrapper - * - * @remarks - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @param resolver: A UriResolverLike - * @returns IClientConfigBuilder (mutated self) - */ -addResolver(resolver: UriResolverLike): IClientConfigBuilder; + /** + * Add a URI Resolver, capable of resolving a URI to a wrapper + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolver: A UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ + addResolver(resolver: UriResolverLike): IClientConfigBuilder; ``` ### addResolvers ```ts -/** - * Add one or more URI Resolvers, capable of resolving URIs to wrappers - * - * @remarks - * A UriResolverLike can be any one of: - * IUriResolver - * | IUriRedirect - * | IUriPackage - * | IUriWrapper - * | UriResolverLike[]; - * - * @param resolvers: A list of UriResolverLike - * @returns IClientConfigBuilder (mutated self) - */ -addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; + /** + * Add one or more URI Resolvers, capable of resolving URIs to wrappers + * + * @remarks + * A UriResolverLike can be any one of: + * IUriResolver + * | IUriRedirect + * | IUriPackage + * | IUriWrapper + * | UriResolverLike[]; + * + * @param resolvers: A list of UriResolverLike + * @returns IClientConfigBuilder (mutated self) + */ + addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; ``` \ No newline at end of file diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index 18f0b3c3b9..5139313fe0 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -16,9 +16,11 @@ "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose", "test:ci": "jest --passWithNoTests --runInBand --verbose", - "test:watch": "jest --watch --passWithNoTests --verbose" + "test:watch": "jest --watch --passWithNoTests --verbose", + "build:readme": "yarn doc-snippets combine" }, "dependencies": { + "doc-snippets": "^0.4.0-pre.1", "@polywrap/core-js": "0.10.0-pre.6", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", @@ -45,5 +47,21 @@ "gitHead": "7346adaf5adb7e6bbb70d9247583e995650d390a", "publishConfig": { "access": "public" + }, + "doc-snippets": { + "extract": { + "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./src" + }, + "inject": { + "dir": "./readme", + "include": "./README.md" + }, + "outputDir": "./" } } diff --git a/packages/js/client-config-builder/readme/README.md b/packages/js/client-config-builder/readme/README.md new file mode 100644 index 0000000000..dd7e7fdbcd --- /dev/null +++ b/packages/js/client-config-builder/readme/README.md @@ -0,0 +1,166 @@ +# PolywrapClient Config Builder + +A DSL for building the PolywrapClient config object. + +Supports building configs using method chaining or imperatively. + +```typescript= +import { ClientConfigBuilder } from "@polywrap/client-config-builder-js"; +import { PolywrapClient } from "@polywrap/client-js"; + +const config = new ClientConfigBuilder() + .add({ + envs: [/*...*/], + interfaces: [/*...*/], + redirects: [/*...*/], + wrappers: [/*...*/], + packages: [/*...*/], + resolvers: [/*...*/], + }) + .add({/*...*/}) + .build(); + +// ... + +const builder = new ClientConfigBuilder(); + +builder.addDefaults(); + +builder.add({ + packages: [/*...*/] +}); + +builder.add({ + envs: [/*...*/] +}); + +const config = builder.build(); + + +// ... + +let client = new PolywrapClient(config); +``` + +## Types + +```ts +$snippet: ClientConfig +``` + +## ClientConfigBuilder + +### Constructor +```ts +$snippet: ClientConfigBuilder-constructor +``` + +### build +```ts +$snippet: IClientConfigBuilder-build +``` + +### buildCoreConfig +```ts +$snippet: IClientConfigBuilder-buildCoreConfig +``` + +### add +```ts +$snippet: IClientConfigBuilder-add +``` + +### addDefaults +```ts +$snippet: IClientConfigBuilder-addDefaults +``` + +### addWrapper +```ts +$snippet: IClientConfigBuilder-addWrapper +``` + +### addWrappers +```ts +$snippet: IClientConfigBuilder-addWrappers +``` + +### removeWrapper +```ts +$snippet: IClientConfigBuilder-removeWrapper +``` + +### addPackage +```ts +$snippet: IClientConfigBuilder-addPackage +``` + +### addPackages +```ts +$snippet: IClientConfigBuilder-addPackages +``` + +### removePackage +```ts +$snippet: IClientConfigBuilder-removePackage +``` + +### addEnv +```ts +$snippet: IClientConfigBuilder-addEnv +``` + +### addEnvs +```ts +$snippet: IClientConfigBuilder-addEnvs +``` + +### removeEnv +```ts +$snippet: IClientConfigBuilder-removeEnv +``` + +### setEnv +```ts +$snippet: IClientConfigBuilder-setEnv +``` + +### addInterfaceImplementation +```ts +$snippet: IClientConfigBuilder-addInterfaceImplementation +``` + +### addInterfaceImplementations +```ts +$snippet: IClientConfigBuilder-addInterfaceImplementations +``` + +### removeInterfaceImplementation +```ts +$snippet: IClientConfigBuilder-removeInterfaceImplementation +``` + +### addRedirect +```ts +$snippet: IClientConfigBuilder-addRedirect +``` + +### addRedirects +```ts +$snippet: IClientConfigBuilder-addRedirects +``` + +### removeRedirect +```ts +$snippet: IClientConfigBuilder-removeRedirect +``` + +### addResolver +```ts +$snippet: IClientConfigBuilder-addResolver +``` + +### addResolvers +```ts +$snippet: IClientConfigBuilder-addResolvers +``` \ No newline at end of file diff --git a/packages/js/client-config-builder/src/ClientConfig.ts b/packages/js/client-config-builder/src/ClientConfig.ts index 5bad83f779..90ce1c3870 100644 --- a/packages/js/client-config-builder/src/ClientConfig.ts +++ b/packages/js/client-config-builder/src/ClientConfig.ts @@ -8,6 +8,7 @@ import { } from "@polywrap/core-js"; import { UriResolverLike } from "@polywrap/uri-resolvers-js"; +// $start: ClientConfig /** * Client configuration that can be passed to the PolywrapClient * @@ -42,3 +43,4 @@ export interface ClientConfig { * */ readonly resolvers: UriResolverLike[]; } +// $end diff --git a/packages/js/client-config-builder/src/ClientConfigBuilder.ts b/packages/js/client-config-builder/src/ClientConfigBuilder.ts index 901338fcca..1fd360fee0 100644 --- a/packages/js/client-config-builder/src/ClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/ClientConfigBuilder.ts @@ -12,6 +12,7 @@ import { import { ExtendableUriResolver } from "@polywrap/uri-resolver-extensions-js"; export class ClientConfigBuilder extends BaseClientConfigBuilder { + // $start: ClientConfigBuilder-constructor /** * Instantiate a ClientConfigBuilder * @@ -22,6 +23,7 @@ export class ClientConfigBuilder extends BaseClientConfigBuilder { private readonly wrapperCache?: IWrapperCache, private readonly resolver?: IUriResolver ) { + // $end super(); } diff --git a/packages/js/client-config-builder/src/IClientConfigBuilder.ts b/packages/js/client-config-builder/src/IClientConfigBuilder.ts index 36d1fb36cd..9d398efff5 100644 --- a/packages/js/client-config-builder/src/IClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/IClientConfigBuilder.ts @@ -11,20 +11,25 @@ import { import { UriResolverLike } from "@polywrap/uri-resolvers-js"; export interface IClientConfigBuilder { + // $start: IClientConfigBuilder-build /** * Build a sanitized client configuration that can be passed to the PolywrapClient constructor * * @returns ClientConfig that results from applying all the steps in the builder pipeline */ build(): ClientConfig; + // $end + // $start: IClientConfigBuilder-buildCoreConfig /** * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors * * @returns CoreClientConfig that results from applying all the steps in the builder pipeline */ buildCoreConfig(): CoreClientConfig; + // $end + // $start: IClientConfigBuilder-add /** * Add a partial ClientConfig * This is equivalent to calling each of the plural add functions: `addEnvs`, `addWrappers`, etc. @@ -33,14 +38,18 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ add(config: Partial): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addDefaults /** * Add the default configuration bundle * * @returns IClientConfigBuilder (mutated self) */ addDefaults(): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addWrapper /** * Add an embedded wrapper * @@ -48,7 +57,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addWrapper(uriWrapper: IUriWrapper): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addWrappers /** * Add one or more embedded wrappers. * This is equivalent to calling addWrapper for each wrapper. @@ -57,7 +68,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addWrappers(uriWrappers: IUriWrapper[]): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-removeWrapper /** * Remove an embedded wrapper * @@ -65,7 +78,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ removeWrapper(uri: Uri | string): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addPackage /** * Add an embedded wrap package * @@ -73,7 +88,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addPackage(uriPackage: IUriPackage): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addPackages /** * Add one or more embedded wrap packages * This is equivalent to calling addPackage for each package @@ -82,7 +99,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addPackages(uriPackages: IUriPackage[]): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-removePackage /** * Remove an embedded wrap package * @@ -90,7 +109,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ removePackage(uri: Uri | string): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addEnv /** * Add an Env. * If an Env is already associated with the uri, it is modified. @@ -100,7 +121,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addEnvs /** * Add one or more Envs * This is equivalent to calling addEnv for each Env @@ -109,7 +132,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addEnvs(envs: Env[]): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-removeEnv /** * Remove an Env * @@ -117,7 +142,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ removeEnv(uri: Uri | string): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-setEnv /** * Add an Env. * If an Env is already associated with the uri, it is replaced. @@ -127,7 +154,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ setEnv(uri: Uri | string, env: Record): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addInterfaceImplementation /** * Register an implementation of a single interface * @@ -139,7 +168,9 @@ export interface IClientConfigBuilder { interfaceUri: Uri | string, implementationUri: Uri | string ): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addInterfaceImplementations /** * Register one or more implementation of a single interface * @@ -151,7 +182,9 @@ export interface IClientConfigBuilder { interfaceUri: Uri | string, implementationUris: Array ): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-removeInterfaceImplementation /** * Remove an implementation of a single interface * @@ -163,7 +196,9 @@ export interface IClientConfigBuilder { interfaceUri: Uri | string, implementationUri: Uri | string ): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addRedirect /** * Add a redirect from one URI to another * @@ -172,7 +207,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addRedirect(from: Uri | string, to: Uri | string): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addRedirects /** * Add an array of URI redirects * @@ -180,7 +217,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addRedirects(redirects: IUriRedirect[]): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-removeRedirect /** * Remove a URI redirect * @@ -188,7 +227,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ removeRedirect(from: Uri | string): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addResolver /** * Add a URI Resolver, capable of resolving a URI to a wrapper * @@ -204,7 +245,9 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addResolver(resolver: UriResolverLike): IClientConfigBuilder; + // $end + // $start: IClientConfigBuilder-addResolvers /** * Add one or more URI Resolvers, capable of resolving URIs to wrappers * @@ -220,4 +263,5 @@ export interface IClientConfigBuilder { * @returns IClientConfigBuilder (mutated self) */ addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; + // $end } From 9a010e1034395c2ef2a3a269207b3abca741e09a Mon Sep 17 00:00:00 2001 From: krisbitney Date: Wed, 28 Dec 2022 14:41:46 +0530 Subject: [PATCH 12/25] using doc-snippets package to build readme in @polywrap/core-js --- .../client-config-builder/src/ClientConfig.ts | 4 +- .../js/core-client/src/PolywrapCoreClient.ts | 17 +- packages/js/core/README.md | 548 ++++++++++++++++++ packages/js/core/package.json | 6 +- packages/js/core/readme/README.md | 76 +++ packages/js/core/readme/config/final.json | 21 + .../js/core/readme/config/sub-sections.json | 18 + .../js/core/readme/sub-sections/base/Uri.md | 67 +++ packages/js/core/src/types/CoreClient.ts | 6 +- packages/js/core/src/types/Env.ts | 5 + packages/js/core/src/types/IUriPackage.ts | 8 + packages/js/core/src/types/IUriRedirect.ts | 8 + packages/js/core/src/types/IUriWrapper.ts | 8 + packages/js/core/src/types/IWrapPackage.ts | 19 + .../src/types/InterfaceImplementations.ts | 10 +- packages/js/core/src/types/Invoke.ts | 54 +- packages/js/core/src/types/MaybeAsync.ts | 5 + packages/js/core/src/types/Uri.ts | 70 +++ packages/js/core/src/types/UriResolver.ts | 14 +- packages/js/core/src/types/Wrapper.ts | 5 +- 20 files changed, 949 insertions(+), 20 deletions(-) create mode 100644 packages/js/core/readme/README.md create mode 100644 packages/js/core/readme/config/final.json create mode 100644 packages/js/core/readme/config/sub-sections.json create mode 100644 packages/js/core/readme/sub-sections/base/Uri.md diff --git a/packages/js/client-config-builder/src/ClientConfig.ts b/packages/js/client-config-builder/src/ClientConfig.ts index 90ce1c3870..462bf34f86 100644 --- a/packages/js/client-config-builder/src/ClientConfig.ts +++ b/packages/js/client-config-builder/src/ClientConfig.ts @@ -19,10 +19,10 @@ export interface ClientConfig { /** set environmental variables for a wrapper */ readonly envs: Env[]; - /** redirect invocations from one uri to another */ + /** register interface implementations */ readonly interfaces: InterfaceImplementations[]; - /** register interface implementations */ + /** redirect invocations from one uri to another */ readonly redirects: IUriRedirect[]; /** add embedded wrappers */ diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index e0f7c44138..9e1e77517f 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -230,7 +230,7 @@ export class PolywrapCoreClient implements CoreClient { // $start: PolywrapCoreClient-invokeWrapper /** - * Invoke a wrapper using standard syntax and an instance of the wrapper + * Invoke a wrapper using an instance of the wrapper. * * @param options - { * // The Wrapper's URI @@ -239,18 +239,21 @@ export class PolywrapCoreClient implements CoreClient { * // Method to be executed. * method: string; * - * //Arguments for the method, structured as a map, removing the chance of incorrectly ordering arguments. + * //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 */ @Tracer.traceMethod("PolywrapClient: invokeWrapper") @@ -292,7 +295,9 @@ export class PolywrapCoreClient implements CoreClient { // $start: PolywrapCoreClient-invoke /** - * Invoke a wrapper using standard syntax. + * Invoke a wrapper. + * + * @remarks * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper. * * @param options - { @@ -302,18 +307,18 @@ export class PolywrapCoreClient implements CoreClient { * // Method to be executed. * method: string; * - * //Arguments for the method, structured as a map, removing the chance of incorrectly ordering arguments. + * //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 */ @Tracer.traceMethod("PolywrapClient: invoke") diff --git a/packages/js/core/README.md b/packages/js/core/README.md index abaa064f6d..aef743ad02 100644 --- a/packages/js/core/README.md +++ b/packages/js/core/README.md @@ -1,3 +1,551 @@ # @polywrap/core-js A TypeScript / JavaScript implementation of the WRAP standard, including all fundamental types & algorithms. + +## Types + +### CoreClient + +```ts + +/** Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors */ +export interface CoreClientConfig { + /** set environmental variables for a wrapper */ + readonly interfaces?: Readonly[]>; + + /** register interface implementations */ + readonly envs?: Readonly[]>; + + /** configure URI resolution for redirects, packages, and wrappers */ + readonly resolver: Readonly>; +} + +/** Options for CoreClient's getFile method */ +export interface GetFileOptions { + /** file path from wrapper root */ + path: string; + + /** file encoding */ + encoding?: "utf-8" | string; +} + +/** Options for CoreClient's getImplementations method */ +export interface GetImplementationsOptions { + /** If true, follow redirects to resolve URIs */ + applyResolution?: boolean; + + /** Use and update an existing resolution context */ + resolutionContext?: IUriResolutionContext; +} + +/** Options for CoreClient's validate method */ +export interface ValidateOptions { + /** Validate full ABI */ + abi?: boolean; + + /** Recursively validate import URIs */ + recursive?: boolean; +} + +/** CoreClient invokes wrappers and interacts with wrap packages. */ +export interface CoreClient extends Invoker, UriResolverHandler { + /** + * Returns the configuration used to instantiate the client + * + * @returns an immutable core client config + */ + getConfig(): CoreClientConfig; + + /** + * returns all interfaces from the configuration used to instantiate the client + * + * @returns an array of interfaces and their registered implementations + */ + getInterfaces(): readonly InterfaceImplementations[] | undefined; + + /** + * returns all env registrations from the configuration used to instantiate the client + * + * @returns an array of env objects containing wrapper environmental variables + */ + getEnvs(): readonly Env[] | undefined; + + /** + * 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 + */ + getEnvByUri(uri: TUri): Env | undefined; + + /** + * returns the URI resolver from the configuration used to instantiate the client + * + * @returns an object that implements the IUriResolver interface + */ + getResolver(): IUriResolver; + + /** + * returns a package's wrap manifest + * + * @param uri - a wrap URI + * @returns a Result containing the WrapManifest if the request was successful + */ + getManifest( + uri: TUri + ): Promise>; + + /** + * 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 + */ + getFile( + uri: TUri, + options: GetFileOptions + ): Promise>; + + /** + * 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 + */ + getImplementations( + uri: TUri, + options: GetImplementationsOptions + ): Promise>; + + /** + * Validate a wrapper, given a URI. + * Optionally, validate the full ABI and/or recursively validate imports. + * + * @param uri: the Uri to resolve + * @param options - { abi?: boolean; recursive?: boolean } + * @returns A Promise with a Result containing a boolean or Error + */ + validate( + uri: TUri, + options?: ValidateOptions + ): Promise>; +} + +``` + +### Env + +```ts + +/** A map of string-indexed, Msgpack-serializable environmental variables associated with a wrapper */ +export interface Env { + /** Uri of wrapper */ + uri: TUri; + + /** Env variables used by the module */ + env: Record; +} + +``` + +### InterfaceImplementations + +```ts + +/** An interface and a list of wrappers that implement the interface */ +export interface InterfaceImplementations { + /** Uri of interface */ + interface: TUri; + + /** Uris of implementations */ + implementations: TUri[]; +} + +``` + +### Invoke + +```ts + +/** Options required for an Wrapper invocation. */ +export interface InvokeOptions { + /** 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; +} + +/** + * Result of an Wrapper invocation. + * + * @template TData Type of the invoke result data. + */ +export type InvokeResult = Result; + +/** + * Provides options for the invoker to set based on the state of the invocation. + * Extends InvokeOptions. + */ +export interface InvokerOptions + extends InvokeOptions { + /** If true, the InvokeResult will (if successful) contain a Msgpack-encoded byte array */ + encodeResult?: boolean; +} + +/** + * An entity capable of invoking wrappers. + * + * @template TData Type of the invoke result data. + */ +export interface Invoker { + /** + * Invoke a wrapper using an instance of the wrapper. + * + * @param options - invoker options and a wrapper instance to invoke + * @returns A Promise with a Result containing the return value or an error + */ + invokeWrapper( + options: InvokerOptions & { wrapper: Wrapper } + ): Promise>; + + /** + * Invoke a wrapper. + * + * @remarks + * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper. + * + * @param options - invoker options + * @returns A Promise with a Result containing the return value or an error + */ + invoke( + options: InvokerOptions + ): Promise>; +} + +/** + * Result of a Wrapper invocation, possibly Msgpack-encoded. + * + * @template TData Type of the invoke result data. + */ +export type InvocableResult = InvokeResult & { + /** If true, result (if successful) contains a Msgpack-encoded byte array */ + encoded?: boolean; +}; + +/** An invocable entity, such as a wrapper. */ +export interface Invocable { + /** + * Invoke this object. + * + * @param options - invoke options + * @param invoker - an Invoker, capable of invoking this object + * @returns A Promise with a Result containing the return value or an error + */ + invoke( + options: InvokeOptions, + invoker: Invoker + ): Promise>; +} + +``` + +### IUriPackage + +```ts + +/** Associates a URI with an embedded wrap package */ +export interface IUriPackage { + /** The package's URI */ + uri: TUri; + + /** The wrap package */ + package: IWrapPackage; +} + +``` + +### IUriRedirect + +```ts + +/** Redirect invocations from one URI to another */ +export interface IUriRedirect { + /** URI to redirect from */ + from: TUri; + + /** URI to redirect to */ + to: TUri; +} + +``` + +### IUriWrapper + +```ts + +/** Associates a URI with an embedded wrapper */ +export interface IUriWrapper { + /** The URI to resolve to the wrapper */ + uri: TUri; + + /** A wrapper instance */ + wrapper: Wrapper; +} + +``` + +### IWrapPackage + +```ts + +/** Options for IWrapPackage's getManifest method */ +export interface GetManifestOptions { + /** If true, manifest validation step will be skipped */ + noValidate?: boolean; +} + +/** A wrap package, capable of producing instances of a wrapper and its manifest */ +export interface IWrapPackage { + /** + * Produce an instance of the wrap manifest + * + * @param options - GetManifestOptions; customize manifest retrieval + * @returns A Promise with a Result containing the wrap manifest or an error + */ + getManifest( + options?: GetManifestOptions + ): Promise>; + + /** + * Produce an instance of the wrapper + * + * @param options - DeserializeManifestOptions; customize manifest deserialization + * @returns A Promise with a Result containing the wrapper or an error + */ + createWrapper( + options?: DeserializeManifestOptions + ): Promise>; +} + +``` + +### MaybeAsync + +```ts + +/** Alias for a type that is either a value or a promise that resolves to the value */ +export type MaybeAsync = Promise | T; + +``` + +### Uri + +#### UriConfig +```ts +/** URI configuration */ +export interface UriConfig { + /** URI Authority: allows the Polywrap URI resolution algorithm to determine an authoritative URI resolver. */ + authority: string; + + /** URI Path: tells the Authority where the Wrapper resides. */ + path: string; + + /** Full string representation of URI */ + uri: string; +} +``` + +#### Uri + +```ts +/** + * A Polywrap URI. Some examples of valid URIs are: + * wrap://ipfs/QmHASH + * wrap://ens/sub.dimain.eth + * wrap://fs/directory/file.txt + * wrap://uns/domain.crypto + * + * Breaking down the various parts of the URI, as it applies + * to [the URI standard](https://tools.ietf.org/html/rfc3986#section-3): + * **wrap://** - URI Scheme: differentiates Polywrap URIs. + * **ipfs/** - URI Authority: allows the Polywrap URI resolution algorithm to determine an authoritative URI resolver. + * **sub.domain.eth** - URI Path: tells the Authority where the Wrapper resides. + */ +export class Uri { +``` + +##### constructor +```ts + /** + * Construct a Uri instance from a wrap URI string + * + * @remarks + * Throws if URI string is invalid + * + * @param uri - a string representation of a wrap URI + */ + constructor(uri: string) { +``` + +##### authority +```ts + /** @returns Uri authority */ + public get authority(): string { +``` + +##### path +```ts + /** @returns Uri path */ + public get path(): string { +``` + +##### uri +```ts + /** @returns Uri string representation */ + public get uri(): string { +``` + +##### equals +```ts + /** Test two Uri instances for equality */ + public static equals(a: Uri, b: Uri): boolean { +``` + +##### isUri +```ts + /** + * Check if a value is an instance of Uri + * + * @param value - value to check + * @returns true if value is a Uri instance */ + public static isUri(value: unknown): value is Uri { +``` + +##### isValidUri +```ts + /** + * Test if a URI string is a valid wrap URI + * + * @param uri - URI string + * @param parsed? - UriConfig to update (mutate) with content of URI string + * @returns true if input string is a valid wrap URI */ + public static isValidUri(uri: string, parsed?: UriConfig): boolean { +``` + +##### toString +```ts + /** @returns Uri string representation */ + public toString(): string { +``` + +##### toJSON +```ts + /** @returns Uri string representation */ + public toJSON(): string { +``` + +##### parseUri +```ts + /** + * Parse a wrap URI string into its authority and path + * + * @param uri - a string representation of a wrap URI + * @returns A Result containing a UriConfig, if successful, or an error + */ + @Tracer.traceMethod("Uri: parseUri") + public static parseUri(uri: string): Result { +``` + +##### from +```ts + /** + * Construct a Uri instance from a Uri or a wrap URI string + * + * @remarks + * Throws if URI string is invalid + * + * @param uri - a Uri instance or a string representation of a wrap URI + */ + @Tracer.traceMethod("Uri: from") + public static from(uri: Uri | string): Uri { +``` + +### UriResolver + +```ts + +/** Options required for URI resolution. */ +export interface TryResolveUriOptions { + /** The Wrapper's URI */ + uri: TUri; + + /** A URI resolution context */ + resolutionContext?: IUriResolutionContext; +} + +/** An entity capable of resolving a WRAP URI */ +export interface UriResolverHandler { + /** + * Resolve a URI to a wrap package, a wrapper, or a uri + * + * @param options - TryResolveUriOptions + * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful + */ + tryResolveUri( + options?: TryResolveUriOptions + ): Promise>; +} + +``` + +### Wrapper + +```ts + +/** + * The Wrapper definition, which can be used to spawn + * many invocations of this particular Wrapper. Internally + * this class may do things like caching WASM bytecode, spawning + * worker threads, or indexing into resolvers to find the requested method. + */ +export interface Wrapper extends Invocable { + /** + * Invoke the Wrapper based on the provided [[InvokeOptions]] + * + * @param options Options for this invocation. + * @param invoker The client instance requesting this invocation. + * This client will be used for any sub-invokes that occur. + */ + invoke( + options: InvokeOptions, + invoker: Invoker + ): Promise>; + + /** + * Get a file from the Wrapper package. + * + * @param options Configuration options for file retrieval + */ + getFile(options: GetFileOptions): Promise>; + + /** + * Get a manifest from the Wrapper package. + */ + getManifest(): WrapManifest; +} + +``` + diff --git a/packages/js/core/package.json b/packages/js/core/package.json index 7e3d509374..ad969a7d82 100644 --- a/packages/js/core/package.json +++ b/packages/js/core/package.json @@ -16,7 +16,10 @@ "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose", "test:ci": "jest --passWithNoTests --runInBand --verbose", - "test:watch": "jest --watch --passWithNoTests --verbose" + "test:watch": "jest --watch --passWithNoTests --verbose", + "build:readme:subsections": "yarn doc-snippets combine -c ./readme/config/sub-sections.json", + "build:readme:final": "yarn doc-snippets combine -c ./readme/config/final.json", + "build:readme": "yarn build:readme:subsections && yarn build:readme:final" }, "dependencies": { "@polywrap/result": "0.10.0-pre.6", @@ -24,6 +27,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { + "doc-snippets": "^0.4.0-pre.1", "@types/jest": "26.0.8", "@types/mustache": "4.0.1", "@types/prettier": "2.6.0", diff --git a/packages/js/core/readme/README.md b/packages/js/core/readme/README.md new file mode 100644 index 0000000000..26d56cd702 --- /dev/null +++ b/packages/js/core/readme/README.md @@ -0,0 +1,76 @@ +# @polywrap/core-js + +A TypeScript / JavaScript implementation of the WRAP standard, including all fundamental types & algorithms. + +## Types + +### CoreClient + +```ts +$snippet: CoreClient.ts +``` + +### Env + +```ts +$snippet: Env.ts +``` + +### InterfaceImplementations + +```ts +$snippet: InterfaceImplementations.ts +``` + +### Invoke + +```ts +$snippet: Invoke.ts +``` + +### IUriPackage + +```ts +$snippet: IUriPackage.ts +``` + +### IUriRedirect + +```ts +$snippet: IUriRedirect.ts +``` + +### IUriWrapper + +```ts +$snippet: IUriWrapper.ts +``` + +### IWrapPackage + +```ts +$snippet: IWrapPackage.ts +``` + +### MaybeAsync + +```ts +$snippet: MaybeAsync.ts +``` + +### Uri + +$snippet: Uri.md + +### UriResolver + +```ts +$snippet: UriResolver.ts +``` + +### Wrapper + +```ts +$snippet: Wrapper.ts +``` + diff --git a/packages/js/core/readme/config/final.json b/packages/js/core/readme/config/final.json new file mode 100644 index 0000000000..dd4994a2ec --- /dev/null +++ b/packages/js/core/readme/config/final.json @@ -0,0 +1,21 @@ +{ + "doc-snippets": { + "extract": { + "include": [ + "./src/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "./readme/sub-sections/injected/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}" + ], + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./" + }, + "inject": { + "dir": "./readme", + "include": "./README.md" + }, + "outputDir": "./" + } +} \ No newline at end of file diff --git a/packages/js/core/readme/config/sub-sections.json b/packages/js/core/readme/config/sub-sections.json new file mode 100644 index 0000000000..3a50a30d2d --- /dev/null +++ b/packages/js/core/readme/config/sub-sections.json @@ -0,0 +1,18 @@ +{ + "doc-snippets": { + "extract": { + "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./src" + }, + "inject": { + "dir": "./readme/sub-sections/base", + "include": "./**/*.md" + }, + "outputDir": "./readme/sub-sections/injected" + } +} \ No newline at end of file diff --git a/packages/js/core/readme/sub-sections/base/Uri.md b/packages/js/core/readme/sub-sections/base/Uri.md new file mode 100644 index 0000000000..f808bd0eb5 --- /dev/null +++ b/packages/js/core/readme/sub-sections/base/Uri.md @@ -0,0 +1,67 @@ +$start: Uri.md +#### UriConfig +```ts +$snippet: UriConfig +``` + +#### Uri + +```ts +$snippet: Uri +``` + +##### constructor +```ts +$snippet: Uri-constructor +``` + +##### authority +```ts +$snippet: Uri-authority +``` + +##### path +```ts +$snippet: Uri-path +``` + +##### uri +```ts +$snippet: Uri-uri +``` + +##### equals +```ts +$snippet: Uri-equals +``` + +##### isUri +```ts +$snippet: Uri-isUri +``` + +##### isValidUri +```ts +$snippet: Uri-isValidUri +``` + +##### toString +```ts +$snippet: Uri-toString +``` + +##### toJSON +```ts +$snippet: Uri-toJSON +``` + +##### parseUri +```ts +$snippet: Uri-parseUri +``` + +##### from +```ts +$snippet: Uri-from +``` +$end \ No newline at end of file diff --git a/packages/js/core/src/types/CoreClient.ts b/packages/js/core/src/types/CoreClient.ts index 5ce606995e..e4f86b2a5e 100644 --- a/packages/js/core/src/types/CoreClient.ts +++ b/packages/js/core/src/types/CoreClient.ts @@ -5,6 +5,8 @@ import { UriResolverHandler } from "./UriResolver"; import { WrapManifest } from "@polywrap/wrap-manifest-types-js"; import { Result } from "@polywrap/result"; +// $start: CoreClient.ts + /** Core Client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors */ export interface CoreClientConfig { /** set environmental variables for a wrapper */ @@ -44,7 +46,7 @@ export interface ValidateOptions { recursive?: boolean; } -/** CoreClient invokes wrapper functions, and interacts with wrap packages. */ +/** CoreClient invokes wrappers and interacts with wrap packages. */ export interface CoreClient extends Invoker, UriResolverHandler { /** * Returns the configuration used to instantiate the client @@ -130,3 +132,5 @@ export interface CoreClient extends Invoker, UriResolverHandler { options?: ValidateOptions ): Promise>; } + +// $end diff --git a/packages/js/core/src/types/Env.ts b/packages/js/core/src/types/Env.ts index df02244e33..d6174370e1 100644 --- a/packages/js/core/src/types/Env.ts +++ b/packages/js/core/src/types/Env.ts @@ -2,6 +2,9 @@ import { Uri } from "."; import { Tracer } from "@polywrap/tracing-js"; +// $start: Env.ts + +/** A map of string-indexed, Msgpack-serializable environmental variables associated with a wrapper */ export interface Env { /** Uri of wrapper */ uri: TUri; @@ -10,6 +13,8 @@ export interface Env { env: Record; } +// $end + export const sanitizeEnvs = Tracer.traceFunc( "core: sanitizeEnvs", (environments: Env[]): Env[] => { diff --git a/packages/js/core/src/types/IUriPackage.ts b/packages/js/core/src/types/IUriPackage.ts index f7b27f64e0..1defddcd75 100644 --- a/packages/js/core/src/types/IUriPackage.ts +++ b/packages/js/core/src/types/IUriPackage.ts @@ -1,6 +1,14 @@ import { Uri, IWrapPackage } from "."; +// $start: IUriPackage.ts + +/** Associates a URI with an embedded wrap package */ export interface IUriPackage { + /** The package's URI */ uri: TUri; + + /** The wrap package */ package: IWrapPackage; } + +// $end diff --git a/packages/js/core/src/types/IUriRedirect.ts b/packages/js/core/src/types/IUriRedirect.ts index 3475f727a0..eb10b707cd 100644 --- a/packages/js/core/src/types/IUriRedirect.ts +++ b/packages/js/core/src/types/IUriRedirect.ts @@ -1,6 +1,14 @@ import { Uri } from "."; +// $start: IUriRedirect.ts + +/** Redirect invocations from one URI to another */ export interface IUriRedirect { + /** URI to redirect from */ from: TUri; + + /** URI to redirect to */ to: TUri; } + +// $end diff --git a/packages/js/core/src/types/IUriWrapper.ts b/packages/js/core/src/types/IUriWrapper.ts index 0a5aa5c622..e5c0fe9496 100644 --- a/packages/js/core/src/types/IUriWrapper.ts +++ b/packages/js/core/src/types/IUriWrapper.ts @@ -1,6 +1,14 @@ import { Uri, Wrapper } from "."; +// $start: IUriWrapper.ts + +/** Associates a URI with an embedded wrapper */ export interface IUriWrapper { + /** The URI to resolve to the wrapper */ uri: TUri; + + /** A wrapper instance */ wrapper: Wrapper; } + +// $end diff --git a/packages/js/core/src/types/IWrapPackage.ts b/packages/js/core/src/types/IWrapPackage.ts index a5c5db9979..ac28aa4726 100644 --- a/packages/js/core/src/types/IWrapPackage.ts +++ b/packages/js/core/src/types/IWrapPackage.ts @@ -6,16 +6,35 @@ import { } from "@polywrap/wrap-manifest-types-js"; import { Result } from "@polywrap/result"; +// $start: IWrapPackage.ts + /** Options for IWrapPackage's getManifest method */ export interface GetManifestOptions { + /** If true, manifest validation step will be skipped */ noValidate?: boolean; } +/** A wrap package, capable of producing instances of a wrapper and its manifest */ export interface IWrapPackage { + /** + * Produce an instance of the wrap manifest + * + * @param options - GetManifestOptions; customize manifest retrieval + * @returns A Promise with a Result containing the wrap manifest or an error + */ getManifest( options?: GetManifestOptions ): Promise>; + + /** + * Produce an instance of the wrapper + * + * @param options - DeserializeManifestOptions; customize manifest deserialization + * @returns A Promise with a Result containing the wrapper or an error + */ createWrapper( options?: DeserializeManifestOptions ): Promise>; } + +// $end diff --git a/packages/js/core/src/types/InterfaceImplementations.ts b/packages/js/core/src/types/InterfaceImplementations.ts index d38fd3f55d..bae7026ba5 100644 --- a/packages/js/core/src/types/InterfaceImplementations.ts +++ b/packages/js/core/src/types/InterfaceImplementations.ts @@ -2,11 +2,19 @@ import { Uri } from "."; import { Tracer } from "@polywrap/tracing-js"; +// $start: InterfaceImplementations.ts + +/** An interface and a list of wrappers that implement the interface */ export interface InterfaceImplementations { + /** Uri of interface */ interface: TUri; + + /** Uris of implementations */ implementations: TUri[]; } +// $end + export const sanitizeInterfaceImplementations = Tracer.traceFunc( "core: sanitizeInterfaceImplementations", ( @@ -26,4 +34,4 @@ export const sanitizeInterfaceImplementations = Tracer.traceFunc( return output; } -); +); \ No newline at end of file diff --git a/packages/js/core/src/types/Invoke.ts b/packages/js/core/src/types/Invoke.ts index 3a0214f5fb..7bf79f662c 100644 --- a/packages/js/core/src/types/Invoke.ts +++ b/packages/js/core/src/types/Invoke.ts @@ -3,6 +3,8 @@ import { IUriResolutionContext } from "../uri-resolution"; import { Result } from "@polywrap/result"; +// $start: Invoke.ts + /** Options required for an Wrapper invocation. */ export interface InvokeOptions { /** The Wrapper's URI */ @@ -11,17 +13,13 @@ export interface InvokeOptions { /** Method to be executed. */ method: string; - /** - * Arguments for the method, structured as a map, - * removing the chance of incorrectly ordering arguments. - */ + /** 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 variables for the wrapper invocation. */ env?: Record; + /** A Uri resolution context */ resolutionContext?: IUriResolutionContext; } @@ -32,27 +30,69 @@ export interface InvokeOptions { */ export type InvokeResult = Result; +/** + * Provides options for the invoker to set based on the state of the invocation. + * Extends InvokeOptions. + */ export interface InvokerOptions extends InvokeOptions { + /** If true, the InvokeResult will (if successful) contain a Msgpack-encoded byte array */ encodeResult?: boolean; } +/** + * An entity capable of invoking wrappers. + * + * @template TData Type of the invoke result data. + */ export interface Invoker { + /** + * Invoke a wrapper using an instance of the wrapper. + * + * @param options - invoker options and a wrapper instance to invoke + * @returns A Promise with a Result containing the return value or an error + */ invokeWrapper( options: InvokerOptions & { wrapper: Wrapper } ): Promise>; + + /** + * Invoke a wrapper. + * + * @remarks + * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper. + * + * @param options - invoker options + * @returns A Promise with a Result containing the return value or an error + */ invoke( options: InvokerOptions ): Promise>; } +/** + * Result of a Wrapper invocation, possibly Msgpack-encoded. + * + * @template TData Type of the invoke result data. + */ export type InvocableResult = InvokeResult & { + /** If true, result (if successful) contains a Msgpack-encoded byte array */ encoded?: boolean; }; +/** An invocable entity, such as a wrapper. */ export interface Invocable { + /** + * Invoke this object. + * + * @param options - invoke options + * @param invoker - an Invoker, capable of invoking this object + * @returns A Promise with a Result containing the return value or an error + */ invoke( options: InvokeOptions, invoker: Invoker ): Promise>; } + +// $end diff --git a/packages/js/core/src/types/MaybeAsync.ts b/packages/js/core/src/types/MaybeAsync.ts index 1e3bb3d1ad..9c47e84aaa 100644 --- a/packages/js/core/src/types/MaybeAsync.ts +++ b/packages/js/core/src/types/MaybeAsync.ts @@ -1 +1,6 @@ +// $start: MaybeAsync.ts + +/** Alias for a type that is either a value or a promise that resolves to the value */ export type MaybeAsync = Promise | T; + +// $end diff --git a/packages/js/core/src/types/Uri.ts b/packages/js/core/src/types/Uri.ts index cc8afb7c2a..ad86ac87d3 100644 --- a/packages/js/core/src/types/Uri.ts +++ b/packages/js/core/src/types/Uri.ts @@ -1,13 +1,21 @@ import { Tracer } from "@polywrap/tracing-js"; import { Result, ResultErr, ResultOk } from "@polywrap/result"; +// $start: UriConfig /** URI configuration */ export interface UriConfig { + /** URI Authority: allows the Polywrap URI resolution algorithm to determine an authoritative URI resolver. */ authority: string; + + /** URI Path: tells the Authority where the Wrapper resides. */ path: string; + + /** Full string representation of URI */ uri: string; } +// $end +// $start: Uri /** * A Polywrap URI. Some examples of valid URIs are: * wrap://ipfs/QmHASH @@ -22,21 +30,41 @@ export interface UriConfig { * **sub.domain.eth** - URI Path: tells the Authority where the Wrapper resides. */ export class Uri { + // $end private _config: UriConfig; + // $start: Uri-authority + /** @returns Uri authority */ public get authority(): string { + // $end return this._config.authority; } + // $start: Uri-path + /** @returns Uri path */ public get path(): string { + // $end return this._config.path; } + // $start: Uri-uri + /** @returns Uri string representation */ public get uri(): string { + // $end return this._config.uri; } + // $start: Uri-constructor + /** + * Construct a Uri instance from a wrap URI string + * + * @remarks + * Throws if URI string is invalid + * + * @param uri - a string representation of a wrap URI + */ constructor(uri: string) { + // $end const result = Uri.parseUri(uri); if (!result.ok) { throw result.error; @@ -44,15 +72,33 @@ export class Uri { this._config = result.value; } + // $start: Uri-equals + /** Test two Uri instances for equality */ public static equals(a: Uri, b: Uri): boolean { + // $end return a.uri === b.uri; } + // $start: Uri-isUri + /** + * Check if a value is an instance of Uri + * + * @param value - value to check + * @returns true if value is a Uri instance */ public static isUri(value: unknown): value is Uri { + // $end return typeof value === "object" && (value as Uri).uri !== undefined; } + // $start: Uri-isValidUri + /** + * Test if a URI string is a valid wrap URI + * + * @param uri - URI string + * @param parsed? - UriConfig to update (mutate) with content of URI string + * @returns true if input string is a valid wrap URI */ public static isValidUri(uri: string, parsed?: UriConfig): boolean { + // $end const result = Uri.parseUri(uri); if (parsed && result.ok) { @@ -62,16 +108,30 @@ export class Uri { return result.ok; } + // $start: Uri-toString + /** @returns Uri string representation */ public toString(): string { + // $end return this._config.uri; } + // $start: Uri-toJSON + /** @returns Uri string representation */ public toJSON(): string { + // $end return this._config.uri; } + // $start: Uri-parseUri + /** + * Parse a wrap URI string into its authority and path + * + * @param uri - a string representation of a wrap URI + * @returns A Result containing a UriConfig, if successful, or an error + */ @Tracer.traceMethod("Uri: parseUri") public static parseUri(uri: string): Result { + // $end if (!uri) { return ResultErr(Error("The provided URI is empty")); } @@ -125,8 +185,18 @@ export class Uri { }); } + // $start: Uri-from + /** + * Construct a Uri instance from a Uri or a wrap URI string + * + * @remarks + * Throws if URI string is invalid + * + * @param uri - a Uri instance or a string representation of a wrap URI + */ @Tracer.traceMethod("Uri: from") public static from(uri: Uri | string): Uri { + // $end if (typeof uri === "string") { return new Uri(uri); } else if (Uri.isUri(uri)) { diff --git a/packages/js/core/src/types/UriResolver.ts b/packages/js/core/src/types/UriResolver.ts index fb0552dc7a..dae4e98788 100644 --- a/packages/js/core/src/types/UriResolver.ts +++ b/packages/js/core/src/types/UriResolver.ts @@ -3,16 +3,28 @@ import { IUriResolutionContext, UriPackageOrWrapper } from "../uri-resolution"; import { Result } from "@polywrap/result"; -/** Options required for an URI resolution. */ +// $start: UriResolver.ts + +/** Options required for URI resolution. */ export interface TryResolveUriOptions { /** The Wrapper's URI */ uri: TUri; + /** A URI resolution context */ resolutionContext?: IUriResolutionContext; } +/** An entity capable of resolving a WRAP URI */ export interface UriResolverHandler { + /** + * Resolve a URI to a wrap package, a wrapper, or a uri + * + * @param options - TryResolveUriOptions + * @returns A Promise with a Result containing either a wrap package, a wrapper, or a URI if successful + */ tryResolveUri( options?: TryResolveUriOptions ): Promise>; } + +// $end diff --git a/packages/js/core/src/types/Wrapper.ts b/packages/js/core/src/types/Wrapper.ts index 5d5655b4b3..2f6578dded 100644 --- a/packages/js/core/src/types/Wrapper.ts +++ b/packages/js/core/src/types/Wrapper.ts @@ -10,6 +10,8 @@ import { import { WrapManifest } from "@polywrap/wrap-manifest-types-js"; import { Result } from "@polywrap/result"; +// $start: Wrapper.ts + /** * The Wrapper definition, which can be used to spawn * many invocations of this particular Wrapper. Internally @@ -33,7 +35,6 @@ export interface Wrapper extends Invocable { * Get a file from the Wrapper package. * * @param options Configuration options for file retrieval - * @param client The client instance requesting the file. */ getFile(options: GetFileOptions): Promise>; @@ -42,3 +43,5 @@ export interface Wrapper extends Invocable { */ getManifest(): WrapManifest; } + +// $end From d7a603fe91182c215bb39b4145163eb36715488b Mon Sep 17 00:00:00 2001 From: krisbitney Date: Wed, 28 Dec 2022 16:46:20 +0530 Subject: [PATCH 13/25] Added TSDoc comments throughout @polywrap/core-js and ensured they are pulled into readme by doc-snippets --- packages/js/core/.gitignore | 1 + packages/js/core/README.md | 202 +++++++++++++++++- packages/js/core/readme/README.md | 7 + .../sub-sections/base/UriResolverInterface.md | 18 ++ .../sub-sections/base/uri-resolution.md | 37 ++++ .../js/core/src/interfaces/uri-resolver.ts | 25 +++ packages/js/core/src/types/UriResolver.ts | 2 +- .../uri-resolution/IUriResolutionContext.ts | 43 ++++ .../src/uri-resolution/IUriResolutionStep.ts | 10 + .../core/src/uri-resolution/IUriResolver.ts | 11 + .../src/uri-resolution/UriPackageOrWrapper.ts | 8 + .../uri-resolution/UriResolutionContext.ts | 6 + 12 files changed, 368 insertions(+), 2 deletions(-) create mode 100644 packages/js/core/.gitignore create mode 100644 packages/js/core/readme/sub-sections/base/UriResolverInterface.md create mode 100644 packages/js/core/readme/sub-sections/base/uri-resolution.md diff --git a/packages/js/core/.gitignore b/packages/js/core/.gitignore new file mode 100644 index 0000000000..b78cae4e43 --- /dev/null +++ b/packages/js/core/.gitignore @@ -0,0 +1 @@ +readme/sub-sections/injected \ No newline at end of file diff --git a/packages/js/core/README.md b/packages/js/core/README.md index aef743ad02..95987f8aa2 100644 --- a/packages/js/core/README.md +++ b/packages/js/core/README.md @@ -496,7 +496,7 @@ export interface TryResolveUriOptions { resolutionContext?: IUriResolutionContext; } -/** An entity capable of resolving a WRAP URI */ +/** An entity capable of resolving a wrap URI, typically by using an IUriResolver implementation */ export interface UriResolverHandler { /** * Resolve a URI to a wrap package, a wrapper, or a uri @@ -549,3 +549,203 @@ export interface Wrapper extends Invocable { ``` +## UriResolverInterface + +### MaybeUriOrManifest +```ts +/** Contains either a Uri, a manifest, or neither */ +export interface MaybeUriOrManifest { + /** wrap URI */ + uri?: string; + + /** Serialized wrap manifest */ + manifest?: Uint8Array; +} +``` + +### Module + +#### tryResolveUri +```ts + /** + * Use an invoker to try to resolve a URI using a wrapper that implements the UriResolver interface + * + * @param invoker - invokes the wrapper with the resolution URI as an argument + * @param wrapper - URI for wrapper that implements the UriResolver interface + * @param uri - the URI to resolve + */ + tryResolveUri: Tracer.traceFunc( + "core: uri-resolver: tryResolveUri", + async ( + invoker: Invoker, + wrapper: Uri, + uri: Uri + ): Promise> => { +``` + +#### getFile +```ts + /** + * Use an invoker to fetch a file using a wrapper that implements the UriResolver interface + * + * @param invoker - invokes the wrapper with the filepath as an argument + * @param wrapper - URI for wrapper that implements the UriResolver interface + * @param path - a filepath, the format of which depends on the UriResolver + */ + getFile: Tracer.traceFunc( + "core: uri-resolver: getFile", + async ( + invoker: Invoker, + wrapper: Uri, + path: string + ): Promise> => { +``` + +## Uri Resolution + +### IUriResolutionContext + +```ts +/** Track and output URI resolution state, path, and history */ +export interface IUriResolutionContext { + /** + * Check if a URI is in the process of being resolved + * + * @param uri - URI to check + * @return true if URI resolution is in process, false otherwise + */ + isResolving(uri: Uri): boolean; + + /** + * Start resolving a URI + * + * @param uri - Uri to resolve + */ + startResolving(uri: Uri): void; + + /** + * Stop resolving a URI + * + * @param uri - Uri being resolved + */ + stopResolving(uri: Uri): void; + + /** + * Push a step onto the resolution history stack + * + * @param step - A completed resolution step + */ + trackStep(step: IUriResolutionStep): void; + + /** @return history of all URI resolution steps completed */ + getHistory(): IUriResolutionStep[]; + + /** @return current URI resolution path */ + getResolutionPath(): Uri[]; + + /** + * Create a new resolution context using the current URI resolution path + * + * @return a UriResolutionContext + */ + createSubHistoryContext(): IUriResolutionContext; + + /** + * Create a new resolution context using the current URI resolution history + * + * @return a UriResolutionContext + */ + createSubContext(): IUriResolutionContext; +} +``` + +### IUriResolutionStep + +```ts +/** A step in the URI resolution algorithm */ +export interface IUriResolutionStep { + /** The current URI being resolved */ + sourceUri: Uri; + + /** The resolution result for the current URI */ + result: Result; + + /** A text/visual description of this URI step */ + description?: string; + + /** History of sub-steps that exist within the context of this URI resolution step */ + subHistory?: IUriResolutionStep[]; +} +``` + +### IUriResolver + +```ts +/** Defines entity capable of resolving a wrap URI */ +export interface IUriResolver { + /** + * Resolve a URI 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 + */ + tryResolveUri( + uri: Uri, + client: CoreClient, + resolutionContext: IUriResolutionContext + ): Promise>; +} +``` + +### UriPackageOrWrapper + +```ts + +/** Indicates that a URI resolved to a Uri */ +export type UriValue = { + type: "uri"; + uri: Uri; +}; + +/** Indicates that a URI resolved to a wrap package */ +export type UriPackageValue = IUriPackage & { + type: "package"; +}; + +/** Indicates that a URI resolved to a wrapper */ +export type UriWrapperValue = IUriWrapper & { + type: "wrapper"; +}; + +/** indicates that a URI resolved to either a wrap package, a wrapper, or a URI */ +export type UriPackageOrWrapper = UriValue | UriPackageValue | UriWrapperValue; + +``` + +### UriResolutionContext + +```ts +/** An implementation of the IUriResolutionContext interface */ +export class UriResolutionContext implements IUriResolutionContext { +``` + +#### constructor + +```ts + /** Construct a UriResolutionContext */ + constructor(); + constructor( + resolvingUriMap: Map, + resolutionPath: Set + ); + constructor( + resolvingUriMap: Map, + history: IUriResolutionStep[] + ); + constructor( + resolvingUriMap?: Map, + resolutionPathOrHistory?: Set | IUriResolutionStep[] + ) { +``` diff --git a/packages/js/core/readme/README.md b/packages/js/core/readme/README.md index 26d56cd702..0644c3e0af 100644 --- a/packages/js/core/readme/README.md +++ b/packages/js/core/readme/README.md @@ -74,3 +74,10 @@ $snippet: UriResolver.ts $snippet: Wrapper.ts ``` +## UriResolverInterface + +$snippet: UriResolverInterface + +## Uri Resolution + +$snippet: uri-resolution.md diff --git a/packages/js/core/readme/sub-sections/base/UriResolverInterface.md b/packages/js/core/readme/sub-sections/base/UriResolverInterface.md new file mode 100644 index 0000000000..b290457e39 --- /dev/null +++ b/packages/js/core/readme/sub-sections/base/UriResolverInterface.md @@ -0,0 +1,18 @@ +$start: UriResolverInterface +### MaybeUriOrManifest +```ts +$snippet: MaybeUriOrManifest +``` + +### Module + +#### tryResolveUri +```ts +$snippet: UriResolverInterface-tryResolveUri +``` + +#### getFile +```ts +$snippet: UriResolverInterface-getFile +``` +$end \ No newline at end of file diff --git a/packages/js/core/readme/sub-sections/base/uri-resolution.md b/packages/js/core/readme/sub-sections/base/uri-resolution.md new file mode 100644 index 0000000000..5e226e9cf9 --- /dev/null +++ b/packages/js/core/readme/sub-sections/base/uri-resolution.md @@ -0,0 +1,37 @@ +$start: uri-resolution.md +### IUriResolutionContext + +```ts +$snippet: IUriResolutionContext +``` + +### IUriResolutionStep + +```ts +$snippet: IUriResolutionStep +``` + +### IUriResolver + +```ts +$snippet: IUriResolver +``` + +### UriPackageOrWrapper + +```ts +$snippet: UriPackageOrWrapper.ts +``` + +### UriResolutionContext + +```ts +$snippet: UriResolutionContext +``` + +#### constructor + +```ts +$snippet: UriResolutionContext-constructor +``` +$end \ No newline at end of file diff --git a/packages/js/core/src/interfaces/uri-resolver.ts b/packages/js/core/src/interfaces/uri-resolver.ts index 9b886a3da5..229b0524bf 100644 --- a/packages/js/core/src/interfaces/uri-resolver.ts +++ b/packages/js/core/src/interfaces/uri-resolver.ts @@ -3,12 +3,27 @@ import { Uri, Invoker } from "../"; import { Tracer } from "@polywrap/tracing-js"; import { Result } from "@polywrap/result"; +// $start: MaybeUriOrManifest +/** Contains either a Uri, a manifest, or neither */ export interface MaybeUriOrManifest { + /** wrap URI */ uri?: string; + + /** Serialized wrap manifest */ manifest?: Uint8Array; } +// $end +/** */ export const module = { + // $start: UriResolverInterface-tryResolveUri + /** + * Use an invoker to try to resolve a URI using a wrapper that implements the UriResolver interface + * + * @param invoker - invokes the wrapper with the resolution URI as an argument + * @param wrapper - URI for wrapper that implements the UriResolver interface + * @param uri - the URI to resolve + */ tryResolveUri: Tracer.traceFunc( "core: uri-resolver: tryResolveUri", async ( @@ -16,6 +31,7 @@ export const module = { wrapper: Uri, uri: Uri ): Promise> => { + // $end return invoker.invoke({ uri: wrapper.uri, method: `tryResolveUri`, @@ -26,6 +42,14 @@ export const module = { }); } ), + // $start: UriResolverInterface-getFile + /** + * Use an invoker to fetch a file using a wrapper that implements the UriResolver interface + * + * @param invoker - invokes the wrapper with the filepath as an argument + * @param wrapper - URI for wrapper that implements the UriResolver interface + * @param path - a filepath, the format of which depends on the UriResolver + */ getFile: Tracer.traceFunc( "core: uri-resolver: getFile", async ( @@ -33,6 +57,7 @@ export const module = { wrapper: Uri, path: string ): Promise> => { + // $end return invoker.invoke({ uri: wrapper.uri, method: "getFile", diff --git a/packages/js/core/src/types/UriResolver.ts b/packages/js/core/src/types/UriResolver.ts index dae4e98788..b4976f19d7 100644 --- a/packages/js/core/src/types/UriResolver.ts +++ b/packages/js/core/src/types/UriResolver.ts @@ -14,7 +14,7 @@ export interface TryResolveUriOptions { resolutionContext?: IUriResolutionContext; } -/** An entity capable of resolving a WRAP URI */ +/** An entity capable of resolving a wrap URI, typically by using an IUriResolver implementation */ export interface UriResolverHandler { /** * Resolve a URI to a wrap package, a wrapper, or a uri diff --git a/packages/js/core/src/uri-resolution/IUriResolutionContext.ts b/packages/js/core/src/uri-resolution/IUriResolutionContext.ts index 52350fa5bf..7e04869a88 100644 --- a/packages/js/core/src/uri-resolution/IUriResolutionContext.ts +++ b/packages/js/core/src/uri-resolution/IUriResolutionContext.ts @@ -1,13 +1,56 @@ import { IUriResolutionStep } from "./IUriResolutionStep"; import { Uri } from ".."; +// $start: IUriResolutionContext +/** Track and output URI resolution state, path, and history */ export interface IUriResolutionContext { + /** + * Check if a URI is in the process of being resolved + * + * @param uri - URI to check + * @return true if URI resolution is in process, false otherwise + */ isResolving(uri: Uri): boolean; + + /** + * Start resolving a URI + * + * @param uri - Uri to resolve + */ startResolving(uri: Uri): void; + + /** + * Stop resolving a URI + * + * @param uri - Uri being resolved + */ stopResolving(uri: Uri): void; + + /** + * Push a step onto the resolution history stack + * + * @param step - A completed resolution step + */ trackStep(step: IUriResolutionStep): void; + + /** @return history of all URI resolution steps completed */ getHistory(): IUriResolutionStep[]; + + /** @return current URI resolution path */ getResolutionPath(): Uri[]; + + /** + * Create a new resolution context using the current URI resolution path + * + * @return a UriResolutionContext + */ createSubHistoryContext(): IUriResolutionContext; + + /** + * Create a new resolution context using the current URI resolution history + * + * @return a UriResolutionContext + */ createSubContext(): IUriResolutionContext; } +// $end diff --git a/packages/js/core/src/uri-resolution/IUriResolutionStep.ts b/packages/js/core/src/uri-resolution/IUriResolutionStep.ts index 731db57b68..535796f78f 100644 --- a/packages/js/core/src/uri-resolution/IUriResolutionStep.ts +++ b/packages/js/core/src/uri-resolution/IUriResolutionStep.ts @@ -3,9 +3,19 @@ import { UriPackageOrWrapper } from "./UriPackageOrWrapper"; import { Result } from "@polywrap/result"; +// $start: IUriResolutionStep +/** A step in the URI resolution algorithm */ export interface IUriResolutionStep { + /** The current URI being resolved */ sourceUri: Uri; + + /** The resolution result for the current URI */ result: Result; + + /** A text/visual description of this URI step */ description?: string; + + /** History of sub-steps that exist within the context of this URI resolution step */ subHistory?: IUriResolutionStep[]; } +// $end diff --git a/packages/js/core/src/uri-resolution/IUriResolver.ts b/packages/js/core/src/uri-resolution/IUriResolver.ts index f714219241..4d7d0667c9 100644 --- a/packages/js/core/src/uri-resolution/IUriResolver.ts +++ b/packages/js/core/src/uri-resolution/IUriResolver.ts @@ -4,10 +4,21 @@ import { UriPackageOrWrapper } from "./UriPackageOrWrapper"; import { Result } from "@polywrap/result"; +// $start: IUriResolver +/** Defines entity capable of resolving a wrap URI */ export interface IUriResolver { + /** + * Resolve a URI 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 + */ tryResolveUri( uri: Uri, client: CoreClient, resolutionContext: IUriResolutionContext ): Promise>; } +// $end diff --git a/packages/js/core/src/uri-resolution/UriPackageOrWrapper.ts b/packages/js/core/src/uri-resolution/UriPackageOrWrapper.ts index ce662e6a76..319231f8b9 100644 --- a/packages/js/core/src/uri-resolution/UriPackageOrWrapper.ts +++ b/packages/js/core/src/uri-resolution/UriPackageOrWrapper.ts @@ -1,17 +1,25 @@ import { Uri } from ".."; import { IUriPackage, IUriWrapper } from "../types"; +// $start: UriPackageOrWrapper.ts + +/** Indicates that a URI resolved to a Uri */ export type UriValue = { type: "uri"; uri: Uri; }; +/** Indicates that a URI resolved to a wrap package */ export type UriPackageValue = IUriPackage & { type: "package"; }; +/** Indicates that a URI resolved to a wrapper */ export type UriWrapperValue = IUriWrapper & { type: "wrapper"; }; +/** indicates that a URI resolved to either a wrap package, a wrapper, or a URI */ export type UriPackageOrWrapper = UriValue | UriPackageValue | UriWrapperValue; + +// $end diff --git a/packages/js/core/src/uri-resolution/UriResolutionContext.ts b/packages/js/core/src/uri-resolution/UriResolutionContext.ts index b6bb4311ce..a15a79a457 100644 --- a/packages/js/core/src/uri-resolution/UriResolutionContext.ts +++ b/packages/js/core/src/uri-resolution/UriResolutionContext.ts @@ -2,11 +2,16 @@ import { IUriResolutionStep } from "./IUriResolutionStep"; import { IUriResolutionContext } from "./IUriResolutionContext"; import { Uri } from "../types"; +// $start: UriResolutionContext +/** An implementation of the IUriResolutionContext interface */ export class UriResolutionContext implements IUriResolutionContext { + // $end private resolvingUriMap: Map; private resolutionPath: Set; private history: IUriResolutionStep[]; + // $start: UriResolutionContext-constructor + /** Construct a UriResolutionContext */ constructor(); constructor( resolvingUriMap: Map, @@ -20,6 +25,7 @@ export class UriResolutionContext implements IUriResolutionContext { resolvingUriMap?: Map, resolutionPathOrHistory?: Set | IUriResolutionStep[] ) { + // $end this.resolvingUriMap = resolvingUriMap ?? new Map(); if (Array.isArray(resolutionPathOrHistory)) { From cefc757058d958989ca9cbc09eff0526e93a533a Mon Sep 17 00:00:00 2001 From: krisbitney Date: Wed, 28 Dec 2022 16:57:28 +0530 Subject: [PATCH 14/25] lint --- packages/js/core/src/types/InterfaceImplementations.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/js/core/src/types/InterfaceImplementations.ts b/packages/js/core/src/types/InterfaceImplementations.ts index bae7026ba5..9d42a8ab91 100644 --- a/packages/js/core/src/types/InterfaceImplementations.ts +++ b/packages/js/core/src/types/InterfaceImplementations.ts @@ -34,4 +34,4 @@ export const sanitizeInterfaceImplementations = Tracer.traceFunc( return output; } -); \ No newline at end of file +); From 8e036583496784d7af2b400489a5da56d79b32e9 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 3 Jan 2023 18:53:03 +0530 Subject: [PATCH 15/25] updated doc-snippets version to 0.4.0-pre.4 to use inline snippets --- packages/js/client-config-builder/README.md | 145 +++++++++++++++++- .../js/client-config-builder/package.json | 22 ++- .../js/client-config-builder/readme/README.md | 5 + .../src/ClientConfigBuilder.ts | 6 +- .../src/bundles/getDefaultConfig.ts | 2 + packages/js/client/README.md | 2 +- packages/js/client/package.json | 22 ++- packages/js/client/src/PolywrapClient.ts | 3 +- packages/js/core-client/README.md | 47 +++--- packages/js/core-client/package.json | 22 ++- .../js/core-client/src/PolywrapCoreClient.ts | 45 ++---- packages/js/core/README.md | 28 ++-- packages/js/core/package.json | 2 +- packages/js/core/readme/config/final.json | 20 +++ .../js/core/readme/config/sub-sections.json | 20 +++ .../js/core/src/interfaces/uri-resolver.ts | 7 +- packages/js/core/src/types/Uri.ts | 33 ++-- .../uri-resolution/UriResolutionContext.ts | 3 +- yarn.lock | 8 +- 19 files changed, 329 insertions(+), 113 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index 3c4f4e6ab7..858c276741 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -55,10 +55,10 @@ export interface ClientConfig { /** set environmental variables for a wrapper */ readonly envs: Env[]; - /** redirect invocations from one uri to another */ + /** register interface implementations */ readonly interfaces: InterfaceImplementations[]; - /** register interface implementations */ + /** redirect invocations from one uri to another */ readonly redirects: IUriRedirect[]; /** add embedded wrappers */ @@ -85,7 +85,6 @@ export interface ClientConfig { ### Constructor ```ts - /** * Instantiate a ClientConfigBuilder * * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache @@ -94,7 +93,7 @@ export interface ClientConfig { constructor( private readonly wrapperCache?: IWrapperCache, private readonly resolver?: IUriResolver - ) { + ) ``` ### build @@ -371,4 +370,142 @@ export interface ClientConfig { * @returns IClientConfigBuilder (mutated self) */ addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; +``` + +## Bundle: DefaultConfig +```ts +export const getDefaultConfig = (): ClientConfig => { + return { + envs: [ + { + uri: new Uri(defaultWrappers.graphNode), + env: { + provider: "https://api.thegraph.com", + }, + }, + { + uri: new Uri("wrap://ens/ipfs.polywrap.eth"), + env: { + provider: defaultIpfsProviders[0], + fallbackProviders: defaultIpfsProviders.slice(1), + }, + }, + ], + redirects: [ + { + from: new Uri("wrap://ens/sha3.polywrap.eth"), + to: new Uri(defaultWrappers.sha3), + }, + { + from: new Uri("wrap://ens/uts46.polywrap.eth"), + to: new Uri(defaultWrappers.uts46), + }, + { + from: new Uri("wrap://ens/graph-node.polywrap.eth"), + to: new Uri(defaultWrappers.graphNode), + }, + { + from: new Uri("wrap://ens/wrappers.polywrap.eth:logger@1.0.0"), + to: new Uri("wrap://plugin/logger"), + }, + ], + interfaces: [ + { + interface: new Uri("wrap://ens/uri-resolver.core.polywrap.eth"), + implementations: [ + new Uri("wrap://ens/ipfs-resolver.polywrap.eth"), + new Uri("wrap://ens/ens-resolver.polywrap.eth"), + new Uri("wrap://ens/fs-resolver.polywrap.eth"), + new Uri("wrap://ens/http-resolver.polywrap.eth"), + // ens-text-record-resolver + new Uri("wrap://ipfs/QmfRCVA1MSAjUbrXXjya4xA9QHkbWeiKRsT7Um1cvrR7FY"), + ], + }, + { + interface: new Uri("wrap://ens/wrappers.polywrap.eth:logger@1.0.0"), + implementations: [new Uri("wrap://plugin/logger")], + }, + { + interface: new Uri(defaultWrappers.concurrentInterface), + implementations: [new Uri("wrap://plugin/concurrent")], + }, + ], + packages: getDefaultPlugins(), + wrappers: [], + resolvers: [], + }; +}; + +export const defaultIpfsProviders = [ + "https://ipfs.wrappers.io", + "https://ipfs.io", +]; + +export const defaultWrappers = { + sha3: "wrap://ens/goerli/sha3.wrappers.eth", + uts46: "wrap://ens/goerli/uts46-lite.wrappers.eth", + graphNode: "wrap://ens/goerli/graph-node.wrappers.eth", + concurrentInterface: "wrap://ens/goerli/interface.concurrent.wrappers.eth", +}; + +export const getDefaultPlugins = (): IUriPackage[] => { + return [ + // IPFS is required for downloading Polywrap packages + { + uri: new Uri("wrap://ens/ipfs.polywrap.eth"), + package: ipfsPlugin({}), + }, + // ENS is required for resolving domain to IPFS hashes + { + uri: new Uri("wrap://ens/ens-resolver.polywrap.eth"), + package: ensResolverPlugin({}), + }, + { + uri: new Uri("wrap://ens/ethereum.polywrap.eth"), + package: ethereumPlugin({ + connections: new Connections({ + networks: { + mainnet: new Connection({ + provider: + "https://mainnet.infura.io/v3/b00b2c2cc09c487685e9fb061256d6a6", + }), + goerli: new Connection({ + provider: + "https://goerli.infura.io/v3/b00b2c2cc09c487685e9fb061256d6a6", + }), + }, + }), + }), + }, + { + uri: new Uri("wrap://ens/http.polywrap.eth"), + package: httpPlugin({}), + }, + { + uri: new Uri("wrap://ens/http-resolver.polywrap.eth"), + package: httpResolverPlugin({}), + }, + { + uri: new Uri("wrap://plugin/logger"), + // TODO: remove this once types are updated + package: loggerPlugin({}) as IWrapPackage, + }, + { + uri: new Uri("wrap://ens/fs.polywrap.eth"), + package: fileSystemPlugin({}), + }, + { + uri: new Uri("wrap://ens/fs-resolver.polywrap.eth"), + package: fileSystemResolverPlugin({}), + }, + { + uri: new Uri("wrap://ens/ipfs-resolver.polywrap.eth"), + package: ipfsResolverPlugin({}), + }, + { + uri: new Uri("wrap://plugin/concurrent"), + package: concurrentPromisePlugin({}), + }, + ]; +}; ``` \ No newline at end of file diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index 5139313fe0..6bf0e9cf41 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -20,7 +20,7 @@ "build:readme": "yarn doc-snippets combine" }, "dependencies": { - "doc-snippets": "^0.4.0-pre.1", + "doc-snippets": "^0.4.0-pre.4", "@polywrap/core-js": "0.10.0-pre.6", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", @@ -62,6 +62,26 @@ "dir": "./readme", "include": "./README.md" }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], "outputDir": "./" } } diff --git a/packages/js/client-config-builder/readme/README.md b/packages/js/client-config-builder/readme/README.md index dd7e7fdbcd..9533163267 100644 --- a/packages/js/client-config-builder/readme/README.md +++ b/packages/js/client-config-builder/readme/README.md @@ -163,4 +163,9 @@ $snippet: IClientConfigBuilder-addResolver ### addResolvers ```ts $snippet: IClientConfigBuilder-addResolvers +``` + +## Bundle: DefaultConfig +```ts +$snippet: getDefaultConfig ``` \ No newline at end of file diff --git a/packages/js/client-config-builder/src/ClientConfigBuilder.ts b/packages/js/client-config-builder/src/ClientConfigBuilder.ts index 1fd360fee0..e243503412 100644 --- a/packages/js/client-config-builder/src/ClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/ClientConfigBuilder.ts @@ -12,8 +12,7 @@ import { import { ExtendableUriResolver } from "@polywrap/uri-resolver-extensions-js"; export class ClientConfigBuilder extends BaseClientConfigBuilder { - // $start: ClientConfigBuilder-constructor - /** + /* $start: ClientConfigBuilder-constructor */ /** * Instantiate a ClientConfigBuilder * * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache @@ -22,8 +21,7 @@ export class ClientConfigBuilder extends BaseClientConfigBuilder { constructor( private readonly wrapperCache?: IWrapperCache, private readonly resolver?: IUriResolver - ) { - // $end + ) /* $ */ { super(); } diff --git a/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts b/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts index 2c863a3f6e..0d51a3508a 100644 --- a/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts +++ b/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts @@ -16,6 +16,7 @@ import { loggerPlugin } from "@polywrap/logger-plugin-js"; import { fileSystemResolverPlugin } from "@polywrap/fs-resolver-plugin-js"; import { concurrentPromisePlugin } from "concurrent-plugin-js"; +// $start: getDefaultConfig export const getDefaultConfig = (): ClientConfig => { return { envs: [ @@ -150,3 +151,4 @@ export const getDefaultPlugins = (): IUriPackage[] => { }, ]; }; +// $end diff --git a/packages/js/client/README.md b/packages/js/client/README.md index dd9ffb48cd..6678f08179 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -145,5 +145,5 @@ export interface PolywrapClientConfig | undefined | PolywrapCoreClientConfig, options?: { noDefaults?: boolean } - ) { + ) ``` \ No newline at end of file diff --git a/packages/js/client/package.json b/packages/js/client/package.json index d3e553b1fb..02e41ab748 100644 --- a/packages/js/client/package.json +++ b/packages/js/client/package.json @@ -33,7 +33,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.1", + "doc-snippets": "^0.4.0-pre.4", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", "@polywrap/fs-plugin-js": "0.10.0-pre.6", @@ -76,6 +76,26 @@ "dir": "./readme", "include": "./README.md" }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], "outputDir": "./" } } diff --git a/packages/js/client/src/PolywrapClient.ts b/packages/js/client/src/PolywrapClient.ts index 7734316c4c..ae7a8c1fb8 100644 --- a/packages/js/client/src/PolywrapClient.ts +++ b/packages/js/client/src/PolywrapClient.ts @@ -25,8 +25,7 @@ export class PolywrapClient extends PolywrapCoreClient { | undefined | PolywrapCoreClientConfig, options?: { noDefaults?: boolean } - ) { - // $end + ) /* $ */ { super( !options?.noDefaults ? buildPolywrapCoreClientConfig( diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index a4a5ae1fa9..cb014c186d 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -109,7 +109,7 @@ export interface PolywrapCoreClientConfig< * * @param config - a core client configuration */ - constructor(config: PolywrapCoreClientConfig) { + constructor(config: PolywrapCoreClientConfig) ``` ### getConfig @@ -119,7 +119,7 @@ export interface PolywrapCoreClientConfig< * * @returns an immutable Polywrap client config */ - public getConfig(): PolywrapCoreClientConfig { + public getConfig(): PolywrapCoreClientConfig ``` ### setTracingEnabled @@ -133,7 +133,7 @@ export interface PolywrapCoreClientConfig< * @param tracerConfig - configure options such as the tracing level * @returns void */ - public setTracingEnabled(tracerConfig?: Partial): void { + public setTracingEnabled(tracerConfig?: Partial): void ``` ### getInterfaces @@ -144,7 +144,7 @@ export interface PolywrapCoreClientConfig< * @returns an array of interfaces and their registered implementations */ @Tracer.traceMethod("PolywrapClient: getInterfaces") - public getInterfaces(): readonly InterfaceImplementations[] | undefined { + public getInterfaces(): readonly InterfaceImplementations[] | undefined ``` ### getEnvs @@ -155,7 +155,7 @@ export interface PolywrapCoreClientConfig< * @returns an array of env objects containing wrapper environmental variables */ @Tracer.traceMethod("PolywrapClient: getEnvs") - public getEnvs(): readonly Env[] | undefined { + public getEnvs(): readonly Env[] | undefined ``` ### getResolver @@ -166,7 +166,7 @@ export interface PolywrapCoreClientConfig< * @returns an object that implements the IUriResolver interface */ @Tracer.traceMethod("PolywrapClient: getUriResolver") - public getResolver(): IUriResolver { + public getResolver(): IUriResolver ``` ### getEnvByUri @@ -180,7 +180,7 @@ export interface PolywrapCoreClientConfig< @Tracer.traceMethod("PolywrapClient: getEnvByUri") public getEnvByUri( uri: TUri - ): Env | undefined { + ): Env | undefined ``` ### getManifest @@ -194,7 +194,7 @@ export interface PolywrapCoreClientConfig< @Tracer.traceMethod("PolywrapClient: getManifest") public async getManifest( uri: TUri - ): Promise> { + ): Promise> ``` ### getFile @@ -210,7 +210,7 @@ export interface PolywrapCoreClientConfig< public async getFile( uri: TUri, options: GetFileOptions - ): Promise> { + ): Promise> ``` ### getImplementations @@ -227,13 +227,13 @@ export interface PolywrapCoreClientConfig< public async getImplementations( uri: TUri, options: GetImplementationsOptions = {} - ): Promise> { + ): Promise> ``` ### invokeWrapper ```ts /** - * Invoke a wrapper using standard syntax and an instance of the wrapper + * Invoke a wrapper using an instance of the wrapper. * * @param options - { * // The Wrapper's URI @@ -242,18 +242,21 @@ export interface PolywrapCoreClientConfig< * // Method to be executed. * method: string; * - * //Arguments for the method, structured as a map, removing the chance of incorrectly ordering arguments. + * //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 */ @Tracer.traceMethod("PolywrapClient: invokeWrapper") @@ -262,13 +265,15 @@ export interface PolywrapCoreClientConfig< TUri extends Uri | string = string >( options: InvokerOptions & { wrapper: Wrapper } - ): Promise> { + ): Promise> ``` ### invoke ```ts /** - * Invoke a wrapper using standard syntax. + * Invoke a wrapper. + * + * @remarks * Unlike `invokeWrapper`, this method automatically retrieves and caches the wrapper. * * @param options - { @@ -278,24 +283,24 @@ export interface PolywrapCoreClientConfig< * // Method to be executed. * method: string; * - * //Arguments for the method, structured as a map, removing the chance of incorrectly ordering arguments. + * //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 */ @Tracer.traceMethod("PolywrapClient: invoke") public async invoke( options: InvokerOptions - ): Promise> { + ): Promise> ``` ### tryResolveUri @@ -309,7 +314,7 @@ export interface PolywrapCoreClientConfig< @Tracer.traceMethod("PolywrapClient: tryResolveUri", TracingLevel.High) public async tryResolveUri( options: TryResolveUriOptions - ): Promise> { + ): Promise> ``` ### loadWrapper @@ -332,7 +337,7 @@ export interface PolywrapCoreClientConfig< uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions - ): Promise> { + ): Promise> ``` ### validate @@ -349,7 +354,7 @@ export interface PolywrapCoreClientConfig< public async validate( uri: TUri, options: ValidateOptions - ): Promise> { + ): Promise> ``` ## Development diff --git a/packages/js/core-client/package.json b/packages/js/core-client/package.json index dababd77a9..f4d04bb6a8 100644 --- a/packages/js/core-client/package.json +++ b/packages/js/core-client/package.json @@ -25,7 +25,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.1", + "doc-snippets": "^0.4.0-pre.4", "@polywrap/uri-resolvers-js": "0.10.0-pre.6", "@types/jest": "26.0.8", "@types/uuid": "8.3.0", @@ -54,6 +54,26 @@ "dir": "./readme", "include": "./README.md" }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], "outputDir": "./" } } diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index 9e1e77517f..0671c20669 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -41,8 +41,7 @@ export class PolywrapCoreClient implements CoreClient { * * @param config - a core client configuration */ - constructor(config: PolywrapCoreClientConfig) { - // $end + constructor(config: PolywrapCoreClientConfig) /* $ */ { try { this.setTracingEnabled(config?.tracerConfig); @@ -65,8 +64,7 @@ export class PolywrapCoreClient implements CoreClient { * * @returns an immutable Polywrap client config */ - public getConfig(): PolywrapCoreClientConfig { - // $end + public getConfig(): PolywrapCoreClientConfig /* $ */ { return this._config; } @@ -80,8 +78,7 @@ export class PolywrapCoreClient implements CoreClient { * @param tracerConfig - configure options such as the tracing level * @returns void */ - public setTracingEnabled(tracerConfig?: Partial): void { - // $end + public setTracingEnabled(tracerConfig?: Partial): void /* $ */ { if (tracerConfig?.consoleEnabled || tracerConfig?.httpEnabled) { Tracer.enableTracing("PolywrapClient", tracerConfig); } else { @@ -96,8 +93,7 @@ export class PolywrapCoreClient implements CoreClient { * @returns an array of interfaces and their registered implementations */ @Tracer.traceMethod("PolywrapClient: getInterfaces") - public getInterfaces(): readonly InterfaceImplementations[] | undefined { - // $end + public getInterfaces(): readonly InterfaceImplementations[] | undefined /* $ */ { // eslint-disable-line return this._config.interfaces; } @@ -108,8 +104,7 @@ export class PolywrapCoreClient implements CoreClient { * @returns an array of env objects containing wrapper environmental variables */ @Tracer.traceMethod("PolywrapClient: getEnvs") - public getEnvs(): readonly Env[] | undefined { - // $end + public getEnvs(): readonly Env[] | undefined /* $ */ { return this._config.envs; } @@ -120,8 +115,7 @@ export class PolywrapCoreClient implements CoreClient { * @returns an object that implements the IUriResolver interface */ @Tracer.traceMethod("PolywrapClient: getUriResolver") - public getResolver(): IUriResolver { - // $end + public getResolver(): IUriResolver /* $ */ { return this._config.resolver; } @@ -135,8 +129,7 @@ export class PolywrapCoreClient implements CoreClient { @Tracer.traceMethod("PolywrapClient: getEnvByUri") public getEnvByUri( uri: TUri - ): Env | undefined { - // $end + ): Env | undefined /* $ */ { const uriUri = Uri.from(uri); const envs = this.getEnvs(); @@ -157,8 +150,7 @@ export class PolywrapCoreClient implements CoreClient { @Tracer.traceMethod("PolywrapClient: getManifest") public async getManifest( uri: TUri - ): Promise> { - // $end + ): Promise> /* $ */ { const load = await this.loadWrapper(Uri.from(uri), undefined); if (!load.ok) { return load; @@ -181,8 +173,7 @@ export class PolywrapCoreClient implements CoreClient { public async getFile( uri: TUri, options: GetFileOptions - ): Promise> { - // $end + ): Promise> /* $ */ { const load = await this.loadWrapper(Uri.from(uri), undefined); if (!load.ok) { return load; @@ -205,8 +196,7 @@ export class PolywrapCoreClient implements CoreClient { public async getImplementations( uri: TUri, options: GetImplementationsOptions = {} - ): Promise> { - // $end + ): Promise> /* $ */ { const isUriTypeString = typeof uri === "string"; const applyResolution = !!options.applyResolution; @@ -262,8 +252,7 @@ export class PolywrapCoreClient implements CoreClient { TUri extends Uri | string = string >( options: InvokerOptions & { wrapper: Wrapper } - ): Promise> { - // $end + ): Promise> /* $ */ { try { const typedOptions: InvokeOptions = { ...options, @@ -324,8 +313,7 @@ export class PolywrapCoreClient implements CoreClient { @Tracer.traceMethod("PolywrapClient: invoke") public async invoke( options: InvokerOptions - ): Promise> { - // $end + ): Promise> /* $ */ { try { const typedOptions: InvokeOptions = { ...options, @@ -377,8 +365,7 @@ export class PolywrapCoreClient implements CoreClient { @Tracer.traceMethod("PolywrapClient: tryResolveUri", TracingLevel.High) public async tryResolveUri( options: TryResolveUriOptions - ): Promise> { - // $end + ): Promise> /* $ */ { const uri = Uri.from(options.uri); const uriResolver = this.getResolver(); @@ -422,8 +409,7 @@ export class PolywrapCoreClient implements CoreClient { uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions - ): Promise> { - // $end + ): Promise> /* $ */ { Tracer.setAttribute("label", `Wrapper loaded: ${uri}`, TracingLevel.High); if (!resolutionContext) { @@ -494,8 +480,7 @@ export class PolywrapCoreClient implements CoreClient { public async validate( uri: TUri, options: ValidateOptions - ): Promise> { - // $end + ): Promise> /* $ */ { const wrapper = await this.loadWrapper(Uri.from(uri)); if (!wrapper.ok) { return ResultErr(new Error(wrapper.error?.message)); diff --git a/packages/js/core/README.md b/packages/js/core/README.md index 95987f8aa2..2fd063433d 100644 --- a/packages/js/core/README.md +++ b/packages/js/core/README.md @@ -397,31 +397,31 @@ export class Uri { * * @param uri - a string representation of a wrap URI */ - constructor(uri: string) { + constructor(uri: string) ``` ##### authority ```ts /** @returns Uri authority */ - public get authority(): string { + public get authority(): string ``` ##### path ```ts /** @returns Uri path */ - public get path(): string { + public get path(): string ``` ##### uri ```ts /** @returns Uri string representation */ - public get uri(): string { + public get uri(): string ``` ##### equals ```ts /** Test two Uri instances for equality */ - public static equals(a: Uri, b: Uri): boolean { + public static equals(a: Uri, b: Uri): boolean ``` ##### isUri @@ -431,7 +431,7 @@ export class Uri { * * @param value - value to check * @returns true if value is a Uri instance */ - public static isUri(value: unknown): value is Uri { + public static isUri(value: unknown): value is Uri ``` ##### isValidUri @@ -442,19 +442,19 @@ export class Uri { * @param uri - URI string * @param parsed? - UriConfig to update (mutate) with content of URI string * @returns true if input string is a valid wrap URI */ - public static isValidUri(uri: string, parsed?: UriConfig): boolean { + public static isValidUri(uri: string, parsed?: UriConfig): boolean ``` ##### toString ```ts /** @returns Uri string representation */ - public toString(): string { + public toString(): string ``` ##### toJSON ```ts /** @returns Uri string representation */ - public toJSON(): string { + public toJSON(): string ``` ##### parseUri @@ -466,7 +466,7 @@ export class Uri { * @returns A Result containing a UriConfig, if successful, or an error */ @Tracer.traceMethod("Uri: parseUri") - public static parseUri(uri: string): Result { + public static parseUri(uri: string): Result ``` ##### from @@ -480,7 +480,7 @@ export class Uri { * @param uri - a Uri instance or a string representation of a wrap URI */ @Tracer.traceMethod("Uri: from") - public static from(uri: Uri | string): Uri { + public static from(uri: Uri | string): Uri ``` ### UriResolver @@ -580,7 +580,7 @@ export interface MaybeUriOrManifest { invoker: Invoker, wrapper: Uri, uri: Uri - ): Promise> => { + ): Promise> ``` #### getFile @@ -598,7 +598,7 @@ export interface MaybeUriOrManifest { invoker: Invoker, wrapper: Uri, path: string - ): Promise> => { + ): Promise> ``` ## Uri Resolution @@ -747,5 +747,5 @@ export class UriResolutionContext implements IUriResolutionContext { constructor( resolvingUriMap?: Map, resolutionPathOrHistory?: Set | IUriResolutionStep[] - ) { + ) ``` diff --git a/packages/js/core/package.json b/packages/js/core/package.json index ad969a7d82..143b698ee7 100644 --- a/packages/js/core/package.json +++ b/packages/js/core/package.json @@ -27,7 +27,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.1", + "doc-snippets": "^0.4.0-pre.4", "@types/jest": "26.0.8", "@types/mustache": "4.0.1", "@types/prettier": "2.6.0", diff --git a/packages/js/core/readme/config/final.json b/packages/js/core/readme/config/final.json index dd4994a2ec..611ddc1e3e 100644 --- a/packages/js/core/readme/config/final.json +++ b/packages/js/core/readme/config/final.json @@ -16,6 +16,26 @@ "dir": "./readme", "include": "./README.md" }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], "outputDir": "./" } } \ No newline at end of file diff --git a/packages/js/core/readme/config/sub-sections.json b/packages/js/core/readme/config/sub-sections.json index 3a50a30d2d..cfde3d90eb 100644 --- a/packages/js/core/readme/config/sub-sections.json +++ b/packages/js/core/readme/config/sub-sections.json @@ -13,6 +13,26 @@ "dir": "./readme/sub-sections/base", "include": "./**/*.md" }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], "outputDir": "./readme/sub-sections/injected" } } \ No newline at end of file diff --git a/packages/js/core/src/interfaces/uri-resolver.ts b/packages/js/core/src/interfaces/uri-resolver.ts index 229b0524bf..1e5546f1f0 100644 --- a/packages/js/core/src/interfaces/uri-resolver.ts +++ b/packages/js/core/src/interfaces/uri-resolver.ts @@ -14,7 +14,6 @@ export interface MaybeUriOrManifest { } // $end -/** */ export const module = { // $start: UriResolverInterface-tryResolveUri /** @@ -30,8 +29,7 @@ export const module = { invoker: Invoker, wrapper: Uri, uri: Uri - ): Promise> => { - // $end + ): Promise> /* $ */ => { return invoker.invoke({ uri: wrapper.uri, method: `tryResolveUri`, @@ -56,8 +54,7 @@ export const module = { invoker: Invoker, wrapper: Uri, path: string - ): Promise> => { - // $end + ): Promise> /* $ */ => { return invoker.invoke({ uri: wrapper.uri, method: "getFile", diff --git a/packages/js/core/src/types/Uri.ts b/packages/js/core/src/types/Uri.ts index ad86ac87d3..b1226264b4 100644 --- a/packages/js/core/src/types/Uri.ts +++ b/packages/js/core/src/types/Uri.ts @@ -35,22 +35,19 @@ export class Uri { // $start: Uri-authority /** @returns Uri authority */ - public get authority(): string { - // $end + public get authority(): string /* $ */ { return this._config.authority; } // $start: Uri-path /** @returns Uri path */ - public get path(): string { - // $end + public get path(): string /* $ */ { return this._config.path; } // $start: Uri-uri /** @returns Uri string representation */ - public get uri(): string { - // $end + public get uri(): string /* $ */ { return this._config.uri; } @@ -63,8 +60,7 @@ export class Uri { * * @param uri - a string representation of a wrap URI */ - constructor(uri: string) { - // $end + constructor(uri: string) /* $ */ { const result = Uri.parseUri(uri); if (!result.ok) { throw result.error; @@ -74,8 +70,7 @@ export class Uri { // $start: Uri-equals /** Test two Uri instances for equality */ - public static equals(a: Uri, b: Uri): boolean { - // $end + public static equals(a: Uri, b: Uri): boolean /* $ */ { return a.uri === b.uri; } @@ -85,8 +80,7 @@ export class Uri { * * @param value - value to check * @returns true if value is a Uri instance */ - public static isUri(value: unknown): value is Uri { - // $end + public static isUri(value: unknown): value is Uri /* $ */ { return typeof value === "object" && (value as Uri).uri !== undefined; } @@ -97,8 +91,7 @@ export class Uri { * @param uri - URI string * @param parsed? - UriConfig to update (mutate) with content of URI string * @returns true if input string is a valid wrap URI */ - public static isValidUri(uri: string, parsed?: UriConfig): boolean { - // $end + public static isValidUri(uri: string, parsed?: UriConfig): boolean /* $ */ { const result = Uri.parseUri(uri); if (parsed && result.ok) { @@ -110,15 +103,13 @@ export class Uri { // $start: Uri-toString /** @returns Uri string representation */ - public toString(): string { - // $end + public toString(): string /* $ */ { return this._config.uri; } // $start: Uri-toJSON /** @returns Uri string representation */ - public toJSON(): string { - // $end + public toJSON(): string /* $ */ { return this._config.uri; } @@ -130,8 +121,7 @@ export class Uri { * @returns A Result containing a UriConfig, if successful, or an error */ @Tracer.traceMethod("Uri: parseUri") - public static parseUri(uri: string): Result { - // $end + public static parseUri(uri: string): Result /* $ */ { if (!uri) { return ResultErr(Error("The provided URI is empty")); } @@ -195,8 +185,7 @@ export class Uri { * @param uri - a Uri instance or a string representation of a wrap URI */ @Tracer.traceMethod("Uri: from") - public static from(uri: Uri | string): Uri { - // $end + public static from(uri: Uri | string): Uri /* $ */ { if (typeof uri === "string") { return new Uri(uri); } else if (Uri.isUri(uri)) { diff --git a/packages/js/core/src/uri-resolution/UriResolutionContext.ts b/packages/js/core/src/uri-resolution/UriResolutionContext.ts index a15a79a457..c387d7eb0e 100644 --- a/packages/js/core/src/uri-resolution/UriResolutionContext.ts +++ b/packages/js/core/src/uri-resolution/UriResolutionContext.ts @@ -24,8 +24,7 @@ export class UriResolutionContext implements IUriResolutionContext { constructor( resolvingUriMap?: Map, resolutionPathOrHistory?: Set | IUriResolutionStep[] - ) { - // $end + ) /* $ */ { this.resolvingUriMap = resolvingUriMap ?? new Map(); if (Array.isArray(resolutionPathOrHistory)) { diff --git a/yarn.lock b/yarn.lock index 3a26f49c5d..910cbd1cad 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6988,10 +6988,10 @@ dns-txt@^2.0.2: dependencies: buffer-indexof "^1.0.0" -doc-snippets@^0.4.0-pre.1: - version "0.4.0-pre.1" - resolved "https://registry.yarnpkg.com/doc-snippets/-/doc-snippets-0.4.0-pre.1.tgz#50d41ad18d0a5a10bc49eade4073dd94dc32eb21" - integrity sha512-hKIkvzgd64Q6zEFNO+PEbsiLIQWvwMrmWnMhR22s0EsL4534H177K/ycyMZ90xnvLiFvckTHUUYXWAWN1ZEkRA== +doc-snippets@^0.4.0-pre.4: + version "0.4.0-pre.4" + resolved "https://registry.yarnpkg.com/doc-snippets/-/doc-snippets-0.4.0-pre.4.tgz#31b0c3ceaf0407049947aa190ef3ae0b52dd2032" + integrity sha512-QqUC5H+urFUAn+CnZg9YUgUhwRAEEc8CIoAqhlLUWFGxTxkdfnS0DCV3Oxd2Nl4vPd+KCj5Uk8m+hdDs5jMhPQ== dependencies: commander "^9.4.1" glob "^8.0.3" From e7a92b43e2a8a5d78063dbcb22ad5741cea3931b Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 10 Jan 2023 18:17:51 +0530 Subject: [PATCH 16/25] added doc comments and readme updates to test-env-js --- .../js/client-config-builder/package.json | 2 +- packages/js/client/package.json | 2 +- packages/js/core-client/package.json | 2 +- packages/js/core/package.json | 2 +- packages/js/test-env/README.md | 179 +++++++++++++++++- packages/js/test-env/package.json | 40 +++- packages/js/test-env/readme/README.md | 143 ++++++++++++++ packages/js/test-env/src/index.ts | 79 +++++++- yarn.lock | 8 +- 9 files changed, 440 insertions(+), 17 deletions(-) create mode 100644 packages/js/test-env/readme/README.md diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index 6bf0e9cf41..279737471f 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -20,7 +20,7 @@ "build:readme": "yarn doc-snippets combine" }, "dependencies": { - "doc-snippets": "^0.4.0-pre.4", + "doc-snippets": "^1.0.0", "@polywrap/core-js": "0.10.0-pre.6", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", diff --git a/packages/js/client/package.json b/packages/js/client/package.json index 02e41ab748..f1161ab153 100644 --- a/packages/js/client/package.json +++ b/packages/js/client/package.json @@ -33,7 +33,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.4", + "doc-snippets": "^1.0.0", "@polywrap/ens-resolver-plugin-js": "0.10.0-pre.6", "@polywrap/ethereum-plugin-js": "0.10.0-pre.6", "@polywrap/fs-plugin-js": "0.10.0-pre.6", diff --git a/packages/js/core-client/package.json b/packages/js/core-client/package.json index f4d04bb6a8..5ccbbc891b 100644 --- a/packages/js/core-client/package.json +++ b/packages/js/core-client/package.json @@ -25,7 +25,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.4", + "doc-snippets": "^1.0.0", "@polywrap/uri-resolvers-js": "0.10.0-pre.6", "@types/jest": "26.0.8", "@types/uuid": "8.3.0", diff --git a/packages/js/core/package.json b/packages/js/core/package.json index 143b698ee7..07afaa5ca7 100644 --- a/packages/js/core/package.json +++ b/packages/js/core/package.json @@ -27,7 +27,7 @@ "@polywrap/wrap-manifest-types-js": "0.10.0-pre.6" }, "devDependencies": { - "doc-snippets": "^0.4.0-pre.4", + "doc-snippets": "^1.0.0", "@types/jest": "26.0.8", "@types/mustache": "4.0.1", "@types/prettier": "2.6.0", diff --git a/packages/js/test-env/README.md b/packages/js/test-env/README.md index 85c5f5a609..ab9a17394d 100644 --- a/packages/js/test-env/README.md +++ b/packages/js/test-env/README.md @@ -58,11 +58,186 @@ export async function foo({ ``` -# API +# API Outline - ensAddresses, providers - constant addresses and urls - runCLI - run arbitrary Polywrap CLI commands -- initTestEnvironment - spin up Ganache and IPFS Docker instances +- initTestEnvironment - spin up Ganache and IPFS Docker instances - stopTestEnvironment - stop Docker - buildWrapper - compile wasm and bindings - buildAndDeployWrapper - deploy wrapper to the testnet ENS + +## Constants + +### providers + +```typescript +/** The URIs for the default providers used by the default infrastructure module. */ +export const providers = { + ipfs: "http://localhost:5001", + ethereum: "http://localhost:8545", + http: "http://localhost:3500", +}; +``` + +### ensAddresses + +```typescript +/** The Ethereum addresses of the default infrastructure module's locally-deployed ENS smart contracts. */ +export const ensAddresses = { + ensAddress: "0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab", + resolverAddress: "0x5b1869D9A4C187F2EAa108f3062412ecf0526b24", + registrarAddress: "0xD833215cBcc3f914bD1C9ece3EE7BF8B14f841bb", + reverseAddress: "0xe982E462b094850F12AF94d21D470e21bE9D0E9C", +} as const; +``` + +### embeddedWrappers + +```typescript +/** Wasm wrappers embedded in the package */ +export const embeddedWrappers = { + ens: `wrap://fs/${path.join(__dirname, "wrappers", "ens")}`, + uts46: `wrap://fs/${path.join(__dirname, "wrappers", "uts46")}`, + sha3: `wrap://fs/${path.join(__dirname, "wrappers", "sha3")}`, +}; +``` + +## Methods + +### initTestEnvironment + +```typescript +/** + * Starts a local test environment using the default infrastructure module. + * + * @param cli? - a path to a Polywrap CLI binary. + */ +export const initTestEnvironment = async ( + cli?: string +): Promise +``` + +### stopTestEnvironment + +```typescript +/** + * Stops the local test environment (default infrastructure module) if one is running. + * + * @param cli? - a path to a Polywrap CLI binary. + */ +export const stopTestEnvironment = async ( + cli?: string +): Promise +``` + +### buildWrapper + +```typescript +/** + * Build the wrapper located at the given path + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param manifestPathOverride? - path to p + */ +export async function buildWrapper( + wrapperAbsPath: string, + manifestPathOverride?: string +): Promise +``` + +### buildAndDeployWrapper + +```typescript +/** + * Build the wrapper located at the given path, and then deploy it to IPFS and ENS. + * If an ENS domain is not provided, a randomly selected human-readable ENS domain name is used. + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param ipfsProvider - ipfs provider to use for deployment + * @param ethereumProvider - ethereum provider to use for ENS registration + * @param ensName? - an ENS domain name to register and assign to the wrapper + * + * @returns registered ens domain name and IPFS hash + */ +export async function buildAndDeployWrapper({ + wrapperAbsPath, + ipfsProvider, + ethereumProvider, + ensName, +}: { + wrapperAbsPath: string; + ipfsProvider: string; + ethereumProvider: string; + ensName?: string; +}): Promise<{ + ensDomain: string; + ipfsCid: string; +}> +``` + +```typescript title="Example: buildAndDeployWrapper with default infrastructure module" +import { buildAndDeployWrapper, providers } from "@polywrap/test-env-js"; + +const { ensDomain, ipfsCid } = await buildAndDeployWrapper({ + wrapperAbsPath: "...", + ipfsProvider: providers.ipfs, + ethereumProvider: providers.ethereum, +}); +const ensUri = `ens/testnet/${ensDomain}`; +``` + +### buildAndDeployWrapperToHttp + +```typescript +/** + * Build the wrapper located at the given path, and then deploy it to HTTP. + * If a domain name is not provided, a randomly selected human-readable domain name is used. + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param httpProvider - http provider used for deployment and domain registration + * @param name? - a domain name to register and assign to the wrapper + * + * @returns http uri + */ +export async function buildAndDeployWrapperToHttp({ + wrapperAbsPath, + httpProvider, + name, +}: { + wrapperAbsPath: string; + httpProvider: string; + name?: string; +}): Promise<{ uri: string }> +``` + +### runCLI + +```typescript +/** + * Runs the polywrap CLI programmatically. + * + * @param args - an array of command line arguments + * @param cwd? - a current working directory + * @param cli? - a path to a Polywrap CLI binary + * @param env? - a map of environmental variables + * + * @returns exit code, standard output, and standard error logs + */ +export const runCLI = async (options: { + args: string[]; + cwd?: string; + cli?: string; + env?: Record; +}): Promise<{ + exitCode: number; + stdout: string; + stderr: string; +}> +``` + +```typescript title="Example: runCLI calling the 'infra' command" +const { exitCode, stderr, stdout } = await runCLI({ + args: ["infra", "up", "--modules=eth-ens-ipfs", "--verbose"] +}); +``` \ No newline at end of file diff --git a/packages/js/test-env/package.json b/packages/js/test-env/package.json index 1ee8b9664d..a6a3b75751 100644 --- a/packages/js/test-env/package.json +++ b/packages/js/test-env/package.json @@ -14,7 +14,8 @@ "scripts": { "build": "rimraf ./build && tsc --project tsconfig.build.json && yarn copy:wrappers", "lint": "eslint --color -c ../../../.eslintrc.js src/", - "copy:wrappers": "copyfiles ./src/wrappers/**/**/* ./build/wrappers/ -u 2" + "copy:wrappers": "copyfiles ./src/wrappers/**/**/* ./build/wrappers/ -u 2", + "build:readme": "yarn doc-snippets combine" }, "dependencies": { "@polywrap/core-js": "0.10.0-pre.6", @@ -24,6 +25,7 @@ "yaml": "2.1.3" }, "devDependencies": { + "doc-snippets": "^1.0.0", "copyfiles": "2.4.1", "rimraf": "3.0.2", "ts-node": "8.10.2", @@ -32,5 +34,41 @@ "gitHead": "7346adaf5adb7e6bbb70d9247583e995650d390a", "publishConfig": { "access": "public" + }, + "doc-snippets": { + "extract": { + "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "ignore": [ + "./**/node_modules/**", + "./**/.polywrap/**", + "./**/__tests__/**" + ], + "dir": "./src" + }, + "inject": { + "dir": "./readme", + "include": "./README.md" + }, + "startTokens": [ + { + "pattern": "$start: ", + "inline": false + }, + { + "pattern": "/* $: {SNIPPET_NAME} */", + "inline": true + } + ], + "endTokens": [ + { + "pattern": "$end", + "inline": false + }, + { + "pattern": "/* $ */", + "inline": true + } + ], + "outputDir": "./" } } diff --git a/packages/js/test-env/readme/README.md b/packages/js/test-env/readme/README.md new file mode 100644 index 0000000000..f73e87054f --- /dev/null +++ b/packages/js/test-env/readme/README.md @@ -0,0 +1,143 @@ +# @polywrap/test-env-js + +Provides functions to setup a test environment with Polywrap CLI and Docker. + +# Description + +It allows user to initiate the test environment through a javascript function (it's the `infra` command in the CLI). It also exports the providers and ens addresses expected in the deployments (They are hard coded, because the initiation of the environment is deterministic) + +# Usage + +Initialization with the simple-storage wrapper. + +``` typescript +import path from "path"; +import { PolywrapClient } from "@polywrap/client-js"; +import { + buildWrapper, + initTestEnvironment, + stopTestEnvironment, + providers, + ensAddresses +} from "@polywrap/test-env-js"; +import * as App from "../types/wrap"; + +// test wrapper in a test environment +export async function foo({ + // spin up docker containers for Ganache and IPFS. + await initTestEnvironment(); + const CONNECTION = { networkNameOrChainId: "testnet" }; + + // get path to the wrapper in testing + const wrapperPath: string = path.join(path.resolve(__dirname), ".."); + + // build current wrapper with CLI + await buildWrapper(wrapperPath); + + // get URI to the local wrapper build + const wrapperUri = `fs/${wrapperPath}/build`; + + // invoke the wrapper to deploy a contract to the test env + const deployContractResponse = await App.SimpleStorage_Module.deployContract( + { connection: CONNECTION }, + client, + wrapperUri + ); + const contractAddress = deployContractResponse.data as string; + + // invoke the wrapper to query a contract in the test env + const response = await App.SimpleStorage_Module.getData( + { + address: contractAddr, + connection: CONNECTION, + }, + client, + wrapperUri + ); +}); + +``` + +# API Outline + +- ensAddresses, providers - constant addresses and urls +- runCLI - run arbitrary Polywrap CLI commands +- initTestEnvironment - spin up Ganache and IPFS Docker instances +- stopTestEnvironment - stop Docker +- buildWrapper - compile wasm and bindings +- buildAndDeployWrapper - deploy wrapper to the testnet ENS + +## Constants + +### providers + +```typescript +$snippet: providers +``` + +### ensAddresses + +```typescript +$snippet: ensAddresses +``` + +### embeddedWrappers + +```typescript +$snippet: embeddedWrappers +``` + +## Methods + +### initTestEnvironment + +```typescript +$snippet: initTestEnvironment +``` + +### stopTestEnvironment + +```typescript +$snippet: stopTestEnvironment +``` + +### buildWrapper + +```typescript +$snippet: buildWrapper +``` + +### buildAndDeployWrapper + +```typescript +$snippet: buildAndDeployWrapper +``` + +```typescript title="Example: buildAndDeployWrapper with default infrastructure module" +import { buildAndDeployWrapper, providers } from "@polywrap/test-env-js"; + +const { ensDomain, ipfsCid } = await buildAndDeployWrapper({ + wrapperAbsPath: "...", + ipfsProvider: providers.ipfs, + ethereumProvider: providers.ethereum, +}); +const ensUri = `ens/testnet/${ensDomain}`; +``` + +### buildAndDeployWrapperToHttp + +```typescript +$snippet: buildAndDeployWrapperToHttp +``` + +### runCLI + +```typescript +$snippet: runCLI +``` + +```typescript title="Example: runCLI calling the 'infra' command" +const { exitCode, stderr, stdout } = await runCLI({ + args: ["infra", "up", "--modules=eth-ens-ipfs", "--verbose"] +}); +``` \ No newline at end of file diff --git a/packages/js/test-env/src/index.ts b/packages/js/test-env/src/index.ts index 1ca2f6a320..43e0f64a27 100644 --- a/packages/js/test-env/src/index.ts +++ b/packages/js/test-env/src/index.ts @@ -12,24 +12,33 @@ import { deserializePolywrapManifest, } from "@polywrap/polywrap-manifest-types-js"; +// $start: ensAddresses +/** The Ethereum addresses of the default infrastructure module's locally-deployed ENS smart contracts. */ export const ensAddresses = { ensAddress: "0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab", resolverAddress: "0x5b1869D9A4C187F2EAa108f3062412ecf0526b24", registrarAddress: "0xD833215cBcc3f914bD1C9ece3EE7BF8B14f841bb", reverseAddress: "0xe982E462b094850F12AF94d21D470e21bE9D0E9C", } as const; +// $end +// $start: providers +/** The URIs for the default providers used by the default infrastructure module. */ export const providers = { ipfs: "http://localhost:5001", ethereum: "http://localhost:8545", http: "http://localhost:3500", }; +// $end +// $start: embeddedWrappers +/** Wasm wrappers embedded in the package */ export const embeddedWrappers = { ens: `wrap://fs/${path.join(__dirname, "wrappers", "ens")}`, uts46: `wrap://fs/${path.join(__dirname, "wrappers", "uts46")}`, sha3: `wrap://fs/${path.join(__dirname, "wrappers", "sha3")}`, }; +// $end: embeddedWrappers const monorepoCli = `${__dirname}/../../../cli/bin/polywrap`; const npmCli = `${__dirname}/../../../polywrap/bin/polywrap`; @@ -69,7 +78,15 @@ async function awaitResponse( return false; } -export const initTestEnvironment = async (cli?: string): Promise => { +// $start: initTestEnvironment +/** + * Starts a local test environment using the default infrastructure module. + * + * @param cli? - a path to a Polywrap CLI binary. + */ +export const initTestEnvironment = async ( + cli?: string +): Promise /* $ */ => { // Start the test environment const { exitCode, stderr, stdout } = await runCLI({ args: ["infra", "up", "--modules=eth-ens-ipfs", "--verbose"], @@ -127,7 +144,15 @@ export const initTestEnvironment = async (cli?: string): Promise => { } }; -export const stopTestEnvironment = async (cli?: string): Promise => { +// $start: stopTestEnvironment +/** + * Stops the local test environment (default infrastructure module) if one is running. + * + * @param cli? - a path to a Polywrap CLI binary. + */ +export const stopTestEnvironment = async ( + cli?: string +): Promise /* $ */ => { // Stop the test environment const { exitCode, stderr } = await runCLI({ args: ["infra", "down", "--modules=eth-ens-ipfs"], @@ -143,6 +168,18 @@ export const stopTestEnvironment = async (cli?: string): Promise => { return Promise.resolve(); }; +// $start: runCLI +/** + * Runs the polywrap CLI programmatically. + * + * @param options - an object containing: + * args - an array of command line arguments + * cwd? - a current working directory + * cli? - a path to a Polywrap CLI binary + * env? - a map of environmental variables + * + * @returns exit code, standard output, and standard error logs + */ export const runCLI = async (options: { args: string[]; cwd?: string; @@ -152,7 +189,7 @@ export const runCLI = async (options: { exitCode: number; stdout: string; stderr: string; -}> => { +}> /* $ */ => { const [exitCode, stdout, stderr] = await new Promise((resolve, reject) => { if (!options.cwd) { // Make sure to set an absolute working directory @@ -201,10 +238,17 @@ export const runCLI = async (options: { }; }; +// $start: buildWrapper +/** + * Build the wrapper located at the given path + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param manifestPathOverride? - path to p + */ export async function buildWrapper( wrapperAbsPath: string, manifestPathOverride?: string -): Promise { +): Promise /* $ */ { const manifestPath = manifestPathOverride ? path.join(wrapperAbsPath, manifestPathOverride) : `${wrapperAbsPath}/polywrap.yaml`; @@ -230,6 +274,18 @@ export async function buildWrapper( } } +// $start: buildAndDeployWrapper +/** + * Build the wrapper located at the given path, and then deploy it to IPFS and ENS. + * If an ENS domain is not provided, a randomly selected human-readable ENS domain name is used. + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param ipfsProvider - ipfs provider to use for deployment + * @param ethereumProvider - ethereum provider to use for ENS registration + * @param ensName? - an ENS domain name to register and assign to the wrapper + * + * @returns registered ens domain name and IPFS hash + */ export async function buildAndDeployWrapper({ wrapperAbsPath, ipfsProvider, @@ -243,7 +299,7 @@ export async function buildAndDeployWrapper({ }): Promise<{ ensDomain: string; ipfsCid: string; -}> { +}> /* $ */ { const manifestPath = `${wrapperAbsPath}/polywrap.yaml`; const tempManifestFilename = `polywrap-temp.yaml`; const tempDeployManifestFilename = `polywrap.deploy-temp.yaml`; @@ -359,6 +415,17 @@ export async function buildAndDeployWrapper({ }; } +// $start: buildAndDeployWrapperToHttp +/** + * Build the wrapper located at the given path, and then deploy it to HTTP. + * If a domain name is not provided, a randomly selected human-readable domain name is used. + * + * @param wrapperAbsPath - absolute path of wrapper to build + * @param httpProvider - http provider used for deployment and domain registration + * @param name? - a domain name to register and assign to the wrapper + * + * @returns http uri + */ export async function buildAndDeployWrapperToHttp({ wrapperAbsPath, httpProvider, @@ -367,7 +434,7 @@ export async function buildAndDeployWrapperToHttp({ wrapperAbsPath: string; httpProvider: string; name?: string; -}): Promise<{ uri: string }> { +}): Promise<{ uri: string }> /* $ */ { const manifestPath = `${wrapperAbsPath}/polywrap.yaml`; const tempManifestFilename = `polywrap-temp.yaml`; const tempDeployManifestFilename = `polywrap.deploy-temp.yaml`; diff --git a/yarn.lock b/yarn.lock index 910cbd1cad..0df91ddc4c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6988,10 +6988,10 @@ dns-txt@^2.0.2: dependencies: buffer-indexof "^1.0.0" -doc-snippets@^0.4.0-pre.4: - version "0.4.0-pre.4" - resolved "https://registry.yarnpkg.com/doc-snippets/-/doc-snippets-0.4.0-pre.4.tgz#31b0c3ceaf0407049947aa190ef3ae0b52dd2032" - integrity sha512-QqUC5H+urFUAn+CnZg9YUgUhwRAEEc8CIoAqhlLUWFGxTxkdfnS0DCV3Oxd2Nl4vPd+KCj5Uk8m+hdDs5jMhPQ== +doc-snippets@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/doc-snippets/-/doc-snippets-1.0.0.tgz#5921d52c6cfe6de0ab9b28f9594232cb6876c37e" + integrity sha512-4wVSd7jxhliPvqZ3sdhKhRla/EYy6DKlflWYd+E7JTGYXy1xBWyMnbSkWshGUiVK8TgZAF45iE4Y6eSo5F2lqg== dependencies: commander "^9.4.1" glob "^8.0.3" From 6cae2eb05a1c2c8424466979f5c0ae7a3743a0a3 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 10 Jan 2023 19:18:51 +0530 Subject: [PATCH 17/25] merge conflict fix --- .../client-config-builder/src/bundles/getDefaultConfig.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts b/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts index 7265cbf2af..9bee88c2b2 100644 --- a/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts +++ b/packages/js/client-config-builder/src/bundles/getDefaultConfig.ts @@ -16,6 +16,8 @@ import { loggerPlugin } from "@polywrap/logger-plugin-js"; import { fileSystemResolverPlugin } from "@polywrap/fs-resolver-plugin-js"; import { concurrentPromisePlugin } from "concurrent-plugin-js"; +// $start: getDefaultConfig + export const defaultIpfsProviders = [ "https://ipfs.wrappers.io", "https://ipfs.io", @@ -48,7 +50,6 @@ export const defaultInterfaces = { logger: "wrap://ens/wrappers.polywrap.eth:logger@1.0.0", }; -// $start: getDefaultConfig export const getDefaultConfig = (): ClientConfig => { return { envs: [ @@ -109,7 +110,6 @@ export const getDefaultConfig = (): ClientConfig => { resolvers: [], }; }; -// $end export const getDefaultPlugins = (): IUriPackage[] => { return [ @@ -171,3 +171,5 @@ export const getDefaultPlugins = (): IUriPackage[] => { }, ]; }; + +// $end From 8df2fc935b80ee5b6811ba46f643df1dd90d63bf Mon Sep 17 00:00:00 2001 From: krisbitney Date: Tue, 10 Jan 2023 23:07:56 +0530 Subject: [PATCH 18/25] fixed typo made when resolving merge conflicts --- packages/js/core-client/src/PolywrapCoreClient.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/js/core-client/src/PolywrapCoreClient.ts b/packages/js/core-client/src/PolywrapCoreClient.ts index 231e489f32..d394fac416 100644 --- a/packages/js/core-client/src/PolywrapCoreClient.ts +++ b/packages/js/core-client/src/PolywrapCoreClient.ts @@ -418,7 +418,7 @@ export class PolywrapCoreClient implements CoreClient { uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions - ): Promise> /* $ */ { + ): Promise> /* $ */ { Tracer.setAttribute("label", `Wrapper loaded: ${uri}`, TracingLevel.High); if (!resolutionContext) { From 1b8ca785573c3cece381ba5ee6e63aa24940191d Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 18:49:45 +0530 Subject: [PATCH 19/25] fixed typo in client config builder constructor snippet extraction; added "build:readme" to build scripts and added "build:fast" options; added "Reference" section headers to readmes --- .../js/client-config-builder/package.json | 3 +- .../js/client-config-builder/readme/README.md | 2 + .../src/ClientConfigBuilder.ts | 3 +- packages/js/client/package.json | 5 +- packages/js/client/readme/README.md | 2 + packages/js/core-client/package.json | 3 +- packages/js/core-client/readme/README.md | 2 + packages/js/core/package.json | 3 +- packages/js/core/readme/README.md | 2 + yarn.lock | 217 ++++++++++++++++++ 10 files changed, 236 insertions(+), 6 deletions(-) diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index a1b30a2af4..b94c63efdb 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -12,7 +12,8 @@ "build" ], "scripts": { - "build": "rimraf ./build && tsc --project tsconfig.build.json", + "build": "yarn build:fast && yarn build:readme", + "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose", "test:ci": "jest --passWithNoTests --runInBand --verbose", diff --git a/packages/js/client-config-builder/readme/README.md b/packages/js/client-config-builder/readme/README.md index 9533163267..1a0e6bfad0 100644 --- a/packages/js/client-config-builder/readme/README.md +++ b/packages/js/client-config-builder/readme/README.md @@ -42,6 +42,8 @@ const config = builder.build(); let client = new PolywrapClient(config); ``` +# Reference + ## Types ```ts diff --git a/packages/js/client-config-builder/src/ClientConfigBuilder.ts b/packages/js/client-config-builder/src/ClientConfigBuilder.ts index e243503412..4938f946a9 100644 --- a/packages/js/client-config-builder/src/ClientConfigBuilder.ts +++ b/packages/js/client-config-builder/src/ClientConfigBuilder.ts @@ -12,7 +12,8 @@ import { import { ExtendableUriResolver } from "@polywrap/uri-resolver-extensions-js"; export class ClientConfigBuilder extends BaseClientConfigBuilder { - /* $start: ClientConfigBuilder-constructor */ /** + // $start: ClientConfigBuilder-constructor + /** * Instantiate a ClientConfigBuilder * * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache diff --git a/packages/js/client/package.json b/packages/js/client/package.json index 4e4cf43d91..26fe89f15c 100644 --- a/packages/js/client/package.json +++ b/packages/js/client/package.json @@ -12,7 +12,8 @@ "build" ], "scripts": { - "build": "rimraf ./build && tsc --project tsconfig.build.json", + "build": "yarn build:fast && yarn build:readme", + "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", "test:ci": "jest --passWithNoTests --runInBand --verbose --detectOpenHandles --forceExit", @@ -41,7 +42,7 @@ "@polywrap/http-resolver-plugin-js": "0.10.0-pre.7", "@polywrap/ipfs-plugin-js": "0.10.0-pre.7", "@polywrap/ipfs-resolver-plugin-js": "0.10.0-pre.7", - "@polywrap/plugin-js": "0.10.0-pre.6", + "@polywrap/plugin-js": "0.10.0-pre.7", "@polywrap/test-cases": "0.10.0-pre.7", "@polywrap/test-env-js": "0.10.0-pre.7", "@types/jest": "26.0.8", diff --git a/packages/js/client/readme/README.md b/packages/js/client/readme/README.md index e90e185184..11ba112ef3 100644 --- a/packages/js/client/readme/README.md +++ b/packages/js/client/readme/README.md @@ -104,6 +104,8 @@ const client = new PolywrapClient(config); const altClient = new PolywrapClient(config, { noDefaults: true }); ``` +# Reference + ## Types ```ts diff --git a/packages/js/core-client/package.json b/packages/js/core-client/package.json index 2456e2b4f0..d797c18c6f 100644 --- a/packages/js/core-client/package.json +++ b/packages/js/core-client/package.json @@ -12,7 +12,8 @@ "build" ], "scripts": { - "build": "rimraf ./build && tsc --project tsconfig.build.json", + "build": "yarn build:fast && yarn build:readme", + "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", "build:readme": "yarn doc-snippets combine" diff --git a/packages/js/core-client/readme/README.md b/packages/js/core-client/readme/README.md index 568a52e164..1ed9d5bed5 100644 --- a/packages/js/core-client/readme/README.md +++ b/packages/js/core-client/readme/README.md @@ -82,6 +82,8 @@ const config = { const client = new PolywrapCoreClient(config); ``` +# Reference + ## Types ```ts diff --git a/packages/js/core/package.json b/packages/js/core/package.json index 6384ec95e8..777cdfbd46 100644 --- a/packages/js/core/package.json +++ b/packages/js/core/package.json @@ -12,7 +12,8 @@ "build" ], "scripts": { - "build": "rimraf ./build && tsc --project tsconfig.build.json", + "build": "yarn build:fast && yarn build:readme", + "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose", "test:ci": "jest --passWithNoTests --runInBand --verbose", diff --git a/packages/js/core/readme/README.md b/packages/js/core/readme/README.md index 0644c3e0af..27479ac1c0 100644 --- a/packages/js/core/readme/README.md +++ b/packages/js/core/readme/README.md @@ -2,6 +2,8 @@ A TypeScript / JavaScript implementation of the WRAP standard, including all fundamental types & algorithms. +# Reference + ## Types ### CoreClient diff --git a/yarn.lock b/yarn.lock index 4433ec8f81..aeb41a73bf 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3288,6 +3288,57 @@ resolved "https://registry.yarnpkg.com/@opentelemetry/semantic-conventions/-/semantic-conventions-1.6.0.tgz#ed410c9eb0070491cff9fe914246ce41f88d6f74" integrity sha512-aPfcBeLErM/PPiAuAbNFLN5sNbZLc3KZlar27uohllN8Zs6jJbHyJU1y7cMA6W/zuq+thkaG8mujiS+3iD/FWQ== +"@polywrap/asyncify-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/asyncify-js/-/asyncify-js-0.10.0-pre.6.tgz#6f756bc2456da6df095652dd61b19fc4fc5a39af" + integrity sha512-dC/W7o1KpQLlag2ojoyHYFuUjuD2VGrMcW4PFJsXmXtMsNu1N9kzOEQsnVKF+oi6MPQB3rDkdkZ2x/RIs5hqzg== + +"@polywrap/client-config-builder-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/client-config-builder-js/-/client-config-builder-js-0.10.0-pre.6.tgz#1e24ed932c86531b77836c5d948a22374a78e9f2" + integrity sha512-qZaJN5RkOTT7+QRh9AWEYDr6zLpK6fVCprb8DXNnBB5NIiJ6TcdyUx6mp/aJrFSI7a8/6j0aVb8j6YPownl7yw== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/ens-resolver-plugin-js" "0.10.0-pre.6" + "@polywrap/ethereum-plugin-js" "0.10.0-pre.6" + "@polywrap/fs-plugin-js" "0.10.0-pre.6" + "@polywrap/fs-resolver-plugin-js" "0.10.0-pre.6" + "@polywrap/http-plugin-js" "0.10.0-pre.6" + "@polywrap/http-resolver-plugin-js" "0.10.0-pre.6" + "@polywrap/ipfs-plugin-js" "0.10.0-pre.6" + "@polywrap/ipfs-resolver-plugin-js" "0.10.0-pre.6" + "@polywrap/logger-plugin-js" "0.10.0" + "@polywrap/uri-resolver-extensions-js" "0.10.0-pre.6" + "@polywrap/uri-resolvers-js" "0.10.0-pre.6" + concurrent-plugin-js "0.1.1" + +"@polywrap/client-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/client-js/-/client-js-0.10.0-pre.6.tgz#560f9dcc860142d3b00beaf9518159acb5df940f" + integrity sha512-HMRRqL5M5QsUeYathJHTqE656IKu4xikQCNxZufJd6ZqTx+7cKeExtfhaGteMVo9SE7AuCl5wcL2rmw24PE5Ew== + dependencies: + "@polywrap/client-config-builder-js" "0.10.0-pre.6" + "@polywrap/core-client-js" "0.10.0-pre.6" + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/msgpack-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/tracing-js" "0.10.0-pre.6" + "@polywrap/uri-resolver-extensions-js" "0.10.0-pre.6" + "@polywrap/uri-resolvers-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + +"@polywrap/core-client-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/core-client-js/-/core-client-js-0.10.0-pre.6.tgz#5d56c630c7c5b0273aa27b4fc9024f5cb24bd0b4" + integrity sha512-+RqHTq3cFNVAGrh/Yk1+8ZRvhakDV2x8A9ZcMRtugRubZktKc7N4WRhc9OMiIORBxts072BdQRmVGKk/BXV4xQ== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/msgpack-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/tracing-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + "@polywrap/core-js@0.10.0-pre.5": version "0.10.0-pre.5" resolved "https://registry.yarnpkg.com/@polywrap/core-js/-/core-js-0.10.0-pre.5.tgz#8457f168235faae19342a87aed6ddce44a56fb59" @@ -3299,6 +3350,73 @@ graphql "15.5.0" graphql-tag "2.10.4" +"@polywrap/core-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/core-js/-/core-js-0.10.0-pre.6.tgz#7751267b8472473bf3774d441fd75ebe348685e3" + integrity sha512-JP9qk0gS1r1fyRqe2Wp/3tzyDEn3DqeVSC+53aBNEk8uMLIJSUI184JXusVNVafwbLgMxOcJ6vZlhb0x5orrWQ== + dependencies: + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/tracing-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + graphql "15.5.0" + graphql-tag "2.10.4" + +"@polywrap/ens-resolver-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/ens-resolver-plugin-js/-/ens-resolver-plugin-js-0.10.0-pre.6.tgz#bebd73f8a1221f8fc78f100d1d1be4cfae999572" + integrity sha512-24QsSaQwVwY30/KKqVxeNIOnrGxeAPo/TOeeWGB8sBxMxhwXArm/L0ldN7Bgr3H4OYjtyRY2qqx1UHyK8ty97w== + dependencies: + "@ethersproject/address" "5.0.7" + "@ethersproject/basex" "5.0.7" + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + ethers "5.0.7" + +"@polywrap/ethereum-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/ethereum-plugin-js/-/ethereum-plugin-js-0.10.0-pre.6.tgz#a7652e518829543512bed44ce956fea9ae9646b7" + integrity sha512-tIhYCg1kZvL50dHFFgv8SUVYvGUo2rDW9Ge8pLuLJnY9uIsBzv4ZqBsyTG6VKTb03RpxI4Y6gEGGNc4u10xQvw== + dependencies: + "@ethersproject/address" "5.0.7" + "@ethersproject/providers" "5.0.7" + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + ethers "5.0.7" + +"@polywrap/fs-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/fs-plugin-js/-/fs-plugin-js-0.10.0-pre.6.tgz#f0277875e0273abdccf0f1e851848527997b7733" + integrity sha512-UvEkSw6mD/JTExwaGWxJ3byfxJBR3lFebLVrYEEscoMe0el0dHseO/PJuhP+Kih7AdRo5zbsNvG+KIqKobI5qg== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + +"@polywrap/fs-resolver-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/fs-resolver-plugin-js/-/fs-resolver-plugin-js-0.10.0-pre.6.tgz#94b48d2eb87d940a2b1cf5822b3b6cc8ca7f606c" + integrity sha512-oXRO/9X0NtXwor4QFzQxFJfkbuoVG5mCW2BgMPwtxihXvmJow6bvsSz95Uhy6c4bKmoHHYo/ORLbsAi/Gg5JTA== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + +"@polywrap/http-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/http-plugin-js/-/http-plugin-js-0.10.0-pre.6.tgz#331be6aec3249c90e355078f49e37d0e187b0d0f" + integrity sha512-6osndYNTcypf8dAi0BHi/4IixSxq2Ti3zgJedRYSwdxjE0uJGQWPSlm+dQlmzI4vYWmXhDpxETpvXizpoOfLMQ== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + axios "0.21.4" + +"@polywrap/http-resolver-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/http-resolver-plugin-js/-/http-resolver-plugin-js-0.10.0-pre.6.tgz#4b5c6a60a814f3900ef9cba60d6d302c41669a4d" + integrity sha512-Y0VLQ3PuCtfe0+1YlsTFRj8DL67K0HcFwaWvYQ0RfMM0iV2B3riQHk0VjrFoEXlU+qSmuG5lsj56IcGF1kuMLQ== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/plugin-js" "0.10.0-pre.6" + abort-controller "3.0.0" + "@polywrap/ipfs-http-client-lite@0.3.0": version "0.3.0" resolved "https://registry.yarnpkg.com/@polywrap/ipfs-http-client-lite/-/ipfs-http-client-lite-0.3.0.tgz#b8caf4b4f39413e591aff4367023a04cb6df83a1" @@ -3315,6 +3433,29 @@ pull-stream-to-async-iterator "^1.0.2" querystring "^0.2.0" +"@polywrap/ipfs-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/ipfs-plugin-js/-/ipfs-plugin-js-0.10.0-pre.6.tgz#a3f19eeff44279202525b998ea4a1b6b1002aacc" + integrity sha512-7J6ejZr9Y7RZJkQjQaMt3zAYr1FzrNOeYt7oD/EZBix0fbzxTLz2ZTIhRyU3M0yaTv8uETi4z3IZrXZmqEl1EQ== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/ipfs-http-client-lite" "0.3.0" + "@polywrap/plugin-js" "0.10.0-pre.6" + abort-controller "3.0.0" + is-ipfs "1.0.3" + multiformats "9.7.0" + +"@polywrap/ipfs-resolver-plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/ipfs-resolver-plugin-js/-/ipfs-resolver-plugin-js-0.10.0-pre.6.tgz#9a261e3973d0ef84b5fe230fcfd65a0d09618148" + integrity sha512-w3iovKnbDv5MHVc6aBkdoj7M90EBMB0B4N1WF7inPS+yJp6sKGQGNf0po3inQ8VZam7m0n1Bj9T6CWURoV/CIQ== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/ipfs-http-client-lite" "0.3.0" + "@polywrap/plugin-js" "0.10.0-pre.6" + abort-controller "3.0.0" + is-ipfs "1.0.3" + "@polywrap/logger-plugin-js@0.10.0": version "0.10.0" resolved "https://registry.yarnpkg.com/@polywrap/logger-plugin-js/-/logger-plugin-js-0.10.0.tgz#9fc10532e86642d7e8eb3fc7a34494cb077610bd" @@ -3330,6 +3471,13 @@ dependencies: "@msgpack/msgpack" "2.7.2" +"@polywrap/msgpack-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/msgpack-js/-/msgpack-js-0.10.0-pre.6.tgz#22f884cbadc959c685851f0981b4616d28f106ff" + integrity sha512-RlUAh/6IKAnDdEDxDwWCzwQswd3DU7JUaD0PpWok45BemxBTNmLMcSkKKlK8zXntVHGR/9E8UqadsDjQDxgEUg== + dependencies: + "@msgpack/msgpack" "2.7.2" + "@polywrap/plugin-js@0.10.0-pre.5": version "0.10.0-pre.5" resolved "https://registry.yarnpkg.com/@polywrap/plugin-js/-/plugin-js-0.10.0-pre.5.tgz#5bd416cb7f52f001144222e5bc83d1e94ff23cb4" @@ -3341,6 +3489,17 @@ "@polywrap/tracing-js" "0.10.0-pre.5" "@polywrap/wrap-manifest-types-js" "0.10.0-pre.5" +"@polywrap/plugin-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/plugin-js/-/plugin-js-0.10.0-pre.6.tgz#ab51539d3ece260aebb028edf6cb4e57504a031d" + integrity sha512-7lxNwv3btb4KsA4ol0lC381YPZLdqAnjQTOa3FiGGYdlpFs8gB0FUTcIZZ2xrROCksliDEuX5Mt8Y8J2X8q9gA== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/msgpack-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/tracing-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + "@polywrap/react@0.10.0-pre.6": version "0.10.0-pre.6" resolved "https://registry.yarnpkg.com/@polywrap/react/-/react-0.10.0-pre.6.tgz#10bc4aedb0d3ff21ff3dc8100bedaaae06d1c3b4" @@ -3355,6 +3514,11 @@ resolved "https://registry.yarnpkg.com/@polywrap/result/-/result-0.10.0-pre.5.tgz#b703878cf7426dee0edc1a2649f79a06153b403e" integrity sha512-5ATKBdqSS/qmSfJDrQBBq4d34b3Al381bJWJ8nWlcyt8ybo2CqHwQuv/dD02elmhS2G3EK/p/sZCbD1st8CZYw== +"@polywrap/result@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/result/-/result-0.10.0-pre.6.tgz#ec5fbe2f8a828bd586c67d9243b4a46e8f42e423" + integrity sha512-IQeaS/4Wdbl+TI59J0+WOpRUQWY7F85QwfRLEH2hZnbMKaCuJB1ski9/0D4soEDiTGF5+PY9rQCB/nNrj5rYJg== + "@polywrap/tracing-js@0.10.0-pre.5": version "0.10.0-pre.5" resolved "https://registry.yarnpkg.com/@polywrap/tracing-js/-/tracing-js-0.10.0-pre.5.tgz#3408c469c64a1f4e6f059f40d04c6b6e6328e76f" @@ -3367,6 +3531,50 @@ "@opentelemetry/sdk-trace-base" "1.6.0" "@opentelemetry/sdk-trace-web" "1.6.0" +"@polywrap/tracing-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/tracing-js/-/tracing-js-0.10.0-pre.6.tgz#ef1b8640d4c0a7a0a1f347931ae8b4f7494d287d" + integrity sha512-2IxLGRn3VdkMyq/aSo9H97oC6D+5+/JEp6mxvo4SxFROnt/0Ua9vs/8VhxBkIKPUglYFCug91T/CWTN0BhzvSw== + dependencies: + "@fetsorn/opentelemetry-console-exporter" "0.0.3" + "@opentelemetry/api" "1.2.0" + "@opentelemetry/exporter-trace-otlp-http" "0.32.0" + "@opentelemetry/resources" "1.6.0" + "@opentelemetry/sdk-trace-base" "1.6.0" + "@opentelemetry/sdk-trace-web" "1.6.0" + +"@polywrap/uri-resolver-extensions-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/uri-resolver-extensions-js/-/uri-resolver-extensions-js-0.10.0-pre.6.tgz#45ab587ed00c47bea8ffa5ea227d654694dc66ef" + integrity sha512-pS0PeF3SVDFn5DWSSeAiK5G+pfIzxrlu8EXk8F4xXdLXCQV93rTufLNUbh9XudvTmqcqgRC8CefvrnWI4sK7bg== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/uri-resolvers-js" "0.10.0-pre.6" + "@polywrap/wasm-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + +"@polywrap/uri-resolvers-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/uri-resolvers-js/-/uri-resolvers-js-0.10.0-pre.6.tgz#9c4a09fe426139ac3bf9609e4607d5ec2d9c2731" + integrity sha512-AT6H1z9Ck4cScRxxTeYT6DkydE1d1utK978Uyp/EF4OZ4OGbSWDdCJ3/6Kc+wSGAGPe5XoYMV805BpQqqjKueA== + dependencies: + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + +"@polywrap/wasm-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/wasm-js/-/wasm-js-0.10.0-pre.6.tgz#79f3bc29d771ba34fc222811f33d2b26a37f53ee" + integrity sha512-tXkfheTjJI7gn1KmD49Yb3FrQ4UpGuRJI5eaTucE9CKmlo7bKO8wn7e+3y1VxZPpGA1CZEqSdY5qPHRwSA5pcg== + dependencies: + "@polywrap/asyncify-js" "0.10.0-pre.6" + "@polywrap/core-js" "0.10.0-pre.6" + "@polywrap/msgpack-js" "0.10.0-pre.6" + "@polywrap/result" "0.10.0-pre.6" + "@polywrap/tracing-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-types-js" "0.10.0-pre.6" + "@polywrap/wrap-manifest-schemas@0.9.3": version "0.9.3" resolved "https://registry.yarnpkg.com/@polywrap/wrap-manifest-schemas/-/wrap-manifest-schemas-0.9.3.tgz#cdf950bb8951fba72afd8300aaf9a0a8159d7c37" @@ -3381,6 +3589,15 @@ jsonschema "1.4.0" semver "7.3.5" +"@polywrap/wrap-manifest-types-js@0.10.0-pre.6": + version "0.10.0-pre.6" + resolved "https://registry.yarnpkg.com/@polywrap/wrap-manifest-types-js/-/wrap-manifest-types-js-0.10.0-pre.6.tgz#1171be90c00ab5fe687f5b9bd1c7b32bb79e5d00" + integrity sha512-70Q+rCnB807m3au+pfP+/MimHacg7Wz2gMS5Q34GA5NGt5Qj0vdyqBjIYbIsyerMjO/gxHrf4CxKl+0+elX0fQ== + dependencies: + json-schema-ref-parser "9.0.9" + jsonschema "1.4.0" + semver "7.3.5" + "@sinclair/typebox@^0.24.1": version "0.24.51" resolved "https://registry.yarnpkg.com/@sinclair/typebox/-/typebox-0.24.51.tgz#645f33fe4e02defe26f2f5c0410e1c094eac7f5f" From bacd79079ca1299c10c3409a881091fb9dbd466a Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 20:42:03 +0530 Subject: [PATCH 20/25] reworked intro in client config builder readme using buildable snippets --- packages/js/client-config-builder/.gitignore | 3 + .../examples/quickstart.ts | 182 ++++++++++++++++++ .../examples/tsconfig.examples.json | 6 + .../js/client-config-builder/package.json | 4 +- .../js/client-config-builder/readme/README.md | 90 ++++----- .../client-config-builder/tsconfig.build.json | 6 +- .../js/client-config-builder/tsconfig.json | 6 +- 7 files changed, 248 insertions(+), 49 deletions(-) create mode 100644 packages/js/client-config-builder/.gitignore create mode 100644 packages/js/client-config-builder/examples/quickstart.ts create mode 100644 packages/js/client-config-builder/examples/tsconfig.examples.json diff --git a/packages/js/client-config-builder/.gitignore b/packages/js/client-config-builder/.gitignore new file mode 100644 index 0000000000..dbb01bb64d --- /dev/null +++ b/packages/js/client-config-builder/.gitignore @@ -0,0 +1,3 @@ +/examples/**/*.d.ts +/examples/**/*.js +/examples/**/*.js.map diff --git a/packages/js/client-config-builder/examples/quickstart.ts b/packages/js/client-config-builder/examples/quickstart.ts new file mode 100644 index 0000000000..f71c28550a --- /dev/null +++ b/packages/js/client-config-builder/examples/quickstart.ts @@ -0,0 +1,182 @@ +import { ClientConfigBuilder, ClientConfig } from "../build"; + +// eslint-disable-next-line import/no-extraneous-dependencies +import { WasmWrapper } from "@polywrap/wasm-js"; +import { httpPlugin } from "@polywrap/http-plugin-js"; +import { RecursiveResolver, WrapperCache } from "@polywrap/uri-resolvers-js"; +import { fileSystemPlugin } from "@polywrap/fs-plugin-js"; +import { CoreClientConfig, Uri } from "@polywrap/core-js"; + +export function initialize(): ClientConfigBuilder { + // $start: quickstart-initialize + // start with a blank slate (typical usage) + const builder = new ClientConfigBuilder(); + + // instantiate a builder with a custom cache and/or resolver + const _builder = new ClientConfigBuilder( + new WrapperCache(), + RecursiveResolver.from([]) + ); + // $end + + return builder ?? _builder; +} + +export function configure(): ClientConfigBuilder { + const builder = new ClientConfigBuilder(); + + // $start: quickstart-configure + // add multiple items to the configuration using the catch-all `add` method + builder.add({ + envs: [], + interfaces: [], + redirects: [], + wrappers: [], + packages: [], + resolvers: [], + }); + + // add or remove items using the more specific add methods + builder + .addPackage({ + uri: "wrap://plugin/package", + package: httpPlugin({}), + }) + .removePackage("wrap://plugin/package") + .addPackages([ + { + uri: "wrap://plugin/http", + package: httpPlugin({}), + }, + { + uri: "wrap://plugin/filesystem", + package: fileSystemPlugin({}), + }, + ]); + // $end + + // $start: quickstart-addDefaults + builder.addDefaults(); + // $end + + return builder; +} + +export function build(): + | ClientConfigBuilder + | ClientConfig + | CoreClientConfig { + const builder = new ClientConfigBuilder(); + + // $start: quickstart-build + // accepted by the PolywrapClient + const clientConfig = builder.build(); + + // accepted by either the PolywrapClient or the PolywrapCoreClient + const coreClientConfig = builder.buildCoreConfig(); + // $end + + return builder ?? clientConfig ?? coreClientConfig; +} + +export async function example(): Promise> { + // $start: quickstart-example + // init + const builder = new ClientConfigBuilder(); + + // add the default bundle first to override its entries later + builder.addDefaults(); + + // add many config items at once + builder.add({ + envs: [], + interfaces: [], + redirects: [], + wrappers: [], + packages: [], + resolvers: [], + }); + + // add and remove wrappers + builder + .addWrapper({ + uri: "wrap://ens/wrapper.eth", + wrapper: await WasmWrapper.from( + new Uint8Array([1, 2, 3]), + new Uint8Array([1, 2, 3]) + ), + }) + .removeWrapper("wrap://ens/wrapper.eth") + .addWrappers([ + { + uri: "wrap://ens/wrapper.eth", + wrapper: await WasmWrapper.from( + new Uint8Array([1, 2, 3]), + new Uint8Array([1, 2, 3]) + ), + }, + ]); + + // add and remove wrap packages + builder + .addPackage({ + uri: "wrap://plugin/package", + package: httpPlugin({}), + }) + .removePackage("wrap://plugin/package") + .addPackages([ + { + uri: "wrap://plugin/package", + package: httpPlugin({}), + }, + ]); + + // add and remove Envs + builder + .addEnv("wrap://ens/wrapper.eth", { key: "value" }) + .removeEnv("wrap://ens/wrapper.eth") + .addEnvs([ + { + uri: "wrap://ens/wrapper.eth", + env: { key: "value" }, + }, + ]); + + // override existing Env, or add new Env if one is not registered at URI + builder.setEnv("wrap://ens/wrapper.eth", { key: "value" }); + + // add or remove registration for an implementation of an interface + builder + .addInterfaceImplementation( + "wrap://ens/interface.eth", + "wrap://ens/wrapper.eth" + ) + .removeInterfaceImplementation( + "wrap://ens/interface.eth", + "wrap://ens/wrapper.eth" + ) + .addInterfaceImplementations("wrap://ens/interface.eth", [ + "wrap://ens/wrapper.eth", + ]); + + // add or remove URI redirects + builder + .addRedirect("wrap://ens/from.eth", "wrap://ens/to.eth") + .removeRedirect("wrap://ens/from.eth") + .addRedirects([ + { + from: "wrap://ens/from.eth", + to: "wrap://ens/to.eth", + }, + ]); + + // add resolvers + builder.addResolver(RecursiveResolver.from([])); + builder.addResolvers([]); + + // build + const clientConfig = builder.build(); + // $end + + return clientConfig; +} diff --git a/packages/js/client-config-builder/examples/tsconfig.examples.json b/packages/js/client-config-builder/examples/tsconfig.examples.json new file mode 100644 index 0000000000..f37de53612 --- /dev/null +++ b/packages/js/client-config-builder/examples/tsconfig.examples.json @@ -0,0 +1,6 @@ +{ + "extends": "../tsconfig.json", + "include": [ + "./**/*.ts" + ], +} \ No newline at end of file diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index b94c63efdb..2334f42780 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -12,12 +12,13 @@ "build" ], "scripts": { - "build": "yarn build:fast && yarn build:readme", + "build": "yarn build:fast && yarn build:snippets && yarn build:readme", "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose", "test:ci": "jest --passWithNoTests --runInBand --verbose", "test:watch": "jest --watch --passWithNoTests --verbose", + "build:snippets": "tsc --project ./examples/tsconfig.examples.json", "build:readme": "yarn doc-snippets combine" }, "dependencies": { @@ -37,6 +38,7 @@ "doc-snippets": "^1.0.0" }, "devDependencies": { + "@polywrap/wasm-js": "0.10.0-pre.7", "@types/jest": "26.0.8", "@types/prettier": "2.6.0", "jest": "26.6.3", diff --git a/packages/js/client-config-builder/readme/README.md b/packages/js/client-config-builder/readme/README.md index 1a0e6bfad0..157b1448b3 100644 --- a/packages/js/client-config-builder/readme/README.md +++ b/packages/js/client-config-builder/readme/README.md @@ -1,45 +1,47 @@ # PolywrapClient Config Builder -A DSL for building the PolywrapClient config object. +A utility class for building the PolywrapClient config. Supports building configs using method chaining or imperatively. -```typescript= -import { ClientConfigBuilder } from "@polywrap/client-config-builder-js"; -import { PolywrapClient } from "@polywrap/client-js"; +## Quickstart + +### Initialize -const config = new ClientConfigBuilder() - .add({ - envs: [/*...*/], - interfaces: [/*...*/], - redirects: [/*...*/], - wrappers: [/*...*/], - packages: [/*...*/], - resolvers: [/*...*/], - }) - .add({/*...*/}) - .build(); +Initialize a ClientConfigBuilder using the [constructor](#constructor) -// ... +```typescript +$snippet: quickstart-initialize +``` -const builder = new ClientConfigBuilder(); +### Configure -builder.addDefaults(); +Add client configuration with [add](#add), or flexibly mix and match builder [configuration methods](#addwrapper) to add and remove configuration items. -builder.add({ - packages: [/*...*/] -}); +```typescript +$snippet: quickstart-configure +``` -builder.add({ - envs: [/*...*/] -}); +You can add the entire [default client configuration bundle](#bundle--defaultconfig) at once with [addDefaults](#adddefaults) -const config = builder.build(); +```typescript +$snippet: quickstart-addDefaults +``` +### Build -// ... +Finally, build a ClientConfig or CoreClientConfig to pass to the PolywrapClient constructor. -let client = new PolywrapClient(config); +```typescript +$snippet: quickstart-build +``` + +### Example + +A complete example using all or most of the available methods. + +```typescript= +$snippet: quickstart ``` # Reference @@ -57,26 +59,11 @@ $snippet: ClientConfig $snippet: ClientConfigBuilder-constructor ``` -### build -```ts -$snippet: IClientConfigBuilder-build -``` - -### buildCoreConfig -```ts -$snippet: IClientConfigBuilder-buildCoreConfig -``` - ### add ```ts $snippet: IClientConfigBuilder-add ``` -### addDefaults -```ts -$snippet: IClientConfigBuilder-addDefaults -``` - ### addWrapper ```ts $snippet: IClientConfigBuilder-addWrapper @@ -167,7 +154,24 @@ $snippet: IClientConfigBuilder-addResolver $snippet: IClientConfigBuilder-addResolvers ``` -## Bundle: DefaultConfig +### addDefaults +```ts +$snippet: IClientConfigBuilder-addDefaults +``` + +### build +```ts +$snippet: IClientConfigBuilder-build +``` + +### buildCoreConfig +```ts +$snippet: IClientConfigBuilder-buildCoreConfig +``` + +## Bundles + +### Bundle: DefaultConfig ```ts $snippet: getDefaultConfig ``` \ No newline at end of file diff --git a/packages/js/client-config-builder/tsconfig.build.json b/packages/js/client-config-builder/tsconfig.build.json index 9708b5768a..aa60f0a106 100644 --- a/packages/js/client-config-builder/tsconfig.build.json +++ b/packages/js/client-config-builder/tsconfig.build.json @@ -1,9 +1,13 @@ { "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "build" + }, "include": [ "./src/**/*.ts" ], "exclude": [ - "./src/**/__tests__" + "./src/**/__tests__", + "./examples" ] } \ No newline at end of file diff --git a/packages/js/client-config-builder/tsconfig.json b/packages/js/client-config-builder/tsconfig.json index 5d37204c00..02827831c0 100644 --- a/packages/js/client-config-builder/tsconfig.json +++ b/packages/js/client-config-builder/tsconfig.json @@ -1,10 +1,8 @@ { "extends": "../../../tsconfig", - "compilerOptions": { - "outDir": "build" - }, "include": [ - "./src/**/*.ts" + "./src/**/*.ts", + "./examples/**/*.ts" ], "exclude": [] } From a748ca84a2466992004e417f270a888f99e5acfe Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 21:55:44 +0530 Subject: [PATCH 21/25] reworked doc-snippets config for client config builder to properly extract snippets from examples --- packages/js/client-config-builder/README.md | 347 +++++++++++++----- .../examples/quickstart.ts | 2 +- .../js/client-config-builder/package.json | 7 +- .../js/client-config-builder/readme/README.md | 2 +- .../client-config-builder/tsconfig.build.json | 1 - packages/js/client/README.md | 2 + packages/js/core-client/README.md | 14 +- packages/js/core/README.md | 16 +- 8 files changed, 279 insertions(+), 112 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index 858c276741..879f632250 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -1,47 +1,182 @@ # PolywrapClient Config Builder -A DSL for building the PolywrapClient config object. +A utility class for building the PolywrapClient config. Supports building configs using method chaining or imperatively. -```typescript= -import { ClientConfigBuilder } from "@polywrap/client-config-builder-js"; -import { PolywrapClient } from "@polywrap/client-js"; +## Quickstart + +### Initialize + +Initialize a ClientConfigBuilder using the [constructor](#constructor) + +```typescript + // start with a blank slate (typical usage) + const builder = new ClientConfigBuilder(); + + // instantiate a builder with a custom cache and/or resolver + const _builder = new ClientConfigBuilder( + new WrapperCache(), + RecursiveResolver.from([]) + ); +``` + +### Configure + +Add client configuration with [add](#add), or flexibly mix and match builder [configuration methods](#addwrapper) to add and remove configuration items. + +```typescript + // add multiple items to the configuration using the catch-all `add` method + builder.add({ + envs: [], + interfaces: [], + redirects: [], + wrappers: [], + packages: [], + resolvers: [], + }); + + // add or remove items by chaining method calls + builder + .addPackage({ + uri: "wrap://plugin/package", + package: httpPlugin({}), + }) + .removePackage("wrap://plugin/package") + .addPackages([ + { + uri: "wrap://plugin/http", + package: httpPlugin({}), + }, + { + uri: "wrap://plugin/filesystem", + package: fileSystemPlugin({}), + }, + ]); +``` + +You can add the entire [default client configuration bundle](#bundle--defaultconfig) at once with [addDefaults](#adddefaults) + +```typescript + builder.addDefaults(); +``` + +### Build + +Finally, build a ClientConfig or CoreClientConfig to pass to the PolywrapClient constructor. + +```typescript + // accepted by the PolywrapClient + const clientConfig = builder.build(); -const config = new ClientConfigBuilder() - .add({ - envs: [/*...*/], - interfaces: [/*...*/], - redirects: [/*...*/], - wrappers: [/*...*/], - packages: [/*...*/], - resolvers: [/*...*/], - }) - .add({/*...*/}) - .build(); + // accepted by either the PolywrapClient or the PolywrapCoreClient + const coreClientConfig = builder.buildCoreConfig(); +``` -// ... +### Example -const builder = new ClientConfigBuilder(); +A complete example using all or most of the available methods. -builder.addDefaults(); +```typescript= + // init + const builder = new ClientConfigBuilder(); -builder.add({ - packages: [/*...*/] -}); + // add the default bundle first to override its entries later + builder.addDefaults(); -builder.add({ - envs: [/*...*/] -}); + // add many config items at once + builder.add({ + envs: [], + interfaces: [], + redirects: [], + wrappers: [], + packages: [], + resolvers: [], + }); + + // add and remove wrappers + builder + .addWrapper({ + uri: "wrap://ens/wrapper.eth", + wrapper: await WasmWrapper.from( + new Uint8Array([1, 2, 3]), + new Uint8Array([1, 2, 3]) + ), + }) + .removeWrapper("wrap://ens/wrapper.eth") + .addWrappers([ + { + uri: "wrap://ens/wrapper.eth", + wrapper: await WasmWrapper.from( + new Uint8Array([1, 2, 3]), + new Uint8Array([1, 2, 3]) + ), + }, + ]); -const config = builder.build(); + // add and remove wrap packages + builder + .addPackage({ + uri: "wrap://plugin/package", + package: httpPlugin({}), + }) + .removePackage("wrap://plugin/package") + .addPackages([ + { + uri: "wrap://plugin/package", + package: httpPlugin({}), + }, + ]); + // add and remove Envs + builder + .addEnv("wrap://ens/wrapper.eth", { key: "value" }) + .removeEnv("wrap://ens/wrapper.eth") + .addEnvs([ + { + uri: "wrap://ens/wrapper.eth", + env: { key: "value" }, + }, + ]); + + // override existing Env, or add new Env if one is not registered at URI + builder.setEnv("wrap://ens/wrapper.eth", { key: "value" }); + + // add or remove registration for an implementation of an interface + builder + .addInterfaceImplementation( + "wrap://ens/interface.eth", + "wrap://ens/wrapper.eth" + ) + .removeInterfaceImplementation( + "wrap://ens/interface.eth", + "wrap://ens/wrapper.eth" + ) + .addInterfaceImplementations("wrap://ens/interface.eth", [ + "wrap://ens/wrapper.eth", + ]); + + // add or remove URI redirects + builder + .addRedirect("wrap://ens/from.eth", "wrap://ens/to.eth") + .removeRedirect("wrap://ens/from.eth") + .addRedirects([ + { + from: "wrap://ens/from.eth", + to: "wrap://ens/to.eth", + }, + ]); -// ... + // add resolvers + builder.addResolver(RecursiveResolver.from([])); + builder.addResolvers([]); -let client = new PolywrapClient(config); + // build + const clientConfig = builder.build(); ``` +# Reference + ## Types ```ts @@ -85,6 +220,7 @@ export interface ClientConfig { ### Constructor ```ts + /** * Instantiate a ClientConfigBuilder * * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache @@ -96,26 +232,6 @@ export interface ClientConfig { ) ``` -### build -```ts - /** - * Build a sanitized client configuration that can be passed to the PolywrapClient constructor - * - * @returns ClientConfig that results from applying all the steps in the builder pipeline - */ - build(): ClientConfig; -``` - -### buildCoreConfig -```ts - /** - * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors - * - * @returns CoreClientConfig that results from applying all the steps in the builder pipeline - */ - buildCoreConfig(): CoreClientConfig; -``` - ### add ```ts /** @@ -128,16 +244,6 @@ export interface ClientConfig { add(config: Partial): IClientConfigBuilder; ``` -### addDefaults -```ts - /** - * Add the default configuration bundle - * - * @returns IClientConfigBuilder (mutated self) - */ - addDefaults(): IClientConfigBuilder; -``` - ### addWrapper ```ts /** @@ -372,8 +478,73 @@ export interface ClientConfig { addResolvers(resolvers: UriResolverLike[]): IClientConfigBuilder; ``` -## Bundle: DefaultConfig +### addDefaults +```ts + /** + * Add the default configuration bundle + * + * @returns IClientConfigBuilder (mutated self) + */ + addDefaults(): IClientConfigBuilder; +``` + +### build +```ts + /** + * Build a sanitized client configuration that can be passed to the PolywrapClient constructor + * + * @returns ClientConfig that results from applying all the steps in the builder pipeline + */ + build(): ClientConfig; +``` + +### buildCoreConfig +```ts + /** + * Build a sanitized core client configuration that can be passed to the PolywrapClient or PolywrapCoreClient constructors + * + * @returns CoreClientConfig that results from applying all the steps in the builder pipeline + */ + buildCoreConfig(): CoreClientConfig; +``` + +## Bundles + +### Bundle: DefaultConfig ```ts + +export const defaultIpfsProviders = [ + "https://ipfs.wrappers.io", + "https://ipfs.io", +]; + +export const defaultWrappers = { + sha3: "wrap://ens/goerli/sha3.wrappers.eth", + uts46: "wrap://ens/goerli/uts46-lite.wrappers.eth", + graphNode: "wrap://ens/goerli/graph-node.wrappers.eth", + ensTextRecordResolver: + "wrap://ipfs/QmfRCVA1MSAjUbrXXjya4xA9QHkbWeiKRsT7Um1cvrR7FY", +}; + +export const defaultPackages = { + ipfs: "wrap://ens/ipfs.polywrap.eth", + ensResolver: "wrap://ens/ens-resolver.polywrap.eth", + ethereum: "wrap://ens/ethereum.polywrap.eth", + http: "wrap://ens/http.polywrap.eth", + httpResolver: "wrap://ens/http-resolver.polywrap.eth", + logger: "wrap://plugin/logger", + fileSystem: "wrap://ens/fs.polywrap.eth", + fileSystemResolver: "wrap://ens/fs-resolver.polywrap.eth", + ipfsResolver: "wrap://ens/ipfs-resolver.polywrap.eth", + concurrent: "wrap://plugin/concurrent", +}; + +export const defaultInterfaces = { + uriResolver: "wrap://ens/uri-resolver.core.polywrap.eth", + concurrent: "wrap://ens/goerli/interface.concurrent.wrappers.eth", + logger: "wrap://ens/wrappers.polywrap.eth:logger@1.0.0", +}; + export const getDefaultConfig = (): ClientConfig => { return { envs: [ @@ -384,7 +555,7 @@ export const getDefaultConfig = (): ClientConfig => { }, }, { - uri: new Uri("wrap://ens/ipfs.polywrap.eth"), + uri: new Uri(defaultPackages.ipfs), env: { provider: defaultIpfsProviders[0], fallbackProviders: defaultIpfsProviders.slice(1), @@ -405,29 +576,28 @@ export const getDefaultConfig = (): ClientConfig => { to: new Uri(defaultWrappers.graphNode), }, { - from: new Uri("wrap://ens/wrappers.polywrap.eth:logger@1.0.0"), - to: new Uri("wrap://plugin/logger"), + from: new Uri(defaultInterfaces.logger), + to: new Uri(defaultPackages.logger), }, ], interfaces: [ { - interface: new Uri("wrap://ens/uri-resolver.core.polywrap.eth"), + interface: new Uri(defaultInterfaces.uriResolver), implementations: [ - new Uri("wrap://ens/ipfs-resolver.polywrap.eth"), - new Uri("wrap://ens/ens-resolver.polywrap.eth"), - new Uri("wrap://ens/fs-resolver.polywrap.eth"), - new Uri("wrap://ens/http-resolver.polywrap.eth"), - // ens-text-record-resolver - new Uri("wrap://ipfs/QmfRCVA1MSAjUbrXXjya4xA9QHkbWeiKRsT7Um1cvrR7FY"), + new Uri(defaultPackages.ipfsResolver), + new Uri(defaultPackages.ensResolver), + new Uri(defaultPackages.fileSystemResolver), + new Uri(defaultPackages.httpResolver), + new Uri(defaultWrappers.ensTextRecordResolver), ], }, { - interface: new Uri("wrap://ens/wrappers.polywrap.eth:logger@1.0.0"), - implementations: [new Uri("wrap://plugin/logger")], + interface: new Uri(defaultInterfaces.logger), + implementations: [new Uri(defaultPackages.logger)], }, { - interface: new Uri(defaultWrappers.concurrentInterface), - implementations: [new Uri("wrap://plugin/concurrent")], + interface: new Uri(defaultInterfaces.concurrent), + implementations: [new Uri(defaultPackages.concurrent)], }, ], packages: getDefaultPlugins(), @@ -436,32 +606,20 @@ export const getDefaultConfig = (): ClientConfig => { }; }; -export const defaultIpfsProviders = [ - "https://ipfs.wrappers.io", - "https://ipfs.io", -]; - -export const defaultWrappers = { - sha3: "wrap://ens/goerli/sha3.wrappers.eth", - uts46: "wrap://ens/goerli/uts46-lite.wrappers.eth", - graphNode: "wrap://ens/goerli/graph-node.wrappers.eth", - concurrentInterface: "wrap://ens/goerli/interface.concurrent.wrappers.eth", -}; - export const getDefaultPlugins = (): IUriPackage[] => { return [ // IPFS is required for downloading Polywrap packages { - uri: new Uri("wrap://ens/ipfs.polywrap.eth"), + uri: new Uri(defaultPackages.ipfs), package: ipfsPlugin({}), }, // ENS is required for resolving domain to IPFS hashes { - uri: new Uri("wrap://ens/ens-resolver.polywrap.eth"), + uri: new Uri(defaultPackages.ensResolver), package: ensResolverPlugin({}), }, { - uri: new Uri("wrap://ens/ethereum.polywrap.eth"), + uri: new Uri(defaultPackages.ethereum), package: ethereumPlugin({ connections: new Connections({ networks: { @@ -478,34 +636,35 @@ export const getDefaultPlugins = (): IUriPackage[] => { }), }, { - uri: new Uri("wrap://ens/http.polywrap.eth"), + uri: new Uri(defaultPackages.http), package: httpPlugin({}), }, { - uri: new Uri("wrap://ens/http-resolver.polywrap.eth"), + uri: new Uri(defaultPackages.httpResolver), package: httpResolverPlugin({}), }, { - uri: new Uri("wrap://plugin/logger"), + uri: new Uri(defaultPackages.logger), // TODO: remove this once types are updated package: loggerPlugin({}) as IWrapPackage, }, { - uri: new Uri("wrap://ens/fs.polywrap.eth"), + uri: new Uri(defaultPackages.fileSystem), package: fileSystemPlugin({}), }, { - uri: new Uri("wrap://ens/fs-resolver.polywrap.eth"), + uri: new Uri(defaultPackages.fileSystemResolver), package: fileSystemResolverPlugin({}), }, { - uri: new Uri("wrap://ens/ipfs-resolver.polywrap.eth"), + uri: new Uri(defaultPackages.ipfsResolver), package: ipfsResolverPlugin({}), }, { - uri: new Uri("wrap://plugin/concurrent"), + uri: new Uri(defaultPackages.concurrent), package: concurrentPromisePlugin({}), }, ]; }; + ``` \ No newline at end of file diff --git a/packages/js/client-config-builder/examples/quickstart.ts b/packages/js/client-config-builder/examples/quickstart.ts index f71c28550a..1790bcceb5 100644 --- a/packages/js/client-config-builder/examples/quickstart.ts +++ b/packages/js/client-config-builder/examples/quickstart.ts @@ -36,7 +36,7 @@ export function configure(): ClientConfigBuilder { resolvers: [], }); - // add or remove items using the more specific add methods + // add or remove items by chaining method calls builder .addPackage({ uri: "wrap://plugin/package", diff --git a/packages/js/client-config-builder/package.json b/packages/js/client-config-builder/package.json index 2334f42780..fdbca4df65 100644 --- a/packages/js/client-config-builder/package.json +++ b/packages/js/client-config-builder/package.json @@ -53,13 +53,16 @@ }, "doc-snippets": { "extract": { - "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "include": [ + "./src/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "./examples/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}" + ], "ignore": [ "./**/node_modules/**", "./**/.polywrap/**", "./**/__tests__/**" ], - "dir": "./src" + "dir": "./" }, "inject": { "dir": "./readme", diff --git a/packages/js/client-config-builder/readme/README.md b/packages/js/client-config-builder/readme/README.md index 157b1448b3..3748e58241 100644 --- a/packages/js/client-config-builder/readme/README.md +++ b/packages/js/client-config-builder/readme/README.md @@ -41,7 +41,7 @@ $snippet: quickstart-build A complete example using all or most of the available methods. ```typescript= -$snippet: quickstart +$snippet: quickstart-example ``` # Reference diff --git a/packages/js/client-config-builder/tsconfig.build.json b/packages/js/client-config-builder/tsconfig.build.json index aa60f0a106..ccebf665da 100644 --- a/packages/js/client-config-builder/tsconfig.build.json +++ b/packages/js/client-config-builder/tsconfig.build.json @@ -8,6 +8,5 @@ ], "exclude": [ "./src/**/__tests__", - "./examples" ] } \ No newline at end of file diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 6678f08179..88db656289 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -104,6 +104,8 @@ const client = new PolywrapClient(config); const altClient = new PolywrapClient(config, { noDefaults: true }); ``` +# Reference + ## Types ```ts diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index cb014c186d..17febba20a 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -82,6 +82,8 @@ const config = { const client = new PolywrapCoreClient(config); ``` +# Reference + ## Types ```ts @@ -194,7 +196,7 @@ export interface PolywrapCoreClientConfig< @Tracer.traceMethod("PolywrapClient: getManifest") public async getManifest( uri: TUri - ): Promise> + ): Promise> ``` ### getFile @@ -210,7 +212,7 @@ export interface PolywrapCoreClientConfig< public async getFile( uri: TUri, options: GetFileOptions - ): Promise> + ): Promise> ``` ### getImplementations @@ -227,7 +229,7 @@ export interface PolywrapCoreClientConfig< public async getImplementations( uri: TUri, options: GetImplementationsOptions = {} - ): Promise> + ): Promise> ``` ### invokeWrapper @@ -337,7 +339,7 @@ export interface PolywrapCoreClientConfig< uri: Uri, resolutionContext?: IUriResolutionContext, options?: DeserializeManifestOptions - ): Promise> + ): Promise> ``` ### validate @@ -350,11 +352,11 @@ export interface PolywrapCoreClientConfig< * @param options - { abi?: boolean; recursive?: boolean } * @returns A Promise with a Result containing a boolean or Error */ - @Tracer.traceMethod("PolywrapClient: validateConfig") + @Tracer.traceMethod("PolywrapClient: validate") public async validate( uri: TUri, options: ValidateOptions - ): Promise> + ): Promise> ``` ## Development diff --git a/packages/js/core/README.md b/packages/js/core/README.md index 2fd063433d..7dbcb78286 100644 --- a/packages/js/core/README.md +++ b/packages/js/core/README.md @@ -2,6 +2,8 @@ A TypeScript / JavaScript implementation of the WRAP standard, including all fundamental types & algorithms. +# Reference + ## Types ### CoreClient @@ -93,7 +95,7 @@ export interface CoreClient extends Invoker, UriResolverHandler { */ getManifest( uri: TUri - ): Promise>; + ): Promise>; /** * returns a file contained in a wrap package @@ -105,7 +107,7 @@ export interface CoreClient extends Invoker, UriResolverHandler { getFile( uri: TUri, options: GetFileOptions - ): Promise>; + ): Promise>; /** * returns the interface implementations associated with an interface URI @@ -118,7 +120,7 @@ export interface CoreClient extends Invoker, UriResolverHandler { getImplementations( uri: TUri, options: GetImplementationsOptions - ): Promise>; + ): Promise>; /** * Validate a wrapper, given a URI. @@ -131,7 +133,7 @@ export interface CoreClient extends Invoker, UriResolverHandler { validate( uri: TUri, options?: ValidateOptions - ): Promise>; + ): Promise>; } ``` @@ -193,7 +195,7 @@ export interface InvokeOptions { * * @template TData Type of the invoke result data. */ -export type InvokeResult = Result; +export type InvokeResult = Result; /** * Provides options for the invoker to set based on the state of the invocation. @@ -580,7 +582,7 @@ export interface MaybeUriOrManifest { invoker: Invoker, wrapper: Uri, uri: Uri - ): Promise> + ): Promise> ``` #### getFile @@ -598,7 +600,7 @@ export interface MaybeUriOrManifest { invoker: Invoker, wrapper: Uri, path: string - ): Promise> + ): Promise> ``` ## Uri Resolution From 32350d8354d06f4bcebb66bacf874d32c2cf6044 Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 22:34:46 +0530 Subject: [PATCH 22/25] added snippets to client readme intro --- packages/js/client/.gitignore | 3 + packages/js/client/README.md | 99 +++++-------------- packages/js/client/examples/quickstart.ts | 38 +++++++ .../js/client/examples/tsconfig.examples.json | 6 ++ packages/js/client/package.json | 10 +- packages/js/client/readme/README.md | 91 +++-------------- 6 files changed, 91 insertions(+), 156 deletions(-) create mode 100644 packages/js/client/.gitignore create mode 100644 packages/js/client/examples/quickstart.ts create mode 100644 packages/js/client/examples/tsconfig.examples.json diff --git a/packages/js/client/.gitignore b/packages/js/client/.gitignore new file mode 100644 index 0000000000..dbb01bb64d --- /dev/null +++ b/packages/js/client/.gitignore @@ -0,0 +1,3 @@ +/examples/**/*.d.ts +/examples/**/*.js +/examples/**/*.js.map diff --git a/packages/js/client/README.md b/packages/js/client/README.md index 88db656289..a40f7e1fc9 100644 --- a/packages/js/client/README.md +++ b/packages/js/client/README.md @@ -15,93 +15,42 @@ npm install --save @polywrap/client-js ## Usage -### Instantiate the client +### Instantiate + +Use the PolywrapClient [constructor](#constructor) to instantiate the client with the default configuration bundle. + ```ts -import { PolywrapClient } from "@polywrap/client-js"; + import { PolywrapClient } from "@polywrap/client-js"; -const client = new PolywrapClient(); + const client = new PolywrapClient(); ``` -### Invoke a wrapper +### Configure + +Use the `@polywrap/client-config-builder-js` package to build a custom configuration for your project. ```ts -await client.invoke({ - uri: "ens/helloworld.dev.polywrap.eth", - method: "logMessage", - args: { - message: "Hello World!" - } -}); + const config = new ClientConfigBuilder().addDefaults().buildCoreConfig(); + + const client = new PolywrapClient(config, { noDefaults: true }); ``` -### Configure the client +### Invoke + +Invoke a wrapper. ```ts -const config = { - // redirect invocations from one uri to another - redirects: [ - { - from: "wrap://ens/from.eth", - to: "wrap://ens/to.eth", + const result = await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" } - ], - // add embedded Wasm wrappers - wrappers: [ - { - uri: "wrap://fs/simple/wrapper/uri/build", - wrapper: WasmWrapper.from( - fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.info")), - fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.wasm")) - ) - } - ], - // add and configure embedded plugin wrappers - packages: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - package: ipfsPlugin({}), - }, - ], - // declare interface implementations - interfaces: [ - { - interface: "wrap://ens/uri-resolver.core.polywrap.eth", - implementations: [ - "wrap://ens/ipfs-resolver.polywrap.eth", - ], - }, - ], - // set environmental variables for a wrapper - envs: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - env: { - provider: "https://ipfs.wrappers.io", - }, - }, - ], - // customize URI resolution - resolvers: [ - new RecursiveResolver( - new PackageToWrapperCacheResolver(wrapperCache, [ - new ExtendableUriResolver(), - ]) - ) - ], - - // custom wrapper cache - wrapperCache: new WrapperCache(), - - // tracer configuration - see @polywrap/tracing-js package - tracerConfig: { ... }, -}; -``` -```ts -// create a client by modifying the default configuration bundle -const client = new PolywrapClient(config); + }); + + if (!result.ok) throw result.error; -// or remove and replace the default configuration -const altClient = new PolywrapClient(config, { noDefaults: true }); + const value = result.value; ``` # Reference diff --git a/packages/js/client/examples/quickstart.ts b/packages/js/client/examples/quickstart.ts new file mode 100644 index 0000000000..1f7470ce0d --- /dev/null +++ b/packages/js/client/examples/quickstart.ts @@ -0,0 +1,38 @@ +import { ClientConfigBuilder, PolywrapClient } from "../build"; + +export function instantiate(): PolywrapClient { + // /* $: quickstart-instantiate */ import { PolywrapClient } from "@polywrap/client-js"; + + const client = new PolywrapClient(); + // $end + + return client; +} + +export function configure(): PolywrapClient { + // $start: quickstart-configure + const config = new ClientConfigBuilder().addDefaults().buildCoreConfig(); + + const client = new PolywrapClient(config, { noDefaults: true }); + // $end + + return client; +} + +export async function invoke(): Promise { + const client = new PolywrapClient(); + // $start: quickstart-invoke + const result = await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } + }); + + if (!result.ok) throw result.error; + + const value = result.value; + // $end + return value; +} diff --git a/packages/js/client/examples/tsconfig.examples.json b/packages/js/client/examples/tsconfig.examples.json new file mode 100644 index 0000000000..f37de53612 --- /dev/null +++ b/packages/js/client/examples/tsconfig.examples.json @@ -0,0 +1,6 @@ +{ + "extends": "../tsconfig.json", + "include": [ + "./**/*.ts" + ], +} \ No newline at end of file diff --git a/packages/js/client/package.json b/packages/js/client/package.json index 26fe89f15c..eac43c213f 100644 --- a/packages/js/client/package.json +++ b/packages/js/client/package.json @@ -12,13 +12,14 @@ "build" ], "scripts": { - "build": "yarn build:fast && yarn build:readme", + "build": "yarn build:fast && yarn build:snippets && yarn build:readme", "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", "test:ci": "jest --passWithNoTests --runInBand --verbose --detectOpenHandles --forceExit", "test:rust": "jest --passWithNoTests --runInBand --verbose --detectOpenHandles --forceExit --config ./jest.rs.config.js", "test:watch": "jest --watch --passWithNoTests --verbose --detectOpenHandles", + "build:snippets": "tsc --project ./examples/tsconfig.examples.json", "build:readme": "yarn doc-snippets combine" }, "dependencies": { @@ -65,13 +66,16 @@ }, "doc-snippets": { "extract": { - "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "include": [ + "./src/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "./examples/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}" + ], "ignore": [ "./**/node_modules/**", "./**/.polywrap/**", "./**/__tests__/**" ], - "dir": "./src" + "dir": "./" }, "inject": { "dir": "./readme", diff --git a/packages/js/client/readme/README.md b/packages/js/client/readme/README.md index 11ba112ef3..63c1cf1e63 100644 --- a/packages/js/client/readme/README.md +++ b/packages/js/client/readme/README.md @@ -15,93 +15,28 @@ npm install --save @polywrap/client-js ## Usage -### Instantiate the client -```ts -import { PolywrapClient } from "@polywrap/client-js"; - -const client = new PolywrapClient(); -``` +### Instantiate -### Invoke a wrapper +Use the PolywrapClient [constructor](#constructor) to instantiate the client with the default configuration bundle. ```ts -await client.invoke({ - uri: "ens/helloworld.dev.polywrap.eth", - method: "logMessage", - args: { - message: "Hello World!" - } -}); +$snippet: quickstart-instantiate ``` -### Configure the client +### Configure + +Use the `@polywrap/client-config-builder-js` package to build a custom configuration for your project. ```ts -const config = { - // redirect invocations from one uri to another - redirects: [ - { - from: "wrap://ens/from.eth", - to: "wrap://ens/to.eth", - } - ], - // add embedded Wasm wrappers - wrappers: [ - { - uri: "wrap://fs/simple/wrapper/uri/build", - wrapper: WasmWrapper.from( - fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.info")), - fs.readFileSync(path.join(simpleWrapperPath, "build/wrap.wasm")) - ) - } - ], - // add and configure embedded plugin wrappers - packages: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - package: ipfsPlugin({}), - }, - ], - // declare interface implementations - interfaces: [ - { - interface: "wrap://ens/uri-resolver.core.polywrap.eth", - implementations: [ - "wrap://ens/ipfs-resolver.polywrap.eth", - ], - }, - ], - // set environmental variables for a wrapper - envs: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - env: { - provider: "https://ipfs.wrappers.io", - }, - }, - ], - // customize URI resolution - resolvers: [ - new RecursiveResolver( - new PackageToWrapperCacheResolver(wrapperCache, [ - new ExtendableUriResolver(), - ]) - ) - ], - - // custom wrapper cache - wrapperCache: new WrapperCache(), - - // tracer configuration - see @polywrap/tracing-js package - tracerConfig: { ... }, -}; +$snippet: quickstart-configure ``` -```ts -// create a client by modifying the default configuration bundle -const client = new PolywrapClient(config); -// or remove and replace the default configuration -const altClient = new PolywrapClient(config, { noDefaults: true }); +### Invoke + +Invoke a wrapper. + +```ts +$snippet: quickstart-invoke ``` # Reference From f23c36e6e60c2d1f394348c9795b6fce776e014b Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 22:49:38 +0530 Subject: [PATCH 23/25] added snippets to core client readme intro --- packages/js/core-client/.gitignore | 3 + packages/js/core-client/README.md | 75 +++++------------- .../js/core-client/examples/quickstart.ts | 33 ++++++++ .../examples/tsconfig.examples.json | 6 ++ packages/js/core-client/package.json | 10 ++- packages/js/core-client/readme/README.md | 79 ++++--------------- 6 files changed, 81 insertions(+), 125 deletions(-) create mode 100644 packages/js/core-client/.gitignore create mode 100644 packages/js/core-client/examples/quickstart.ts create mode 100644 packages/js/core-client/examples/tsconfig.examples.json diff --git a/packages/js/core-client/.gitignore b/packages/js/core-client/.gitignore new file mode 100644 index 0000000000..dbb01bb64d --- /dev/null +++ b/packages/js/core-client/.gitignore @@ -0,0 +1,3 @@ +/examples/**/*.d.ts +/examples/**/*.js +/examples/**/*.js.map diff --git a/packages/js/core-client/README.md b/packages/js/core-client/README.md index 17febba20a..b9e74ad8ae 100644 --- a/packages/js/core-client/README.md +++ b/packages/js/core-client/README.md @@ -15,71 +15,32 @@ npm install --save @polywrap/core-client-js ## Usage -### Instantiate the client +### Instantiate + +Use the `@polywrap/client-config-builder-js` package to build a CoreClientConfig for your project, then use the PolywrapCoreClient [constructor](#constructor) to instantiate the client with your config. + ```ts -import { PolywrapCoreClient } from "@polywrap/core-client-js"; + const config = new ClientConfigBuilder().addDefaults().buildCoreConfig(); -const config = { ... }; -const client = new PolywrapCoreClient(config); + const client = new PolywrapCoreClient(config); ``` -### Invoke a wrapper +### Invoke + +Invoke a wrapper. ```ts -await client.invoke({ - uri: "ens/helloworld.dev.polywrap.eth", - method: "logMessage", - args: { - message: "Hello World!" - } -}); -``` + const result = await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } + }); -### Configure the core client + if (!result.ok) throw result.error; -```ts -const config = { - // declare interface implementations - interfaces: [ - { - interface: "wrap://ens/uri-resolver.core.polywrap.eth", - implementations: [ - "wrap://ens/ipfs-resolver.polywrap.eth", - ], - }, - ], - // set environmental variables for a wrapper - envs: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - env: { - provider: "https://ipfs.wrappers.io", - }, - }, - ], - // customize URI resolution by adding redirects and embedded wrappers/packages - resolver: - RecursiveResolver.from( - PackageToWrapperCacheResolver.from( - [ - StaticResolver.from([ - ...redirects, - ...wrappers, - ...packages, - ]), - ...this.config.resolvers, - new ExtendableUriResolver(), - ], - new WrapperCache() - ) - ), - // tracer configuration - see @polywrap/tracing-js package - tracerConfig: { ... }, -}; -``` -```ts -// create a client by modifying the default configuration bundle -const client = new PolywrapCoreClient(config); + const value = result.value; ``` # Reference diff --git a/packages/js/core-client/examples/quickstart.ts b/packages/js/core-client/examples/quickstart.ts new file mode 100644 index 0000000000..753cfc0fb5 --- /dev/null +++ b/packages/js/core-client/examples/quickstart.ts @@ -0,0 +1,33 @@ +import { PolywrapCoreClient } from "../build"; +import { ClientConfigBuilder } from "@polywrap/client-config-builder-js"; + +export function instantiate(): PolywrapCoreClient { + // $start: quickstart-instantiate + const config = new ClientConfigBuilder().addDefaults().buildCoreConfig(); + + const client = new PolywrapCoreClient(config); + // $end + + return client; +} + +export async function invoke(): Promise { + const config = new ClientConfigBuilder().addDefaults().buildCoreConfig(); + + const client = new PolywrapCoreClient(config); + + // $start: quickstart-invoke + const result = await client.invoke({ + uri: "ens/helloworld.dev.polywrap.eth", + method: "logMessage", + args: { + message: "Hello World!" + } + }); + + if (!result.ok) throw result.error; + + const value = result.value; + // $end + return value; +} diff --git a/packages/js/core-client/examples/tsconfig.examples.json b/packages/js/core-client/examples/tsconfig.examples.json new file mode 100644 index 0000000000..f37de53612 --- /dev/null +++ b/packages/js/core-client/examples/tsconfig.examples.json @@ -0,0 +1,6 @@ +{ + "extends": "../tsconfig.json", + "include": [ + "./**/*.ts" + ], +} \ No newline at end of file diff --git a/packages/js/core-client/package.json b/packages/js/core-client/package.json index d797c18c6f..172e8abb74 100644 --- a/packages/js/core-client/package.json +++ b/packages/js/core-client/package.json @@ -12,10 +12,11 @@ "build" ], "scripts": { - "build": "yarn build:fast && yarn build:readme", + "build": "yarn build:fast && yarn build:snippets && yarn build:readme", "build:fast": "rimraf ./build && tsc --project tsconfig.build.json", "lint": "eslint --color -c ../../../.eslintrc.js src/", "test": "jest --passWithNoTests --runInBand --verbose=true --detectOpenHandles --forceExit", + "build:snippets": "tsc --project ./examples/tsconfig.examples.json", "build:readme": "yarn doc-snippets combine" }, "dependencies": { @@ -43,13 +44,16 @@ }, "doc-snippets": { "extract": { - "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "include": [ + "./src/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "./examples/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}" + ], "ignore": [ "./**/node_modules/**", "./**/.polywrap/**", "./**/__tests__/**" ], - "dir": "./src" + "dir": "./" }, "inject": { "dir": "./readme", diff --git a/packages/js/core-client/readme/README.md b/packages/js/core-client/readme/README.md index 1ed9d5bed5..1cf94bd408 100644 --- a/packages/js/core-client/readme/README.md +++ b/packages/js/core-client/readme/README.md @@ -15,71 +15,20 @@ npm install --save @polywrap/core-client-js ## Usage -### Instantiate the client -```ts -import { PolywrapCoreClient } from "@polywrap/core-client-js"; - -const config = { ... }; -const client = new PolywrapCoreClient(config); -``` - -### Invoke a wrapper - -```ts -await client.invoke({ - uri: "ens/helloworld.dev.polywrap.eth", - method: "logMessage", - args: { - message: "Hello World!" - } -}); -``` - -### Configure the core client - -```ts -const config = { - // declare interface implementations - interfaces: [ - { - interface: "wrap://ens/uri-resolver.core.polywrap.eth", - implementations: [ - "wrap://ens/ipfs-resolver.polywrap.eth", - ], - }, - ], - // set environmental variables for a wrapper - envs: [ - { - uri: "wrap://ens/ipfs.polywrap.eth", - env: { - provider: "https://ipfs.wrappers.io", - }, - }, - ], - // customize URI resolution by adding redirects and embedded wrappers/packages - resolver: - RecursiveResolver.from( - PackageToWrapperCacheResolver.from( - [ - StaticResolver.from([ - ...redirects, - ...wrappers, - ...packages, - ]), - ...this.config.resolvers, - new ExtendableUriResolver(), - ], - new WrapperCache() - ) - ), - // tracer configuration - see @polywrap/tracing-js package - tracerConfig: { ... }, -}; -``` -```ts -// create a client by modifying the default configuration bundle -const client = new PolywrapCoreClient(config); +### Instantiate + +Use the `@polywrap/client-config-builder-js` package to build a CoreClientConfig for your project, then use the PolywrapCoreClient [constructor](#constructor) to instantiate the client with your config. + +```ts +$snippet: quickstart-instantiate +``` + +### Invoke + +Invoke a wrapper. + +```ts +$snippet: quickstart-invoke ``` # Reference From a11986c4c5c6fd2fb8dd8d4217200543133d242a Mon Sep 17 00:00:00 2001 From: krisbitney Date: Sat, 14 Jan 2023 23:19:17 +0530 Subject: [PATCH 24/25] added snippets to test-env-js readme intro --- packages/js/client/tsconfig.build.json | 3 + packages/js/client/tsconfig.json | 4 +- packages/js/core-client/tsconfig.build.json | 3 + packages/js/core-client/tsconfig.json | 4 +- packages/js/test-env/.gitignore | 3 + packages/js/test-env/README.md | 108 +++++++----------- packages/js/test-env/examples/quickstart.ts | 49 ++++++++ .../test-env/examples/tsconfig.examples.json | 6 + packages/js/test-env/package.json | 11 +- packages/js/test-env/readme/README.md | 94 ++++----------- packages/js/test-env/tsconfig.build.json | 3 + packages/js/test-env/tsconfig.json | 6 +- 12 files changed, 147 insertions(+), 147 deletions(-) create mode 100644 packages/js/test-env/.gitignore create mode 100644 packages/js/test-env/examples/quickstart.ts create mode 100644 packages/js/test-env/examples/tsconfig.examples.json diff --git a/packages/js/client/tsconfig.build.json b/packages/js/client/tsconfig.build.json index 77aadfdd2f..ec6eea7b58 100644 --- a/packages/js/client/tsconfig.build.json +++ b/packages/js/client/tsconfig.build.json @@ -1,5 +1,8 @@ { "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "build" + }, "include": [ "./src/**/*.ts" ], diff --git a/packages/js/client/tsconfig.json b/packages/js/client/tsconfig.json index a708147fab..61edd1723e 100644 --- a/packages/js/client/tsconfig.json +++ b/packages/js/client/tsconfig.json @@ -7,10 +7,10 @@ "es5", "dom" ], - "outDir": "build" }, "include": [ - "./src/**/*.ts" + "./src/**/*.ts", + "./examples/**/*.ts" ], "exclude": [] } diff --git a/packages/js/core-client/tsconfig.build.json b/packages/js/core-client/tsconfig.build.json index 77aadfdd2f..ec6eea7b58 100644 --- a/packages/js/core-client/tsconfig.build.json +++ b/packages/js/core-client/tsconfig.build.json @@ -1,5 +1,8 @@ { "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "build" + }, "include": [ "./src/**/*.ts" ], diff --git a/packages/js/core-client/tsconfig.json b/packages/js/core-client/tsconfig.json index a708147fab..61edd1723e 100644 --- a/packages/js/core-client/tsconfig.json +++ b/packages/js/core-client/tsconfig.json @@ -7,10 +7,10 @@ "es5", "dom" ], - "outDir": "build" }, "include": [ - "./src/**/*.ts" + "./src/**/*.ts", + "./examples/**/*.ts" ], "exclude": [] } diff --git a/packages/js/test-env/.gitignore b/packages/js/test-env/.gitignore new file mode 100644 index 0000000000..dbb01bb64d --- /dev/null +++ b/packages/js/test-env/.gitignore @@ -0,0 +1,3 @@ +/examples/**/*.d.ts +/examples/**/*.js +/examples/**/*.js.map diff --git a/packages/js/test-env/README.md b/packages/js/test-env/README.md index 75b112f36f..d5960f9cbe 100644 --- a/packages/js/test-env/README.md +++ b/packages/js/test-env/README.md @@ -8,26 +8,27 @@ It allows user to initiate the test environment through a javascript function (i # Usage -Initialization with the simple-storage wrapper. +## Init test env + +Spin up docker containers for Ganache and IPFS. ``` typescript -import path from "path"; -import { PolywrapClient } from "@polywrap/client-js"; -import { - buildWrapper, - initTestEnvironment, - stopTestEnvironment, - providers, - ensAddresses -} from "@polywrap/test-env-js"; -import * as App from "../types/wrap"; - -// test wrapper in a test environment -export async function foo({ - // spin up docker containers for Ganache and IPFS. await initTestEnvironment(); - const CONNECTION = { networkNameOrChainId: "testnet" }; +``` + +## Stop test env + +Stop docker containers for Ganache and IPFS. + +``` typescript + await stopTestEnvironment(); +``` + +## Build a wrapper +Build a local wrapper project. + +``` typescript // get path to the wrapper in testing const wrapperPath: string = path.join(path.resolve(__dirname), ".."); @@ -35,37 +36,18 @@ export async function foo({ await buildWrapper(wrapperPath, undefined, true); // get URI to the local wrapper build - const wrapperUri = `fs/${wrapperPath}/build`; - - // invoke the wrapper to deploy a contract to the test env - const deployContractResponse = await App.SimpleStorage_Module.deployContract( - { connection: CONNECTION }, - client, - wrapperUri - ); - const contractAddress = deployContractResponse.data as string; - - // invoke the wrapper to query a contract in the test env - const response = await App.SimpleStorage_Module.getData( - { - address: contractAddr, - connection: CONNECTION, - }, - client, - wrapperUri - ); -}); - + const wrapperUri = `wrap://fs/${wrapperPath}/build`; ``` -# API Outline +## Execute the CLI -- ensAddresses, providers - constant addresses and urls -- runCLI - run arbitrary Polywrap CLI commands -- initTestEnvironment - spin up Ganache and IPFS Docker instances -- stopTestEnvironment - stop Docker -- buildWrapper - compile wasm and bindings -- buildAndDeployWrapper - deploy wrapper to the testnet ENS +Execute a command with the Polywrap CLI. + +``` typescript + const { exitCode, stderr, stdout } = await runCLI({ + args: ["infra", "up", "--verbose"], + }); +``` ## Constants @@ -138,11 +120,13 @@ export const stopTestEnvironment = async ( * Build the wrapper located at the given path * * @param wrapperAbsPath - absolute path of wrapper to build - * @param manifestPathOverride? - path to p + * @param manifestPathOverride? - path to polywrap manifest + * @param codegen? - run codegen before build */ export async function buildWrapper( wrapperAbsPath: string, - manifestPathOverride?: string + manifestPathOverride?: string, + codegen?: boolean ): Promise ``` @@ -157,6 +141,7 @@ export async function buildWrapper( * @param ipfsProvider - ipfs provider to use for deployment * @param ethereumProvider - ethereum provider to use for ENS registration * @param ensName? - an ENS domain name to register and assign to the wrapper + * @param codegen? - run codegen before build * * @returns registered ens domain name and IPFS hash */ @@ -165,28 +150,19 @@ export async function buildAndDeployWrapper({ ipfsProvider, ethereumProvider, ensName, + codegen, }: { wrapperAbsPath: string; ipfsProvider: string; ethereumProvider: string; ensName?: string; + codegen?: boolean; }): Promise<{ ensDomain: string; ipfsCid: string; }> ``` -```typescript title="Example: buildAndDeployWrapper with default infrastructure module" -import { buildAndDeployWrapper, providers } from "@polywrap/test-env-js"; - -const { ensDomain, ipfsCid } = await buildAndDeployWrapper({ - wrapperAbsPath: "...", - ipfsProvider: providers.ipfs, - ethereumProvider: providers.ethereum, -}); -const ensUri = `ens/testnet/${ensDomain}`; -``` - ### buildAndDeployWrapperToHttp ```typescript @@ -197,6 +173,7 @@ const ensUri = `ens/testnet/${ensDomain}`; * @param wrapperAbsPath - absolute path of wrapper to build * @param httpProvider - http provider used for deployment and domain registration * @param name? - a domain name to register and assign to the wrapper + * @param codegen? - run codegen before build * * @returns http uri */ @@ -204,10 +181,12 @@ export async function buildAndDeployWrapperToHttp({ wrapperAbsPath, httpProvider, name, + codegen, }: { wrapperAbsPath: string; httpProvider: string; name?: string; + codegen?: boolean; }): Promise<{ uri: string }> ``` @@ -217,10 +196,11 @@ export async function buildAndDeployWrapperToHttp({ /** * Runs the polywrap CLI programmatically. * - * @param args - an array of command line arguments - * @param cwd? - a current working directory - * @param cli? - a path to a Polywrap CLI binary - * @param env? - a map of environmental variables + * @param options - an object containing: + * args - an array of command line arguments + * cwd? - a current working directory + * cli? - a path to a Polywrap CLI binary + * env? - a map of environmental variables * * @returns exit code, standard output, and standard error logs */ @@ -234,10 +214,4 @@ export const runCLI = async (options: { stdout: string; stderr: string; }> -``` - -```typescript title="Example: runCLI calling the 'infra' command" -const { exitCode, stderr, stdout } = await runCLI({ - args: ["infra", "up", "--modules=eth-ens-ipfs", "--verbose"] -}); ``` \ No newline at end of file diff --git a/packages/js/test-env/examples/quickstart.ts b/packages/js/test-env/examples/quickstart.ts new file mode 100644 index 0000000000..4bfb9044f0 --- /dev/null +++ b/packages/js/test-env/examples/quickstart.ts @@ -0,0 +1,49 @@ +import { + buildWrapper, + initTestEnvironment, + runCLI, + stopTestEnvironment, +} from "../build"; + +import path from "path"; + +export async function init(): Promise { + // $start: quickstart-init + await initTestEnvironment(); + // $end +} + +export async function stop(): Promise { + // $start: quickstart-stop + await stopTestEnvironment(); + // $end +} + +export async function build(): Promise { + // $start: quickstart-build + // get path to the wrapper in testing + const wrapperPath: string = path.join(path.resolve(__dirname), ".."); + + // build current wrapper with CLI, invoking codegen before build + await buildWrapper(wrapperPath, undefined, true); + + // get URI to the local wrapper build + const wrapperUri = `wrap://fs/${wrapperPath}/build`; + // $end + + return wrapperUri; +} + +export async function cli(): Promise<{ + exitCode: number; + stdout: string; + stderr: string; +}> { + // $start: quickstart-runCLI + const { exitCode, stderr, stdout } = await runCLI({ + args: ["infra", "up", "--verbose"], + }); + // $end + + return { exitCode, stderr, stdout }; +} diff --git a/packages/js/test-env/examples/tsconfig.examples.json b/packages/js/test-env/examples/tsconfig.examples.json new file mode 100644 index 0000000000..f37de53612 --- /dev/null +++ b/packages/js/test-env/examples/tsconfig.examples.json @@ -0,0 +1,6 @@ +{ + "extends": "../tsconfig.json", + "include": [ + "./**/*.ts" + ], +} \ No newline at end of file diff --git a/packages/js/test-env/package.json b/packages/js/test-env/package.json index 602d93a2cf..871986e5b4 100644 --- a/packages/js/test-env/package.json +++ b/packages/js/test-env/package.json @@ -12,9 +12,11 @@ "build" ], "scripts": { - "build": "rimraf ./build && tsc --project tsconfig.build.json && yarn copy:wrappers", + "build": "yarn build:fast && yarn build:snippets && yarn build:readme", + "build:fast": "rimraf ./build && tsc --project tsconfig.build.json && yarn copy:wrappers", "lint": "eslint --color -c ../../../.eslintrc.js src/", "copy:wrappers": "copyfiles ./src/wrappers/**/**/* ./build/wrappers/ -u 2", + "build:snippets": "tsc --project ./examples/tsconfig.examples.json", "build:readme": "yarn doc-snippets combine" }, "dependencies": { @@ -37,13 +39,16 @@ }, "doc-snippets": { "extract": { - "include": "./**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "include": [ + "./src/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}", + "./examples/**/*.{ts,tsx,json,yaml,txt,md,graphql,cue}" + ], "ignore": [ "./**/node_modules/**", "./**/.polywrap/**", "./**/__tests__/**" ], - "dir": "./src" + "dir": "./" }, "inject": { "dir": "./readme", diff --git a/packages/js/test-env/readme/README.md b/packages/js/test-env/readme/README.md index f73e87054f..e7c33cf883 100644 --- a/packages/js/test-env/readme/README.md +++ b/packages/js/test-env/readme/README.md @@ -8,64 +8,37 @@ It allows user to initiate the test environment through a javascript function (i # Usage -Initialization with the simple-storage wrapper. +## Init test env + +Spin up docker containers for Ganache and IPFS. ``` typescript -import path from "path"; -import { PolywrapClient } from "@polywrap/client-js"; -import { - buildWrapper, - initTestEnvironment, - stopTestEnvironment, - providers, - ensAddresses -} from "@polywrap/test-env-js"; -import * as App from "../types/wrap"; - -// test wrapper in a test environment -export async function foo({ - // spin up docker containers for Ganache and IPFS. - await initTestEnvironment(); - const CONNECTION = { networkNameOrChainId: "testnet" }; - - // get path to the wrapper in testing - const wrapperPath: string = path.join(path.resolve(__dirname), ".."); - - // build current wrapper with CLI - await buildWrapper(wrapperPath); - - // get URI to the local wrapper build - const wrapperUri = `fs/${wrapperPath}/build`; - - // invoke the wrapper to deploy a contract to the test env - const deployContractResponse = await App.SimpleStorage_Module.deployContract( - { connection: CONNECTION }, - client, - wrapperUri - ); - const contractAddress = deployContractResponse.data as string; - - // invoke the wrapper to query a contract in the test env - const response = await App.SimpleStorage_Module.getData( - { - address: contractAddr, - connection: CONNECTION, - }, - client, - wrapperUri - ); -}); +$snippet: quickstart-init +``` + +## Stop test env + +Stop docker containers for Ganache and IPFS. + +``` typescript +$snippet: quickstart-stop +``` + +## Build a wrapper + +Build a local wrapper project. +``` typescript +$snippet: quickstart-build ``` -# API Outline +## Execute the CLI -- ensAddresses, providers - constant addresses and urls -- runCLI - run arbitrary Polywrap CLI commands -- initTestEnvironment - spin up Ganache and IPFS Docker instances -- stopTestEnvironment - stop Docker -- buildWrapper - compile wasm and bindings -- buildAndDeployWrapper - deploy wrapper to the testnet ENS +Execute a command with the Polywrap CLI. + +``` typescript +$snippet: quickstart-runCLI +``` ## Constants @@ -113,17 +86,6 @@ $snippet: buildWrapper $snippet: buildAndDeployWrapper ``` -```typescript title="Example: buildAndDeployWrapper with default infrastructure module" -import { buildAndDeployWrapper, providers } from "@polywrap/test-env-js"; - -const { ensDomain, ipfsCid } = await buildAndDeployWrapper({ - wrapperAbsPath: "...", - ipfsProvider: providers.ipfs, - ethereumProvider: providers.ethereum, -}); -const ensUri = `ens/testnet/${ensDomain}`; -``` - ### buildAndDeployWrapperToHttp ```typescript @@ -134,10 +96,4 @@ $snippet: buildAndDeployWrapperToHttp ```typescript $snippet: runCLI -``` - -```typescript title="Example: runCLI calling the 'infra' command" -const { exitCode, stderr, stdout } = await runCLI({ - args: ["infra", "up", "--modules=eth-ens-ipfs", "--verbose"] -}); ``` \ No newline at end of file diff --git a/packages/js/test-env/tsconfig.build.json b/packages/js/test-env/tsconfig.build.json index 77aadfdd2f..ec6eea7b58 100644 --- a/packages/js/test-env/tsconfig.build.json +++ b/packages/js/test-env/tsconfig.build.json @@ -1,5 +1,8 @@ { "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "build" + }, "include": [ "./src/**/*.ts" ], diff --git a/packages/js/test-env/tsconfig.json b/packages/js/test-env/tsconfig.json index 5d37204c00..02827831c0 100644 --- a/packages/js/test-env/tsconfig.json +++ b/packages/js/test-env/tsconfig.json @@ -1,10 +1,8 @@ { "extends": "../../../tsconfig", - "compilerOptions": { - "outDir": "build" - }, "include": [ - "./src/**/*.ts" + "./src/**/*.ts", + "./examples/**/*.ts" ], "exclude": [] } From 66ceb487b4679e317a38944e332331a6c17113ae Mon Sep 17 00:00:00 2001 From: krisbitney Date: Thu, 19 Jan 2023 15:04:28 +0530 Subject: [PATCH 25/25] readme updates --- packages/js/client-config-builder/README.md | 8 ++++---- packages/js/core/README.md | 8 +++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/packages/js/client-config-builder/README.md b/packages/js/client-config-builder/README.md index 879f632250..0daa99d9fa 100644 --- a/packages/js/client-config-builder/README.md +++ b/packages/js/client-config-builder/README.md @@ -223,12 +223,12 @@ export interface ClientConfig { /** * Instantiate a ClientConfigBuilder * - * @param wrapperCache?: a wrapper cache to be used in place of the default wrapper cache - * @param resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig + * @param _wrapperCache?: a wrapper cache to be used in place of the default wrapper cache + * @param _resolver?: a uri resolver to be used in place of any added redirects, wrappers, packages, and resolvers when building a CoreClientConfig */ constructor( - private readonly wrapperCache?: IWrapperCache, - private readonly resolver?: IUriResolver + private readonly _wrapperCache?: IWrapperCache, + private readonly _resolver?: IUriResolver ) ``` diff --git a/packages/js/core/README.md b/packages/js/core/README.md index 7dbcb78286..e00128685f 100644 --- a/packages/js/core/README.md +++ b/packages/js/core/README.md @@ -558,10 +558,10 @@ export interface Wrapper extends Invocable { /** Contains either a Uri, a manifest, or neither */ export interface MaybeUriOrManifest { /** wrap URI */ - uri?: string; + uri?: string | null; /** Serialized wrap manifest */ - manifest?: Uint8Array; + manifest?: Uint8Array | null; } ``` @@ -600,7 +600,7 @@ export interface MaybeUriOrManifest { invoker: Invoker, wrapper: Uri, path: string - ): Promise> + ): Promise> ``` ## Uri Resolution @@ -730,6 +730,8 @@ export type UriPackageOrWrapper = UriValue | UriPackageValue | UriWrapperValue; ```ts /** An implementation of the IUriResolutionContext interface */ +// $start: UriResolutionContext +/** An implementation of the IUriResolutionContext interface */ export class UriResolutionContext implements IUriResolutionContext { ```