From 3f5b8e547dffb7fbc4027c67c38dcd2f126109ff Mon Sep 17 00:00:00 2001 From: NathanosDev Date: Sat, 10 Feb 2024 19:04:11 +0100 Subject: [PATCH] docs: update examples to use DFX v0.16.1 --- dfx.json | 17 +++++++++--- examples/clock/tests/clock/index.d.ts | 9 ------ examples/clock/tests/clock/index.js | 1 - examples/clock/tests/src/clock.spec.ts | 12 ++++---- examples/counter/tests/counter/index.d.ts | 9 ------ examples/counter/tests/counter/index.js | 1 - examples/counter/tests/src/counter.spec.ts | 8 +++--- examples/todo/tests/src/todo.spec.ts | 8 +++--- examples/todo/tests/todo/index.d.ts | 9 ------ examples/todo/tests/todo/index.js | 1 - packages/pic/README.md | 32 +++++++++++----------- 11 files changed, 43 insertions(+), 64 deletions(-) delete mode 100644 examples/clock/tests/clock/index.d.ts delete mode 100644 examples/clock/tests/clock/index.js delete mode 100644 examples/counter/tests/counter/index.d.ts delete mode 100644 examples/counter/tests/counter/index.js delete mode 100644 examples/todo/tests/todo/index.d.ts delete mode 100644 examples/todo/tests/todo/index.js diff --git a/dfx.json b/dfx.json index af933fd..5618cc8 100644 --- a/dfx.json +++ b/dfx.json @@ -1,4 +1,16 @@ { + "version": 1, + "dfx": "0.16.1", + "output_env_file": ".env", + "networks": { + "local": { + "bind": "127.0.0.1:8080", + "type": "ephemeral", + "replica": { + "subnet_type": "system" + } + } + }, "canisters": { "counter": { "main": "examples/counter/src/main.mo", @@ -28,8 +40,5 @@ "output": "examples/todo/declarations" } } - }, - "output_env_file": ".env", - "dfx": "0.15.2", - "version": 1 + } } diff --git a/examples/clock/tests/clock/index.d.ts b/examples/clock/tests/clock/index.d.ts deleted file mode 100644 index 8d2d471..0000000 --- a/examples/clock/tests/clock/index.d.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { IDL } from '@dfinity/candid'; -import { Actor } from '@hadronous/pic'; -import { _SERVICE } from '../../declarations/clock.did'; - -export declare const idlFactory: IDL.InterfaceFactory; -export declare const init: ({ IDL }: { IDL: IDL }) => IDL.Type[]; - -export declare type ClockService = _SERVICE; -export declare type ClockActor = Actor; diff --git a/examples/clock/tests/clock/index.js b/examples/clock/tests/clock/index.js deleted file mode 100644 index f1f44c3..0000000 --- a/examples/clock/tests/clock/index.js +++ /dev/null @@ -1 +0,0 @@ -export { idlFactory, init } from '../../declarations/clock.did'; diff --git a/examples/clock/tests/src/clock.spec.ts b/examples/clock/tests/src/clock.spec.ts index f581560..aede16c 100644 --- a/examples/clock/tests/src/clock.spec.ts +++ b/examples/clock/tests/src/clock.spec.ts @@ -1,7 +1,7 @@ import { resolve } from 'node:path'; import { Principal } from '@dfinity/principal'; -import { PocketIc } from '@hadronous/pic'; -import { ClockActor, idlFactory, ClockService } from '../clock'; +import { Actor, PocketIc } from '@hadronous/pic'; +import { _SERVICE, idlFactory } from '../../declarations/clock.did'; const WASM_PATH = resolve( __dirname, @@ -17,14 +17,14 @@ const WASM_PATH = resolve( ); describe('Clock', () => { - let actor: ClockActor; + let actor: Actor<_SERVICE>; let pic: PocketIc; let canisterId: Principal; beforeEach(async () => { pic = await PocketIc.create(); - const fixture = await pic.setupCanister({ - idlFactory, + const fixture = await pic.setupCanister<_SERVICE>({ + idlFactory: idlFactory, wasm: WASM_PATH, }); actor = fixture.actor; @@ -51,7 +51,7 @@ describe('Clock', () => { it('should set and get canister cycles', async () => { const cycles = await pic.getCyclesBalance(canisterId); - const cyclesToAdd = 1_000_000; + const cyclesToAdd = 1_000_000_000; const updatedCyclesBalance = await pic.addCycles(canisterId, cyclesToAdd); const fetchUpdatedCyclesBalance = await pic.getCyclesBalance(canisterId); diff --git a/examples/counter/tests/counter/index.d.ts b/examples/counter/tests/counter/index.d.ts deleted file mode 100644 index 52b56d9..0000000 --- a/examples/counter/tests/counter/index.d.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { IDL } from '@dfinity/candid'; -import { Actor } from '@hadronous/pic'; -import { _SERVICE } from '../../declarations/counter.did'; - -export declare const idlFactory: IDL.InterfaceFactory; -export declare const init: ({ IDL }: { IDL: IDL }) => IDL.Type[]; - -export declare type CounterService = _SERVICE; -export declare type CounterActor = Actor; diff --git a/examples/counter/tests/counter/index.js b/examples/counter/tests/counter/index.js deleted file mode 100644 index 19ec201..0000000 --- a/examples/counter/tests/counter/index.js +++ /dev/null @@ -1 +0,0 @@ -export { idlFactory, init } from '../../declarations/counter.did'; diff --git a/examples/counter/tests/src/counter.spec.ts b/examples/counter/tests/src/counter.spec.ts index 47d81ac..94f284f 100644 --- a/examples/counter/tests/src/counter.spec.ts +++ b/examples/counter/tests/src/counter.spec.ts @@ -1,8 +1,8 @@ import { resolve } from 'node:path'; import { Principal } from '@dfinity/principal'; -import { PocketIc } from '@hadronous/pic'; -import { CounterActor, idlFactory, CounterService, init } from '../counter'; +import { Actor, PocketIc } from '@hadronous/pic'; import { IDL } from '@dfinity/candid'; +import { _SERVICE, idlFactory, init } from '../../declarations/counter.did'; const WASM_PATH = resolve( __dirname, @@ -19,14 +19,14 @@ const WASM_PATH = resolve( describe('Counter', () => { let pic: PocketIc; - let actor: CounterActor; + let actor: Actor<_SERVICE>; let canisterId: Principal; const countInitArg = 1n; beforeEach(async () => { pic = await PocketIc.create(); - const fixture = await pic.setupCanister({ + const fixture = await pic.setupCanister<_SERVICE>({ idlFactory, wasm: WASM_PATH, arg: IDL.encode(init({ IDL }), [countInitArg]), diff --git a/examples/todo/tests/src/todo.spec.ts b/examples/todo/tests/src/todo.spec.ts index 36c0c90..405091e 100644 --- a/examples/todo/tests/src/todo.spec.ts +++ b/examples/todo/tests/src/todo.spec.ts @@ -1,8 +1,8 @@ import { resolve } from 'node:path'; import { Principal } from '@dfinity/principal'; import { AnonymousIdentity } from '@dfinity/agent'; -import { PocketIc, createIdentity } from '@hadronous/pic'; -import { TodoActor, idlFactory, TodoService } from '../todo'; +import { Actor, PocketIc, createIdentity } from '@hadronous/pic'; +import { _SERVICE, idlFactory } from '../../declarations/todo.did'; const WASM_PATH = resolve( __dirname, @@ -19,7 +19,7 @@ const WASM_PATH = resolve( describe('Todo', () => { let pic: PocketIc; - let actor: TodoActor; + let actor: Actor<_SERVICE>; let canisterId: Principal; const alice = createIdentity('superSecretAlicePassword'); @@ -27,7 +27,7 @@ describe('Todo', () => { beforeEach(async () => { pic = await PocketIc.create(); - const fixture = await pic.setupCanister({ + const fixture = await pic.setupCanister<_SERVICE>({ idlFactory, wasm: WASM_PATH, }); diff --git a/examples/todo/tests/todo/index.d.ts b/examples/todo/tests/todo/index.d.ts deleted file mode 100644 index 3731c48..0000000 --- a/examples/todo/tests/todo/index.d.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { IDL } from '@dfinity/candid'; -import { Actor } from '@hadronous/pic'; -import { _SERVICE } from '../../declarations/todo.did'; - -export declare const idlFactory: IDL.InterfaceFactory; -export declare const init: ({ IDL }: { IDL: IDL }) => IDL.Type[]; - -export declare type TodoService = _SERVICE; -export declare type TodoActor = Actor; diff --git a/examples/todo/tests/todo/index.js b/examples/todo/tests/todo/index.js deleted file mode 100644 index ace58cd..0000000 --- a/examples/todo/tests/todo/index.js +++ /dev/null @@ -1 +0,0 @@ -export { idlFactory, init } from '../../declarations/todo.did'; diff --git a/packages/pic/README.md b/packages/pic/README.md index d6261c6..b3d521e 100644 --- a/packages/pic/README.md +++ b/packages/pic/README.md @@ -69,9 +69,24 @@ PicJS leverages a [`postinstall`](https://docs.npmjs.com/cli/v9/using-npm/script } ``` +## API Docs + +More detailed documentation is available in the [API docs](https://hadronous.github.io/pic-js/). The best place to start is with the [PocketIc](https://hadronous.github.io/pic-js/classes/PocketIc.html) class and then move on to the [Actor](https://hadronous.github.io/pic-js/interfaces/Actor.html) class. + +## Examples + +All examples are written in [TypeScript](https://www.typescriptlang.org/) with [Jest](https://jestjs.io/) as the test runner, +but `@hadronous/pic` can be used with JavaScript and any other testing runner, such as [NodeJS](https://nodejs.org/dist/latest-v20.x/docs/api/test.html), [bun](https://bun.sh/docs/cli/test) or [Mocha](https://mochajs.org/). + +- The [Counter](https://github.com/hadronous/pic-js/tree/main/examples/counter/README.md) example demonstrates how to work with a simple canister as well as init arguments, canister upgrades and WASM reinstallation. +- The [Clock](https://github.com/hadronous/pic-js/tree/main/examples/clock/README.md) example demonstrates how to work with the replica's system time, canister timers as well as checking for canister existence and cycle management. +- The [Todo](https://github.com/hadronous/pic-js/tree/main/examples/todo/README.md) example demonstrates how to work with more complex canisters, identities, canister upgrades, and stable memory management. + ## Canister Declarations -The DFX auto-generated bindings for canisters have some issues that make the developer experience with PicJS less than ideal. There are four files generated by DFX for a canister. To use a `counter` canister as an example: +The DFX auto-generated bindings for canisters had some issues in versions of DFX lower than `0.16.0` that made the developer experience with PicJS less than ideal. If you are using DFX v`0.16.0` or higher then you can ignore this section. + +There are four files generated by DFX for a canister. To use a `counter` canister as an example: - `counter.did.js` - Exports the canister's Candid as a JavaScript object. The `idlFactory` and `init` exports in this file are not included in the `counter.did.d.ts` file. @@ -171,18 +186,3 @@ Fixes for these issues are already merged into Candid, but they need to be relea export declare const idlFactory: IDL.InterfaceFactory; export declare const init: ({ IDL }: { IDL: IDL }) => IDL.Type[]; ``` - -Examples of this fix can be found for each of the examples in the [examples](#examples) section. - -## API Docs - -More detailed documentation is available in the [API docs](https://hadronous.github.io/pic-js/). The best place to start is with the [PocketIc](https://hadronous.github.io/pic-js/classes/PocketIc.html) class and then move on to the [Actor](https://hadronous.github.io/pic-js/interfaces/Actor.html) class. - -## Examples - -All examples are written in [TypeScript](https://www.typescriptlang.org/) with [Jest](https://jestjs.io/) as the test runner, -but `@hadronous/pic` can be used with JavaScript and any other testing runner, such as [NodeJS](https://nodejs.org/dist/latest-v20.x/docs/api/test.html), [bun](https://bun.sh/docs/cli/test) or [Mocha](https://mochajs.org/). - -- The [Counter](https://github.com/hadronous/pic-js/tree/main/examples/counter/README.md) example demonstrates how to work with a simple canister as well as init arguments, canister upgrades and WASM reinstallation. -- The [Clock](https://github.com/hadronous/pic-js/tree/main/examples/clock/README.md) example demonstrates how to work with the replica's system time, canister timers as well as checking for canister existence and cycle management. -- The [Todo](https://github.com/hadronous/pic-js/tree/main/examples/todo/README.md) example demonstrates how to work with more complex canisters, identities, canister upgrades, and stable memory management.