feat: JavaScript target IDL type object exports and factory function deprecations (#665)

**Overview**

The JavaScript target would be more useful (especially to Azle
developers) if it exported the IDL type objects that it generates. We
also no longer need the factory functions as of `3.0.0`, thus we will
mark them deprecated and provide direct exports for that previous
functionality.

**Requirements**

The JavaScript target should export all of the IDL type objects,
including the generated `IDL.Service` and `init args`, without the need
to use a factory function.

**Considerations**

There are no breaking changes besides some formatting of the generated
JavaScript files. The `idflFactory` and `init` functions have been
marked as deprecated but not removed. Developers can choose to import
the `IDL` type objects now, but they are not forced to. This is mainly
an ergonomic change with deprecations to prepare for a future with the
best developer experience by default.

Author: lastmjs

CHANGELOG.md

@@ -15,6 +15,8 @@
 
 * Non-breaking changes:
   + Added `pp_named_args`, `pp_named_init_args` in `pretty::candid` module.
+  + The `JavaScript` `didc` target now exports its generated IDL type objects.
+  + The `JavaScript` and `TypeScript` `didc` targets now export `idlService` and `idlInitArgs` (non-factory-function altneratives to `idlFactory` and `init`).
 
 ### candid_parser
 

rust/candid_parser/src/bindings/javascript.rs

@@ -193,25 +193,36 @@ fn pp_defs<'a>(
     env: &'a TypeEnv,
     def_list: &'a [&'a str],
     recs: &'a BTreeSet<&'a str>,
+    export: bool,
 ) -> RcDoc<'a> {
-    let recs_doc = lines(
-        recs.iter()
-            .map(|id| kwd("const").append(ident(id)).append(" = IDL.Rec();")),
-    );
-    let defs = lines(def_list.iter().map(|&id| {
+    let export_prefix = if export { str("export ") } else { RcDoc::nil() };
+
+    let recs_doc = lines(recs.iter().map(|id| {
+        export_prefix
+            .clone()
+            .append(kwd("const"))
+            .append(ident(id))
+            .append(" = IDL.Rec();")
+    }));
+    let mut defs = lines(def_list.iter().map(|&id| {
         let ty = env.find_type(&id.into()).unwrap();
         if recs.contains(id) {
             ident(id)
                 .append(".fill")
                 .append(enclose("(", pp_ty(ty), ");"))
         } else {
-            kwd("const")
+            export_prefix
+                .clone()
+                .append(kwd("const"))
                 .append(ident(id))
                 .append(" = ")
                 .append(pp_ty(ty))
                 .append(";")
         }
     }));
+    if !def_list.is_empty() {
+        defs = defs.append(RcDoc::hardline())
+    }
     recs_doc.append(defs)
 }
 
@@ -230,39 +241,71 @@ fn pp_actor<'a>(ty: &'a Type, recs: &'a BTreeSet<&'a str>) -> RcDoc<'a> {
     }
 }
 
+fn pp_imports<'a>() -> RcDoc<'a> {
+    str("import { IDL } from '@dfinity/candid';")
+        .append(RcDoc::hardline())
+        .append(RcDoc::hardline())
+}
+
 pub fn compile(env: &TypeEnv, actor: &Option<Type>) -> String {
     match actor {
         None => {
             let def_list: Vec<_> = env.to_sorted_iter().map(|pair| pair.0.as_str()).collect();
             let recs = infer_rec(env, &def_list).unwrap();
-            let doc = pp_defs(env, &def_list, &recs);
-            doc.pretty(LINE_WIDTH).to_string()
+            let doc = pp_defs(env, &def_list, &recs, true);
+            let result = pp_imports().append(doc).pretty(LINE_WIDTH).to_string();
+
+            result
         }
         Some(actor) => {
             let def_list = chase_actor(env, actor).unwrap();
             let recs = infer_rec(env, &def_list).unwrap();
-            let defs = pp_defs(env, &def_list, &recs);
             let types = if let TypeInner::Class(ref args, _) = actor.as_ref() {
                 args.iter().map(|arg| arg.typ.clone()).collect::<Vec<_>>()
             } else {
                 Vec::new()
             };
-            let init = types.as_slice();
-            let actor = kwd("return").append(pp_actor(actor, &recs)).append(";");
-            let body = defs.append(actor);
-            let doc = str("export const idlFactory = ({ IDL }) => ")
-                .append(enclose_space("{", body, "};"));
-            // export init args
-            let init_defs = chase_types(env, init).unwrap();
+            let init_types = types.as_slice();
+
+            let defs = pp_defs(env, &def_list, &recs, true);
+            let actor = pp_actor(actor, &recs);
+
+            let idl_service = str("export const idlService = ")
+                .append(actor.clone())
+                .append(";");
+
+            let idl_init_args = str("export const idlInitArgs = ")
+                .append(pp_rets(init_types))
+                .append(";");
+
+            let idl_factory_return = kwd("return").append(actor).append(";");
+            let idl_factory_body = pp_defs(env, &def_list, &recs, false).append(idl_factory_return);
+            let idl_factory_doc = str("export const idlFactory = ({ IDL }) => ")
+                .append(enclose_space("{", idl_factory_body, "};"));
+
+            let init_defs = chase_types(env, init_types).unwrap();
             let init_recs = infer_rec(env, &init_defs).unwrap();
-            let init_defs_doc = pp_defs(env, &init_defs, &init_recs);
-            let init_doc = kwd("return").append(pp_rets(init)).append(";");
+            let init_defs_doc = pp_defs(env, &init_defs, &init_recs, false);
+            let init_doc = kwd("return").append(pp_rets(init_types)).append(";");
             let init_doc = init_defs_doc.append(init_doc);
             let init_doc =
                 str("export const init = ({ IDL }) => ").append(enclose_space("{", init_doc, "};"));
             let init_doc = init_doc.pretty(LINE_WIDTH).to_string();
-            let doc = doc.append(RcDoc::hardline()).append(init_doc);
-            doc.pretty(LINE_WIDTH).to_string()
+
+            let result = pp_imports()
+                .append(defs)
+                .append(idl_service)
+                .append(RcDoc::hardline())
+                .append(RcDoc::hardline())
+                .append(idl_init_args)
+                .append(RcDoc::hardline())
+                .append(RcDoc::hardline())
+                .append(idl_factory_doc)
+                .append(RcDoc::hardline())
+                .append(RcDoc::hardline())
+                .append(init_doc);
+
+            result.pretty(LINE_WIDTH).to_string()
         }
     }
 }

rust/candid_parser/src/bindings/typescript.rs

@@ -317,9 +317,9 @@ fn pp_actor<'a>(env: &'a TypeEnv, ty: &'a Type, syntax: Option<&'a IDLType>) ->
 }
 
 pub fn compile(env: &TypeEnv, actor: &Option<Type>, prog: &IDLMergedProg) -> String {
-    let header = r#"import type { Principal } from '@dfinity/principal';
-import type { ActorMethod } from '@dfinity/agent';
+    let header = r#"import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
+import type { Principal } from '@dfinity/principal';
 "#;
     let syntax_actor = prog.resolve_actor().ok().flatten();
     let def_list: Vec<_> = env.to_sorted_iter().map(|pair| pair.0.as_str()).collect();
@@ -332,6 +332,10 @@ import type { IDL } from '@dfinity/candid';
                 .map(|s| pp_docs(s.docs.as_ref()))
                 .unwrap_or(RcDoc::nil());
             docs.append(pp_actor(env, actor, syntax_actor.as_ref().map(|s| &s.typ)))
+                .append(RcDoc::line())
+                .append("export declare const idlService: IDL.ServiceClass;")
+                .append(RcDoc::line())
+                .append("export declare const idlInitArgs: IDL.Type[];")
                 .append(RcDoc::line())
                 .append("export declare const idlFactory: IDL.InterfaceFactory;")
                 .append(RcDoc::line())

rust/candid_parser/tests/assets/ok/actor.d.ts

@@ -1,6 +1,6 @@
-import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
+import type { Principal } from '@dfinity/principal';
 
 export type f = ActorMethod<[number], number>;
 export type g = f;
@@ -13,5 +13,7 @@ export interface _SERVICE {
   'h2' : h,
   'o' : ActorMethod<[o], o>,
 }
+export declare const idlService: IDL.ServiceClass;
+export declare const idlInitArgs: IDL.Type[];
 export declare const idlFactory: IDL.InterfaceFactory;
 export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

rust/candid_parser/tests/assets/ok/actor.js

@@ -1,9 +1,28 @@
+import { IDL } from '@dfinity/candid';
+
+export const o = IDL.Rec();
+export const f = IDL.Func([IDL.Int8], [IDL.Int8], []);
+export const h = IDL.Func([f], [f], []);
+export const g = f;
+o.fill(IDL.Opt(o));
+
+export const idlService = IDL.Service({
+  'f' : IDL.Func([IDL.Nat], [h], []),
+  'g' : f,
+  'h' : g,
+  'h2' : h,
+  'o' : IDL.Func([o], [o], []),
+});
+
+export const idlInitArgs = [];
+
 export const idlFactory = ({ IDL }) => {
   const o = IDL.Rec();
   const f = IDL.Func([IDL.Int8], [IDL.Int8], []);
   const h = IDL.Func([f], [f], []);
   const g = f;
   o.fill(IDL.Opt(o));
+  
   return IDL.Service({
     'f' : IDL.Func([IDL.Nat], [h], []),
     'g' : f,
@@ -12,4 +31,5 @@ export const idlFactory = ({ IDL }) => {
     'o' : IDL.Func([o], [o], []),
   });
 };
+
 export const init = ({ IDL }) => { return []; };

rust/candid_parser/tests/assets/ok/class.d.ts

@@ -1,6 +1,6 @@
-import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
+import type { Principal } from '@dfinity/principal';
 
 export type List = [] | [[bigint, List]];
 export interface Profile { 'age' : number, 'name' : string }
@@ -14,5 +14,7 @@ export interface _SERVICE {
   'get' : ActorMethod<[], List>,
   'set' : ActorMethod<[List], List>,
 }
+export declare const idlService: IDL.ServiceClass;
+export declare const idlInitArgs: IDL.Type[];
 export declare const idlFactory: IDL.InterfaceFactory;
 export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

rust/candid_parser/tests/assets/ok/class.js

@@ -1,15 +1,31 @@
+import { IDL } from '@dfinity/candid';
+
+export const List = IDL.Rec();
+List.fill(IDL.Opt(IDL.Tuple(IDL.Int, List)));
+export const Profile = IDL.Record({ 'age' : IDL.Nat8, 'name' : IDL.Text });
+
+export const idlService = IDL.Service({
+  'get' : IDL.Func([], [List], []),
+  'set' : IDL.Func([List], [List], []),
+});
+
+export const idlInitArgs = [IDL.Int, List, Profile];
+
 export const idlFactory = ({ IDL }) => {
   const List = IDL.Rec();
   List.fill(IDL.Opt(IDL.Tuple(IDL.Int, List)));
   const Profile = IDL.Record({ 'age' : IDL.Nat8, 'name' : IDL.Text });
+  
   return IDL.Service({
     'get' : IDL.Func([], [List], []),
     'set' : IDL.Func([List], [List], []),
   });
 };
+
 export const init = ({ IDL }) => {
   const List = IDL.Rec();
   List.fill(IDL.Opt(IDL.Tuple(IDL.Int, List)));
   const Profile = IDL.Record({ 'age' : IDL.Nat8, 'name' : IDL.Text });
+  
   return [IDL.Int, List, Profile];
 };

rust/candid_parser/tests/assets/ok/comment.d.ts

@@ -1,6 +1,6 @@
-import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
+import type { Principal } from '@dfinity/principal';
 
 /**
  * line comment

rust/candid_parser/tests/assets/ok/comment.js

@@ -1,2 +1,5 @@
-const id = IDL.Nat8;
+import { IDL } from '@dfinity/candid';
+
+export const id = IDL.Nat8;
+
 

rust/candid_parser/tests/assets/ok/cyclic.d.ts

@@ -1,6 +1,6 @@
-import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
+import type { Principal } from '@dfinity/principal';
 
 export type A = [] | [B];
 export type B = [] | [C];
@@ -9,5 +9,7 @@ export type X = Y;
 export type Y = Z;
 export type Z = A;
 export interface _SERVICE { 'f' : ActorMethod<[A, B, C, X, Y, Z], undefined> }
+export declare const idlService: IDL.ServiceClass;
+export declare const idlInitArgs: IDL.Type[];
 export declare const idlFactory: IDL.InterfaceFactory;
 export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];