Control, Scope And Visibility

In Aqua, the default namespace of a module is the file name and all declarations, i.e., data, services and functions, are public.
For example, the default.aqua file:
1
-- default_foo.aqua
2
​
3
​
4
func foo() -> string:
5
    <- "I am a visible foo func that compiles"
Copied!
Which we compile with
1
aqua -i aqua-scripts -o compiled-aqua
Copied!
to obtain Typescript wrapped AIR, default_foo.ts in the compiled-aqua directory:
1
import { FluenceClient, PeerIdB58 } from '@fluencelabs/fluence';
2
import { RequestFlowBuilder } from '@fluencelabs/fluence/dist/api.unstable';
3
import { RequestFlow } from '@fluencelabs/fluence/dist/internal/RequestFlow';
4
​
5
​
6
// Services
7
​
8
​
9
// Functions
10
​
11
export async function foo(client: FluenceClient, config?: {ttl?: number}): Promise<string> {
12
    let request: RequestFlow;
13
    const promise = new Promise<string>((resolve, reject) => {
14
        const r = new RequestFlowBuilder()
15
            .disableInjections()
16
            .withRawScript(
17
                `
18
(xor
19
 (seq
20
  (call %init_peer_id% ("getDataSrv" "-relay-") [] -relay-)
21
  (xor
22
   (call %init_peer_id% ("callbackSrv" "response") ["I am a visible foo func that compiles"])
23
   (call %init_peer_id% ("errorHandlingSrv" "error") [%last_error% 1])
24
  )
25
 )
26
 (call %init_peer_id% ("errorHandlingSrv" "error") [%last_error% 2])
27
)
28
​
29
            `,
30
            )
31
            .configHandler((h) => {
32
                h.on('getDataSrv', '-relay-', () => {
33
                    return client.relayPeerId!;
34
                });
35
​
36
                h.onEvent('callbackSrv', 'response', (args) => {
37
    const [res] = args;
38
  resolve(res);
39
});
40
​
41
                h.onEvent('errorHandlingSrv', 'error', (args) => {
42
                    // assuming error is the single argument
43
                    const [err] = args;
44
                    reject(err);
45
                });
46
            })
47
            .handleScriptError(reject)
48
            .handleTimeout(() => {
49
                reject('Request timed out for foo');
50
            })
51
        if(config && config.ttl) {
52
            r.withTTL(config.ttl)
53
        }
54
        request = r.build();
55
    });
56
    await client.initiateFlow(request!);
57
    return promise;
58
}
Copied!
Regardless of your output target, i.e. raw AIR or Typescript wrapped AIR, the default module namespace is default_foo and foo is the compiled function.
While this default approach is handy for single file, single module development, it makes for inefficient dependency management and unnecessary compilations for multi-module projects. The remainder of this section introduces the scoping and visibility concepts available in Aqua to effectively manage dependencies.
Managing Visibility With module and declare
By default, all declarations in a module, i.e., data, service and func, are public. With the module declaration, Aqua allows developers to create named modules and define membership visibility where the default visibility of module is private. That is, with the module declaration all module members are private and do not get compiled.
Let's create an export.aqua file like so:
1
module Export
2
​
3
func foo() -> string:
4
    <- "I am Export foo"
Copied!
When we compile export.aqua
1
aqua -i aqua-scripts -o compiled-aqua
Copied!
nothing gets compiled as expected:
1
2021.09.02 11:31:41 [INFO] Aqua Compiler 0.2.1-219
2
2021.09.02 11:31:42 [INFO] Source /Users/bebo/localdev/aqua-245/documentation-examples/aqua-scripts/export.aqua: compilation OK (nothing to emit)
Copied!
You can further check the output directory, compiled-aqua, in our case, for the lack of output files. Consequently, foo cannot be imported from other files. For example:
1
-- import.aqua
2
​
3
import "export.aqua"
4
​
5
​
6
func wrapped_foo() -> string:
7
    res <- foo()
8
    <- res
Copied!
Results in compile failure since foo is not visible to import.aqua:
1
6 func wrapped_foo() -> string:
2
7     res <- foo()
3
             ^^^==
4
             Undefined arrow, available: HOST_PEER_ID, INIT_PEER_ID, nil, LAST_ERROR
5
8     <- res
Copied!
We can use declares to create visibility for a module namespace for consuming modules. For example,
1
-- export.aqua
2
module Export declares foo
3
​
4
func bar() -> string:
5
    <- " I am MyFooBar bar"
6
​
7
func foo() -> string:
8
    res <- bar() 
9
    <- res
Copied!
in and by itself does not result in compiled Aqua:
1
aqua -i aqua-scripts -o compiled-aqua -a
2
Aqua JS: node /Users/bebo/.nvm/versions/node/v14.16.0/lib/node_modules/@fluencelabs/aqua/aqua.js -i aqua-scripts -o compiled-aqua -a
3
Aqua JS:
4
Aqua JS: 2021.09.08 13:36:17 [INFO] Aqua Compiler 0.3.0-222
5
2021.09.08 13:36:21 [INFO] Source /Users/bebo/localdev/aqua-245/documentation-examples/aqua-scripts/export.aqua: compilation OK (nothing to emit)
Copied!
But once we link from another module, e.g.:
1
import foo from "export.aqua"
2
​
3
func foo_wrapper() -> string:
4
    res <- foo()
5
    <- res
Copied!
We get the appropriate result:
1
2021.09.08 13:40:17 [INFO] Source /Users/bebo/localdev/aqua-245/documentation-examples/aqua-scripts/export.aqua: compilation OK (nothing to emit)
2
2021.09.08 13:40:17 [INFO] Result /Users/bebo/localdev/aqua-245/documentation-examples/compiled-aqua/import.ts: compilation OK (1 functions)
Copied!
in form of  import.ts:
1
// compiled-aqua/import.ts
2
import { FluencePeer } from '@fluencelabs/fluence';
3
import {
4
    ResultCodes,
5
    RequestFlow,
6
    RequestFlowBuilder,
7
    CallParams,
8
} from '@fluencelabs/fluence/dist/internal/compilerSupport/v1';
9
​
10
​
11
// Services
12
​
13
​
14
// Functions
15
​
16
 export function foo_wrapper(config?: {ttl?: number}) : Promise<string>;
17
 export function foo_wrapper(peer: FluencePeer, config?: {ttl?: number}) : Promise<string>;
18
 export function foo_wrapper(...args) {
19
     let peer: FluencePeer;
20
​
21
     let config;
22
     if (args[0] instanceof FluencePeer) {
23
         peer = args[0];
24
         config = args[1];
25
     } else {
26
         peer = FluencePeer.default;
27
         config = args[0];
28
     }
29
​
30
     let request: RequestFlow;
31
     const promise = new Promise<string>((resolve, reject) => {
32
         const r = new RequestFlowBuilder()
33
                 .disableInjections()
34
                 .withRawScript(
35
                     `
36
     (xor
37
 (seq
38
  (call %init_peer_id% ("getDataSrv" "-relay-") [] -relay-)
39
  (xor
40
   (call %init_peer_id% ("callbackSrv" "response") [" I am MyFooBar bar"])
41
   (call %init_peer_id% ("errorHandlingSrv" "error") [%last_error% 1])
42
  )
43
 )
44
 (call %init_peer_id% ("errorHandlingSrv" "error") [%last_error% 2])
45
)
46
​
47
                 `,
48
                 )
49
                 .configHandler((h) => {
50
                     h.on('getDataSrv', '-relay-', () => {
51
                    return peer.connectionInfo.connectedRelay ;
52
                });
53
​
54
                h.onEvent('callbackSrv', 'response', (args) => {
55
    const [res] = args;
56
  resolve(res);
57
});
58
​
59
                h.onEvent('errorHandlingSrv', 'error', (args) => {
60
                    const [err] = args;
61
                    reject(err);
62
                });
63
            })
64
            .handleScriptError(reject)
65
            .handleTimeout(() => {
66
                reject('Request timed out for foo_wrapper');
67
            })
68
        if(config && config.ttl) {
69
            r.withTTL(config.ttl)
70
        }
71
        request = r.build();
72
    });
73
    peer.internals.initiateFlow(request!);
74
    return promise;
75
}
Copied!
Of course, if we change import.aqua to include the private bar:
1
import bar from "export.aqua"
2
​
3
func bar_wrapper() -> string:
4
    res <- bar()
5
    <- res
Copied!
We get the expected error:
1
import bar from "export.aqua"
2
         ^^^===================
3
         Imported file declares [foo], no bar declared. Try adding `declares *` to that file.
Copied!
As indicated in the error message, declares * makes all members of the namespace public, although we can be quite fine-grained and use a comma separated list of members we want to be visible, such as declares foo, bar.
Scoping Inclusion With use and import
We already encountered the import statement earlier. Using import with the file name, e.g., import "export.aqua", imports all visible, i.e., public, members from the dependency. We can manage import granularity with the from modifier, e.g., import foo from "file.aqua", to limit our imports and subsequent compilation outputs. Moreover, we can alias imported declarations with the as modifier, e.g.,import foo as HighFoo, bar as LowBar from "export_file.aqua".
In addition to import, we also have the use keyword available to link and scope. The difference betweenuse and import is that use brings in module namespaces declared in the referenced source file. For example:
1
-- export.aqua
2
module ExportModule declares foo
3
​
4
func foo() -> string:
5
    <- "I am a foo fighter"
Copied!
declares the ExportModule namespace and makes foo visible. We can now bring foo into scope by means of its module namespace ExportModule in our import file without having to (re-) declare anything:
1
-- import.aqua
2
use "export.aqua"
3
​
4
func foo -> string:
5
    res <- ExportModule.foo()
6
    <- res
Copied!
This example already illustrates the power of use as we now can declare a local foo function rather than the foo_wrapper we used earlier. use provides very clear namespace separation that is fully enforced at the compiler level allowing developers to build, update and extend complex code bases with clear namespace separation by default.
The default behavior for use is to use the dependent filename if no module declaration was provided. Moreover, we can use the as modifier to change the module namespace. Continuing with the above example:
1
-- import.aqua
2
use "export.aqua" as RenamedExport
3
​
4
func foo() -> string:
5
    -- res <- ExportModule.foo()  --< this fails
6
    res <- RenamedExport.foo()
7
    <- res
Copied!
Imports And Exports
Expressions
Last modified 1mo ago
Copy link
Contents
Managing Visibility With module and declare
Scoping Inclusion With use and import
Managing Visibility With `module` and `declare`

Scoping Inclusion With `use` and `import`
