From 77019f73bc2a186e95834d77cb02295efcd4e3de Mon Sep 17 00:00:00 2001 From: Jordan Last Date: Thu, 2 Jan 2025 14:41:26 -0700 Subject: [PATCH] adding jsdocs to query and update decorators --- .../ic_api/reject_code/src/caller/index.ts | 11 ++++++----- .../ic_api/reject_message/src/caller/index.ts | 11 ++++++----- src/lib/stable/canister_methods/query.ts | 14 ++++++++++++++ src/lib/stable/canister_methods/update.ts | 13 +++++++++++++ 4 files changed, 39 insertions(+), 10 deletions(-) diff --git a/examples/stable/test/property/ic_api/reject_code/src/caller/index.ts b/examples/stable/test/property/ic_api/reject_code/src/caller/index.ts index 690f137d86..98fd374eef 100644 --- a/examples/stable/test/property/ic_api/reject_code/src/caller/index.ts +++ b/examples/stable/test/property/ic_api/reject_code/src/caller/index.ts @@ -1,4 +1,4 @@ -import { call, IDL, rejectCode, RejectionCode, trap, update } from 'azle'; +import { call, IDL, rejectCode, RejectionCode, update } from 'azle'; import { AssertType, NotAnyAndExact } from 'azle/type_tests/assert_type'; export default class { @@ -111,8 +111,9 @@ function isRejectionCode(code: RejectionCode): boolean { } function getRejectorPrincipal(): string { - return ( - process.env.REJECTOR_PRINCIPAL ?? - trap('process.env.REJECTOR_PRINCIPAL is undefined') - ); + if (process.env.REJECTOR_PRINCIPAL !== undefined) { + return process.env.REJECTOR_PRINCIPAL; + } + + throw new Error(`process.env.REJECTOR_PRINCIPAL is undefined`); } diff --git a/examples/stable/test/property/ic_api/reject_message/src/caller/index.ts b/examples/stable/test/property/ic_api/reject_message/src/caller/index.ts index b093d3b950..99ea6e1f4b 100644 --- a/examples/stable/test/property/ic_api/reject_message/src/caller/index.ts +++ b/examples/stable/test/property/ic_api/reject_message/src/caller/index.ts @@ -1,4 +1,4 @@ -import { call, IDL, rejectMessage, trap, update } from 'azle'; +import { call, IDL, rejectMessage, update } from 'azle'; import { AssertType, NotAnyAndExact } from 'azle/type_tests/assert_type'; export default class { @@ -38,8 +38,9 @@ async function getRejectMessage( } function getRejectorPrincipal(): string { - return ( - process.env.REJECTOR_PRINCIPAL ?? - trap('process.env.REJECTOR_PRINCIPAL is undefined') - ); + if (process.env.REJECTOR_PRINCIPAL !== undefined) { + return process.env.REJECTOR_PRINCIPAL; + } + + throw new Error(`process.env.REJECTOR_PRINCIPAL is undefined`); } diff --git a/src/lib/stable/canister_methods/query.ts b/src/lib/stable/canister_methods/query.ts index 432d64cdd6..7990dee672 100644 --- a/src/lib/stable/canister_methods/query.ts +++ b/src/lib/stable/canister_methods/query.ts @@ -7,11 +7,25 @@ import { MethodType } from '.'; +/** + * Decorator to mark a method as a query call entry point. + * Query calls are read-only and do not inherit latency from ICP consensus. + */ export function query( originalMethod: MethodType, context: ClassMethodDecoratorContext> ): MethodType; +/** + * Decorator to mark a method as a query call entry point. + * Query calls are read-only and do not inherit latency from ICP consensus. + * + * @param paramIdlTypes - Optional array of Candid IDL types for the method parameters. The runtime arguments will be decoded using these types. + * @param returnIdlType - Optional Candid IDL type for the method return value. The runtime return value will be encoded using this type. + * @param options - Optional configuration object + * @param options.composite - Optional flag to indicate that the method should be treated as a composite query method capable of some cross-canister query calls. + * @param options.manual - Optional flag to indicate manual handling of the method's runtime return value. This is meant to be used with `reply`, skipping automatic Candid encoding of the runtime return value. + */ export function query( paramIdlTypes?: IDL.Type[], returnIdlType?: IDL.Type, diff --git a/src/lib/stable/canister_methods/update.ts b/src/lib/stable/canister_methods/update.ts index 37f00e84f8..a3c2898fa0 100644 --- a/src/lib/stable/canister_methods/update.ts +++ b/src/lib/stable/canister_methods/update.ts @@ -7,11 +7,24 @@ import { MethodType } from '.'; +/** + * Decorator to mark a method as an update call entry point. + * Update calls are read-write and inherit latency from ICP consensus. + */ export function update( originalMethod: MethodType, context: ClassMethodDecoratorContext> ): MethodType; +/** + * Decorator to mark a method as an update call entry point. + * Update calls are read-write and inherit latency from ICP consensus. + * + * @param paramIdlTypes - Optional array of Candid IDL types for the method parameters. The runtime arguments will be decoded using these types. + * @param returnIdlType - Optional Candid IDL type for the method return value. The runtime return value will be encoded using this type. + * @param options - Optional configuration object + * @param options.manual - Optional flag to indicate manual handling of the method's runtime return value. This is meant to be used with `reply`, skipping automatic Candid encoding of the runtime return value. + */ export function update( paramIdlTypes?: IDL.Type[], returnIdlType?: IDL.Type,