feat: wrap aqua api (#807)

api/api-example/index.js

@@ -1,32 +1,20 @@
-import {
+//@ts-check
-    Aqua,
-    Call,
-    Path,
-} from "@fluencelabs/aqua-api/aqua-api.js";
 
-const aquaPath = new Path("test.aqua")
+import { compileAquaCallFromPath } from '@fluencelabs/aqua-api'
-// write function that we want to call and arguments
-const args = {num: 42}
-const call = new Call("getNumber(num)", args, aquaPath)
 
 // compile call
-const compilationResult = await Aqua.compile(call, [])
+const compilationResult = await compileAquaCallFromPath({
+  filePath: 'test.aqua',
+  data: { num: 3 },
+  funcCall: 'getNumber(num)',
+})
 
+const {
+  errors,
+  functionCall: { funcDef, script },
+  functions,
+  generatedSources,
+  services,
+} = compilationResult
 
-/*
+console.log(script)
-// Compilation result definition
-export class CompilationResult {
-    // List of service definitions to register in Fluence JS Client
-    services: Record<string, ServiceDef>
-    // List of function definitions to call in Fluence JS Client
-    functions: Record<string, AquaFunction>
-    // Definition of wrapped function to call in Fluence JS Client
-    functionCall?: AquaFunction
-    // List of errors. All other fields will be empty if `errors` not empty
-    errors: string[]
-}
- */
-
-// get function definition, that describes types of arguments and results of a function
-// and AIR script
-const {funcDef, script} = compilationResult.functionCall

api/api-example/package-lock.json

@@ -1,21 +0,0 @@
-{
-  "name": "aqua-api-example",
-  "version": "1.0.0",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "aqua-api-example",
-      "version": "1.0.0",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@fluencelabs/aqua-api": "0.10.4"
-      }
-    },
-    "node_modules/@fluencelabs/aqua-api": {
-      "version": "0.10.4",
-      "resolved": "https://registry.npmjs.org/@fluencelabs/aqua-api/-/aqua-api-0.10.4.tgz",
-      "integrity": "sha512-mBT/ht0mVcGqBfkrnQw9E/tqIW3RNOCDhNwjra9X5WI/TRlztU3G8Vn/odVn6YTpZWJeDwn1qN1VgLoS3VkASA=="
-    }
-  }
-}

api/api-example/package.json

@@ -10,6 +10,6 @@
   "type": "module",
   "license": "Apache-2.0",
   "dependencies": {
-    "@fluencelabs/aqua-api": "0.10.4"
+    "@fluencelabs/aqua-api": "workspace:*"
   }
 }

api/api-npm/aqua-api.d.ts

@@ -1,67 +1,69 @@
-import type { FunctionCallDef, ServiceDef } from "@fluencelabs/fluence/dist/internal/compilerSupport/v3impl/interface"
+import type { FunctionCallDef, ServiceDef } from "@fluencelabs/interfaces";
 
 export class AquaConfig {
-    constructor(
+  constructor(
-        logLevel?: string,
+    logLevel?: string,
-        constants?: string[],
+    constants?: string[],
-        noXor?: boolean,
+    noXor?: boolean,
-        noRelay?: boolean,
+    noRelay?: boolean,
-        targetType?: string,
+    targetType?: string,
-        tracing?: boolean
+    tracing?: boolean,
-    );
+  );
 
-    logLevel?: string
+  logLevel?: string;
-    constants?: string[]
+  constants?: string[];
-    noXor?: boolean
+  noXor?: boolean;
-    noRelay?: boolean
+  noRelay?: boolean;
-    targetType?: string
+  targetType?: string;
-    tracing?: boolean
+  tracing?: boolean;
 }
 
 export class AquaFunction {
-    funcDef: FunctionCallDef
+  funcDef: FunctionCallDef;
-    script: string
+  script: string;
 }
 
 export class GeneratedSource {
-    name: string
+  name: string;
-    tsSource?: string
+  tsSource?: string;
-    jsSource?: string
+  jsSource?: string;
-    tsTypes?: string
+  tsTypes?: string;
 }
 
 export class CompilationResult {
-    services: Record<string, ServiceDef>
+  services: Record<string, ServiceDef>;
-    functions: Record<string, AquaFunction>
+  functions: Record<string, AquaFunction>;
-    functionCall?: AquaFunction
+  functionCall?: AquaFunction;
-    errors: string[]
+  errors: string[];
-    generatedSources: GeneratedSource[]
+  generatedSources: GeneratedSource[];
 }
 
 export class Input {
-    constructor(input: string);
+  constructor(input: string);
 
-    input: string
+  input: string;
 }
 
 export class Path {
-    constructor(path: string);
+  constructor(path: string);
 
-    path: string
+  path: string;
 }
 
 export class Call {
-    constructor(functionCall: string,
+  constructor(functionCall: string, arguments: any, input: Input | Path);
-        arguments: any,
-        input: Input | Path);
 
-    functionCall: string
+  functionCall: string;
-    arguments: any
+  arguments: any;
-    input: Input | Path
+  input: Input | Path;
 }
 
 export class Compiler {
-    compile(input: Input | Path | Call, imports: string[], config?: AquaConfig): Promise<CompilationResult>;
+  compile(
+    input: Input | Path | Call,
+    imports: string[],
+    config?: AquaConfig,
+  ): Promise<CompilationResult>;
 }
 
 export var Aqua: Compiler;

api/api-npm/index.d.ts

@@ -0,0 +1,50 @@
+import { type CompilationResult } from "./aqua-api.js";
+
+/** Common arguments for all compile functions */
+type CommonArgs = {
+  /** Paths to directories, which you want to import .aqua files from. Example: ["./path/to/dir"] */
+  imports?: string[] | undefined;
+  /** Constants to be passed to the compiler. Example: ["CONSTANT1=1", "CONSTANT2=2"] */
+  constants?: string[] | undefined;
+  /** Set log level for the compiler. Must be one of: Must be one of: all, trace, debug, info, warn, error, off. Default: info */
+  logLevel?: string | undefined;
+  /** Do not generate a pass through the relay node. Default: false */
+  noRelay?: boolean | undefined;
+  /** Do not generate a wrapper that catches and displays errors. Default: false */
+  noXor?: boolean | undefined;
+  /** Target type for the compiler. Must be one of: ts, js, air. Default: air */
+  targetType?: "ts" | "js" | "air" | undefined;
+  /** Compile aqua in tracing mode (for debugging purposes). Default: false */
+  tracing?: boolean | undefined;
+};
+
+type CodeString = {
+  /** Aqua code to be compiled */
+  code: string;
+}
+
+/** Compile aqua code from a string */
+export declare function compileFromString(args: CommonArgs & CodeString): Promise<Omit<CompilationResult, 'funcCall'>>
+
+type FilePath = {
+  /** Path to the aqua file to be compiled */
+  filePath: string;
+}
+
+/** Compile aqua code from a file */
+export declare function compileFromPath(args: CommonArgs & FilePath): Promise<Omit<CompilationResult, 'funcCall'>>
+
+type FuncCall = {
+  /** Function call you want to compile. Example: someFunc("someArg") */
+  funcCall: string;
+  /** Args to be passed to the function (record with keys named as args you want to pass to the function) Example: { someArg: 1 } */
+  data?: Record<string, unknown> | undefined;
+}
+
+/** Compile aqua function call from a string */
+export declare function compileAquaCallFromString(args: CommonArgs & CodeString & FuncCall): Promise<Required<CompilationResult>>
+
+/** Compile aqua function call from a file */
+export declare function compileAquaCallFromPath(args: CommonArgs & FilePath & FuncCall): Promise<Required<CompilationResult>>
+
+export {}

api/api-npm/index.js

@@ -0,0 +1,66 @@
+// @ts-check
+import { AquaConfig, Aqua, Call, Input, Path } from "./aqua-api.js";
+
+function getConfig({
+  constants = [],
+  logLevel = "info",
+  noRelay = false,
+  noXor = false,
+  targetType = "air",
+  tracing = false,
+}) {
+  return new AquaConfig(
+    logLevel,
+    constants,
+    noXor,
+    noRelay,
+    {
+      ts: "typescript",
+      js: "javascript",
+      air: "air",
+    }[targetType],
+    tracing,
+  );
+}
+
+export function compileFromString({ code, ...commonArgs }) {
+  const config = getConfig(commonArgs);
+  const { imports = [] } = commonArgs;
+  return Aqua.compile(new Input(code), imports, config);
+}
+
+export function compileFromPath({ filePath, ...commonArgs }) {
+  const config = getConfig(commonArgs);
+  const { imports = [] } = commonArgs;
+  return Aqua.compile(new Path(filePath), imports, config);
+}
+
+export function compileAquaCallFromString({
+  code,
+  funcCall,
+  data,
+  ...commonArgs
+}) {
+  const config = getConfig(commonArgs);
+  const { imports = [] } = commonArgs;
+  return Aqua.compile(
+    new Call(funcCall, data, new Input(code)),
+    imports,
+    config,
+  );
+}
+
+export function compileAquaCallFromPath({
+  filePath,
+  funcCall,
+  data,
+  ...commonArgs
+}) {
+  const config = getConfig(commonArgs);
+  const { imports = [] } = commonArgs;
+  return Aqua.compile(
+    new Call(funcCall, data, new Input(filePath)),
+    imports,
+    config,
+  );
+}

api/api-npm/package.json

@@ -2,12 +2,16 @@
   "name": "@fluencelabs/aqua-api",
   "version": "0.11.8",
   "description": "Aqua API",
-  "type": "commonjs",
+  "type": "module",
+  "main": "index.js",
   "files": [
+    "index.js",
+    "index.d.ts",
     "aqua-api.js",
     "aqua-api.d.ts",
     "meta-utils.js"
   ],
+  "prettier": {},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fluencelabs/aqua.git"
@@ -23,6 +27,7 @@
   },
   "homepage": "https://github.com/fluencelabs/aqua#readme",
   "devDependencies": {
-    "@fluencelabs/fluence": "0.28.0"
+    "@fluencelabs/interfaces": "^0.8.0",
+    "prettier": "3.0.0"
   }
 }

build.sbt

@@ -155,7 +155,7 @@ lazy val `aqua-apiJS` = `aqua-api`.js
   .settings(
     Compile / fastOptJS / artifactPath := baseDirectory.value / "../../api-npm" / "aqua-api.js",
     Compile / fullOptJS / artifactPath := baseDirectory.value / "../../api-npm" / "aqua-api.js",
-    scalaJSLinkerConfig                ~= (_.withModuleKind(ModuleKind.CommonJSModule)),
+    scalaJSLinkerConfig                ~= (_.withModuleKind(ModuleKind.ESModule)),
     scalaJSUseMainModuleInitializer    := true,
     Test / test                        := {}
   )

pnpm-workspace.yaml

@@ -1,5 +1,6 @@
 packages:
   - 'cli/cli-npm'
   - 'api/api-npm'
+  - 'api/api-example'
   - 'language-server/language-server-npm'
   - 'integration-tests'