@taqueria/plugin-contract-types 0.0.0-pr-726-e060c010 → 0.0.0-pr-704-5f019876

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +125 -0
  2. package/_readme.eta +128 -0
  3. package/package.json +1 -1
  4. package/Readme.md +0 -259
package/README.md ADDED
@@ -0,0 +1,125 @@
1
+ # Taqueria Contract Types Plugin
2
+
3
+ This plugin provides a `taq generate types` command which will generate and export TypeScript types from compiled Michelson smart contracts. These generated types then work with your IDE and Taquito, providing type safety and an improved code authoring experience
4
+
5
+ Benefits of using generated types:
6
+ - Static types used to call smart contract methods are checked at compile time, improving code reliability
7
+ - Generated types enable auto-completion and syntax highlighting in your IDE
8
+ - Developing apps with Taquito is faster and more reliable
9
+ - The VS Code Extension provides tooltip hints for parameter types used to call a smart contract method
10
+ - Calling smart contract methods with types is done directly, removing the need for utility methods
11
+ - Simplifies your code and improves readability
12
+
13
+ ## Requirements
14
+
15
+ - Node JS v16 or later
16
+ - Taquito v11.2 or later (optional)
17
+
18
+ ## Installation
19
+
20
+ To install the Contract Types plugin on a Taqueria project, navigate to the project folder and run:
21
+ ```shell
22
+ taq install @taqueria/plugin-contract-types
23
+ ```
24
+
25
+ ## Configuration
26
+
27
+ This plugin will look for Michelson files according to the `artifactsDir` configured in `./.taq/config.json`. By default, this value is `/artifacts` but can be changed as needed
28
+
29
+ ## Usage
30
+
31
+ The plugin provides a single command to Taqueria: `taq generate types`
32
+
33
+ This will look for `.tz` files in the `/artifacts` directory and will generate a series of related `.ts` files in the `/types` directory. These files export type definitions for each method which can then be used by Taquito and your IDE
34
+
35
+ ### The `generate types` Command
36
+
37
+ #### Syntax
38
+ ```shell
39
+ taq generate types [typeOutputDir]
40
+ ```
41
+
42
+ #### Parameters
43
+
44
+ | parameter | required | description |
45
+ |:-------------:|:-----------|----------------------------------------------------|
46
+ | typeOutputDir | no | The output directory for the `.ts` files generated |
47
+
48
+ #### CLI Aliases
49
+
50
+ The following aliases are interchangable with `generate types`
51
+ - `gen`
52
+ - `gentypes`
53
+
54
+ #### Options
55
+
56
+ The `generate types` command will accept the following optional parameters:
57
+
58
+ | flag | name | description |
59
+ |:-----:|:--------------|----------------------------------------------|
60
+ | -t | typeAliasMode | Use type aliases in the generated types |
61
+
62
+
63
+ ## Taquito Workflow Improvements
64
+
65
+ The generated TS types can be used in a Taquito project which provides an improved developing experience, and simplifies the way types are provided to Taquito method calls. Some examples of how these changes are put into use are detailed below
66
+
67
+ > ### :page_with_curl: Note
68
+ > You can view the full example in the `example-usage.ts` file on Github: [taqueria/taqueria-plugin-contract-types/example](https://github.com/ecadlabs/taqueria/blob/main/taqueria-plugin-contract-types/example/example-usage.ts)
69
+
70
+ ### Calling the `.at` Method of a Contract
71
+
72
+ Traditionally, calling the `.at` method of a contract with Taquito required the developer to pass the parameter's type via a utility method:
73
+ ```ts Utility Method
74
+ const contract = await Tezos.contract.at(`KT123...`, contractAbstractionComposer<TestContractType>());
75
+ ```
76
+ or a cast:
77
+ ```ts Cast
78
+ const contract = await Tezos.contract.at(`KT123...`) as ContractProviderFromContractType<TestContractType>;
79
+ ```
80
+
81
+ When using generated types, the developer can now directly use the type in the call to `.at`:
82
+ ```ts
83
+ const contract = await Tezos.contract.at<TestContract>(`KT123...`);
84
+ ```
85
+
86
+ ### Using a Wallet
87
+
88
+ Using a wallet is simplified in a similar way:
89
+ ```ts
90
+ const contract = await Tezos.wallet.at(`KT123...`, walletAbstractionComposer<TestContractType>());
91
+ ```
92
+
93
+ Becomes:
94
+ ```ts
95
+ const contract = await Tezos.wallet.at<TestWalletContract>(`KT123...`);
96
+ ```
97
+
98
+ ### Contract Origination
99
+
100
+ The Taquito contract origination did not have any way to provide a type, so this used to require a cast:
101
+ ```ts
102
+ const originationResult = await Tezos.contract.originate({...});
103
+ const contract = await originationResult.contract(5) as ContractProviderFromContractType<TestContractType2>;
104
+ ```
105
+
106
+ Now, it can directly accept a type:
107
+ ```ts
108
+ const originationResult = await Tezos.contract.originate({...});
109
+ const contract = await originationResult.contract<TestContract2>(5);
110
+ ```
111
+
112
+
113
+ ### Storage
114
+
115
+ When accessing storage, there was no way to pass the type through the contract class. This required providing the type a second time:
116
+ ```ts
117
+ const contract = await Tezos.contract.at(`KT123...`) as ContractProviderFromContractType<TestContractType>;
118
+ const storage = await contract.storage<StorageFromContractType<TestContractType>>();
119
+ ```
120
+
121
+ Now, the contract type provides the default storage type:
122
+ ```ts
123
+ const contract = await Tezos.contract.at<TestContract>(`KT123...`);
124
+ const storage = await contract.storage();
125
+ ```
package/_readme.eta ADDED
@@ -0,0 +1,128 @@
1
+ <% if (it.output == "github") { %>
2
+ # Taqueria Contract Types Plugin
3
+ <% } %>
4
+
5
+ This plugin provides a `taq generate types` command which will generate and export TypeScript types from compiled Michelson smart contracts. These generated types then work with your IDE and Taquito, providing type safety and an improved code authoring experience
6
+
7
+ Benefits of using generated types:
8
+ - Static types used to call smart contract methods are checked at compile time, improving code reliability
9
+ - Generated types enable auto-completion and syntax highlighting in your IDE
10
+ - Developing apps with Taquito is faster and more reliable
11
+ - The VS Code Extension provides tooltip hints for parameter types used to call a smart contract method
12
+ - Calling smart contract methods with types is done directly, removing the need for utility methods
13
+ - Simplifies your code and improves readability
14
+
15
+ ## Requirements
16
+
17
+ - Node JS v16 or later
18
+ - Taquito v11.2 or later (optional)
19
+
20
+ ## Installation
21
+
22
+ To install the Contract Types plugin on a Taqueria project, navigate to the project folder and run:
23
+ ```shell
24
+ taq install @taqueria/plugin-contract-types
25
+ ```
26
+
27
+ ## Configuration
28
+
29
+ This plugin will look for Michelson files according to the `artifactsDir` configured in `./.taq/config.json`. By default, this value is `/artifacts` but can be changed as needed
30
+
31
+ ## Usage
32
+
33
+ The plugin provides a single command to Taqueria: `taq generate types`
34
+
35
+ This will look for `.tz` files in the `/artifacts` directory and will generate a series of related `.ts` files in the `/types` directory. These files export type definitions for each method which can then be used by Taquito and your IDE
36
+
37
+ ### The `generate types` Command
38
+
39
+ #### Syntax
40
+ ```shell
41
+ taq generate types [typeOutputDir]
42
+ ```
43
+
44
+ #### Parameters
45
+
46
+ | parameter | required | description |
47
+ |:-------------:|:-----------|----------------------------------------------------|
48
+ | typeOutputDir | no | The output directory for the `.ts` files generated |
49
+
50
+ #### CLI Aliases
51
+
52
+ The following aliases are interchangable with `generate types`
53
+ - `gen`
54
+ - `gentypes`
55
+
56
+ #### Options
57
+
58
+ The `generate types` command will accept the following optional parameters:
59
+
60
+ | flag | name | description |
61
+ |:-----:|:--------------|----------------------------------------------|
62
+ | -t | typeAliasMode | Use type aliases in the generated types |
63
+
64
+
65
+ ## Taquito Workflow Improvements
66
+
67
+ The generated TS types can be used in a Taquito project which provides an improved developing experience, and simplifies the way types are provided to Taquito method calls. Some examples of how these changes are put into use are detailed below
68
+
69
+ <%~ it.noteOpenAdmonition %>
70
+ You can view the full example in the `example-usage.ts` file on Github: [taqueria/taqueria-plugin-contract-types/example](https://github.com/ecadlabs/taqueria/blob/main/taqueria-plugin-contract-types/example/example-usage.ts)
71
+ <%= it.closeAdmonition %>
72
+
73
+ ### Calling the `.at` Method of a Contract
74
+
75
+ Traditionally, calling the `.at` method of a contract with Taquito required the developer to pass the parameter's type via a utility method:
76
+ ```ts Utility Method
77
+ const contract = await Tezos.contract.at(`KT123...`, contractAbstractionComposer<TestContractType>());
78
+ ```
79
+ or a cast:
80
+ ```ts Cast
81
+ const contract = await Tezos.contract.at(`KT123...`) as ContractProviderFromContractType<TestContractType>;
82
+ ```
83
+
84
+ When using generated types, the developer can now directly use the type in the call to `.at`:
85
+ ```ts
86
+ const contract = await Tezos.contract.at<TestContract>(`KT123...`);
87
+ ```
88
+
89
+ ### Using a Wallet
90
+
91
+ Using a wallet is simplified in a similar way:
92
+ ```ts
93
+ const contract = await Tezos.wallet.at(`KT123...`, walletAbstractionComposer<TestContractType>());
94
+ ```
95
+
96
+ Becomes:
97
+ ```ts
98
+ const contract = await Tezos.wallet.at<TestWalletContract>(`KT123...`);
99
+ ```
100
+
101
+ ### Contract Origination
102
+
103
+ The Taquito contract origination did not have any way to provide a type, so this used to require a cast:
104
+ ```ts
105
+ const originationResult = await Tezos.contract.originate({...});
106
+ const contract = await originationResult.contract(5) as ContractProviderFromContractType<TestContractType2>;
107
+ ```
108
+
109
+ Now, it can directly accept a type:
110
+ ```ts
111
+ const originationResult = await Tezos.contract.originate({...});
112
+ const contract = await originationResult.contract<TestContract2>(5);
113
+ ```
114
+
115
+
116
+ ### Storage
117
+
118
+ When accessing storage, there was no way to pass the type through the contract class. This required providing the type a second time:
119
+ ```ts
120
+ const contract = await Tezos.contract.at(`KT123...`) as ContractProviderFromContractType<TestContractType>;
121
+ const storage = await contract.storage<StorageFromContractType<TestContractType>>();
122
+ ```
123
+
124
+ Now, the contract type provides the default storage type:
125
+ ```ts
126
+ const contract = await Tezos.contract.at<TestContract>(`KT123...`);
127
+ const storage = await contract.storage();
128
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@taqueria/plugin-contract-types",
3
- "version": "0.0.0-pr-726-e060c010",
3
+ "version": "0.0.0-pr-704-5f019876",
4
4
  "description": "",
5
5
  "targets": {
6
6
  "default": {
package/Readme.md DELETED
@@ -1,259 +0,0 @@
1
- This plugin provides a `taq generate types` command which will generate and export TypeScript types from compiled Michelson smart contracts. These generated types then work with your IDE and Taquito, providing type safety and an improved code authoring experience
2
-
3
- Benefits of using generated types:
4
- - Static types used to call smart contract methods are checked at compile time, improving code reliability
5
- - Generated types enable auto-completion and syntax highlighting in your IDE
6
- - Developing apps with Taquito is faster and more reliable
7
- - The VS Code Extension provides tooltip hints for parameter types used to call a smart contract method
8
- - Calling smart contract methods with types is done directly, removing the need for utility methods
9
- - Simplifies your code and improves readability
10
-
11
- ## Requirements
12
-
13
- - Node JS v16 or later
14
- - Taquito v11.2 or later (optional)
15
-
16
- ## Installation
17
-
18
- To install the Contract Types plugin on a Taqueria project, navigate to the project folder and run:
19
- ```shell
20
- taq install @taqueria/plugin-contract-types
21
- ```
22
-
23
- ## Configuration
24
-
25
- This plugin will look for Michelson files according to the `artifactsDir` configured in `./.taq/config.json`. By default, this value is `/artifacts` but can be changed as needed
26
-
27
- ## Usage
28
-
29
- The plugin provides a single command to Taqueria: `taq generate types`
30
-
31
- This will look for `.tz` files in the `/artifacts` directory and will generate a series of related `.ts` files in the `/types` directory. These files export type definitions for each method which can then be used by Taquito and your IDE
32
-
33
- ### The `generate types` Command
34
-
35
- #### Syntax
36
- ```shell
37
- taq generate types [typeOutputDir]
38
- ```
39
-
40
- #### Parameters
41
-
42
- | parameter | required | description |
43
- |:-------------:|:-----------|----------------------------------------------------|
44
- | typeOutputDir | no | The output directory for the `.ts` files generated |
45
-
46
- #### CLI Aliases
47
-
48
- The following aliases are interchangable with `generate types`
49
- - `gen`
50
- - `gentypes`
51
-
52
- #### Options
53
-
54
- The `generate types` command will accept the following optional parameters:
55
-
56
- | flag | name | description |
57
- |:-----:|:--------------|----------------------------------------------|
58
- | -t | typeAliasMode | Use type aliases in the generated types |
59
-
60
- ## Examples
61
-
62
- ### Example Usage (based on an nft auction contract from open minter sdk)
63
-
64
- ```ts
65
- export const exampleContractMethods1 = async () => {
66
-
67
- const Tezos = new TezosToolkit(`https://YOUR_PREFERRED_RPC_URL`)
68
-
69
- const contract = await Tezos.contract.at<TestContract>(`tz123`);
70
-
71
- contract.methods.bid(tas.nat(0));
72
- contract.methods.configure(
73
- /*opening_price:*/ tas.mutez(10),
74
- /*min_raise_percent:*/ tas.nat(10),
75
- /*min_raise:*/ tas.mutez(10),
76
- /*round_time:*/ tas.nat(10),
77
- /*extend_time:*/ tas.nat(10),
78
- /*asset:*/ [{
79
- fa2_address: tas.address(`tz123`),
80
- fa2_batch: [{
81
- amount: tas.nat(100),
82
- token_id: tas.nat(`100000000000000`),
83
- }],
84
- }],
85
- /*start_time:*/ tas.timestamp(new Date()),
86
- /*end_time:*/ tas.timestamp(`2020-01-01`),
87
- );
88
-
89
- // methodsObject
90
- contract.methodsObject.bid(tas.nat(0));
91
- contract.methodsObject.configure({
92
- asset: [{
93
- fa2_address: tas.address(`tz123`),
94
- fa2_batch: [{
95
- amount: tas.nat(100),
96
- token_id: tas.nat(`100000000000000`),
97
- }],
98
- }],
99
- start_time: tas.timestamp(new Date()),
100
- end_time: tas.timestamp(`2020-01-01`),
101
- extend_time: tas.nat(10),
102
- min_raise: tas.mutez(10),
103
- min_raise_percent: tas.nat(10),
104
- opening_price: tas.mutez(10),
105
- round_time: tas.nat(10),
106
- });
107
-
108
- };
109
- ```
110
-
111
- ### Example typegen task
112
-
113
- ```console
114
- $ taqueria typegen --typescriptDir ./types
115
- generateTypes
116
- {
117
- "typescriptDir": "./types"
118
- }
119
- Generating Types: /home/rick/projects/crypto/taqueria/example/artifacts => /home/rick/projects/crypto/taqueria/example/types
120
- Contracts Found:
121
- - /home/rick/projects/crypto/taqueria/example/artifacts/example-contract-1.tz
122
- Processing /example-contract-1.tz...example-contract-1.tz: Types generated
123
- ```
124
-
125
-
126
- ### Example type output
127
-
128
- ```ts
129
- type Storage = {
130
- pauseable_admin?: {
131
- admin: address;
132
- paused: boolean;
133
- pending_admin?: address;
134
- };
135
- current_id: nat;
136
- max_auction_time: nat;
137
- max_config_to_start_time: nat;
138
- auctions: BigMap<nat, {
139
- seller: address;
140
- current_bid: mutez;
141
- start_time: timestamp;
142
- last_bid_time: timestamp;
143
- round_time: int;
144
- extend_time: int;
145
- asset: Array<{
146
- fa2_address: address;
147
- fa2_batch: Array<{
148
- token_id: nat;
149
- amount: nat;
150
- }>;
151
- }>;
152
- min_raise_percent: nat;
153
- min_raise: mutez;
154
- end_time: timestamp;
155
- highest_bidder: address;
156
- }>;
157
- };
158
-
159
- type Methods = {
160
- confirm_admin: () => Promise<void>;
161
- pause: (param: boolean) => Promise<void>;
162
- set_admin: (param: address) => Promise<void>;
163
- bid: (param: nat) => Promise<void>;
164
- cancel: (param: nat) => Promise<void>;
165
- configure: (
166
- opening_price: mutez,
167
- min_raise_percent: nat,
168
- min_raise: mutez,
169
- round_time: nat,
170
- extend_time: nat,
171
- asset: Array<{
172
- fa2_address: address;
173
- fa2_batch: Array<{
174
- token_id: nat;
175
- amount: nat;
176
- }>;
177
- }>,
178
- start_time: timestamp,
179
- end_time: timestamp,
180
- ) => Promise<void>;
181
- resolve: (param: nat) => Promise<void>;
182
- };
183
- ```
184
-
185
-
186
- ## Taquito library changes
187
-
188
- See [example-usage.ts](example/example-usage.ts) for full example
189
-
190
- ### Before
191
-
192
- Using taquito with the generated contract types:
193
-
194
- The at method can be called providing a type with a utility method that can be provided:
195
- ```ts
196
- const contract = await Tezos.contract.at(`tz123`, contractAbstractionComposer<TestContractType>());
197
-
198
- // methods can now use typed parameters
199
- // methodsObject will be able to use type parameters
200
- ```
201
-
202
- This can work the same with a wallet
203
- ```ts
204
- const contract = await Tezos.wallet.at(`tz123`, walletAbstractionComposer<TestContractType>());
205
- ```
206
-
207
- Alternatively, this can be done with a cast:
208
- ```ts
209
- const contract = await Tezos.contract.at(`tz123`) as ContractProviderFromContractType<TestContractType>;
210
- ```
211
-
212
-
213
- The originate contract does not have any way to provide a type, so this requires a cast:
214
- ```ts
215
- const originationResult = await Tezos.contract.originate({...});
216
- const contract = await originationResult.contract(5) as ContractProviderFromContractType<TestContractType2>;
217
- ```
218
-
219
-
220
- For accessing storage, there is no way to pass the type through the contract class,
221
- so it requires providing the type again:
222
- ```ts
223
- const contract = await Tezos.contract.at(`tz123`) as ContractProviderFromContractType<TestContractType>;
224
- const storage = await contract.storage<StorageFromContractType<TestContractType>>();
225
- ```
226
-
227
-
228
- ### After
229
-
230
- Extending ContractAbstraction with additional generic types:
231
-
232
- The at method can be called with the contract type provided:
233
- ```ts
234
- const contract = await Tezos.contract.at<TestContract>(`tz123`);
235
-
236
- // methods can now use typed parameters
237
- // methodsObject will be able to use type parameters
238
- // storage will be able to use type parameters
239
-
240
- ```
241
-
242
- This can work the same with a wallet
243
- ```ts
244
- const contract = await Tezos.wallet.at<TestWalletContract>(`tz123`);
245
- ```
246
-
247
- The originate contract now accepts a type:
248
- ```ts
249
- const originationResult = await Tezos.contract.originate({...});
250
- const contract = await originationResult.contract<TestContract2>(5);
251
- ```
252
-
253
-
254
- The contract type now also provides the default storage type:
255
- ```ts
256
- const contract = await Tezos.contract.at<TestContract>(`tz123`);
257
- const storage = await contract.storage();
258
- ```
259
-