feat: compile api (#2)

Author: kazupon

.prettierignore

@@ -1,3 +1,4 @@
 lib
 coverage
 tsconfig.json
+__generated__

README.md

@@ -24,7 +24,7 @@ TODO:
 
 ## :handshake: API
 
-TODO:
+About details, See the [API References](https://github.com/intlify/cli/blob/master/api.md)
 
 
 ## :scroll: Changelog

api.md

@@ -0,0 +1,104 @@
+# @intlify/cli API References
+
+## Table Of Contents
+
+- [Function](#function)
+  - [compile](#compile)
+- [Enum](#enum)
+  - [CompileErrorCodes](#compileerrorcodes)
+- [Interface](#interface)
+  - [CompileOptions](#compileoptions)
+
+## Function
+
+### compile
+
+Compile i18n resources
+
+**Signature:**
+```typescript
+export declare function compile(source: string, output: string, options?: CompileOptions): Promise<boolean>;
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| source | string | the i18n resource source path, you can use glob pattern |
+| output | string | the compiled i18n resource output path |
+| options | CompileOptions | [CompileOptions](#compileoptions) |
+
+#### Returns
+
+ `true` when all i18n resource successfuly compile, not `false`
+
+#### Remarks
+
+This functoin is **asyncronous** function. If you want to get about error details, use the handler of [CompileOptions](#compileoptions) and [CompileErrorCodes](#compileerrorcodes)
+
+
+## Enum
+
+### CompileErrorCodes
+
+Compile Error Codes
+
+**Signature:**
+```typescript
+export declare const enum CompileErrorCodes 
+```
+
+#### Members
+
+| Member | Value| Description |
+| --- | --- | --- |
+| INTERNAL_COMPILE_ERROR | 3 | Internal compile error |
+| INTERNAL_COMPILE_WARNING | 2 | Internal compile warning |
+| NOT_SUPPORTED_FORMAT | 1 | Not supported format |
+
+#### Remarks
+
+The error codes of [compile](#compile) function
+
+
+## Interface
+
+### CompileOptions
+
+Compile Options
+
+**Signature:**
+```typescript
+export interface CompileOptions 
+```
+
+#### Remarks
+
+This optioins is used at [compile](#compile) function
+
+
+#### Methods
+
+
+#### Properties
+
+##### onCompile
+
+Compile handler
+
+**Signature:**
+```typescript
+onCompile?: (source: string, output: string) => void;
+```
+
+##### onError
+
+Compile Error handler
+
+**Signature:**
+```typescript
+onError?: (code: number, source: string, output: string, msg?: string) => void;
+```
+
+
+

package.json

@@ -71,6 +71,7 @@
   },
   "files": [
     "bin/*.js",
+    "dist/*.d.ts",
     "lib/**/*.js"
   ],
   "homepage": "https://github.com/intlify/cli#readme",
@@ -88,7 +89,7 @@
   },
   "scripts": {
     "build": "yarn build:transpile && yarn build:extract",
-    "build:docs": "api-docs-gen ./temp/cli.api.json -c ./docsgen.config.js -o ./",
+    "build:docs": "api-docs-gen ./temp/cli.api.json -c ./docsgen.config.js -o ./ -g noprefix",
     "build:extract": "api-extractor run -l -c ./api-extractor.json",
     "build:transpile": "tsc -p .",
     "clean": "npm-run-all clean:*",
@@ -108,5 +109,6 @@
     "test:unit": "jest --env node",
     "test:watch": "jest --env node --watch",
     "watch": "tsc -p . --watch"
-  }
+  },
+  "types": "dist/cli.d.ts"
 }

src/api.ts

@@ -0,0 +1,141 @@
+import path from 'path'
+import { promises as fs } from 'fs'
+import { debug as Debug } from 'debug'
+import { generateJSON, generateYAML } from './generator/index'
+import { globAsync } from './utils'
+
+const SUPPORTED_FORMAT = ['.json', '.json5', '.yaml', '.yml']
+const debug = Debug('@intlify/cli:api')
+
+/**
+ * Compile Error Codes
+ *
+ * @remarks
+ * The error codes of {@link compile} function
+ *
+ * @public
+ */
+export const enum CompileErrorCodes {
+  /**
+   * Not supported format
+   */
+  NOT_SUPPORTED_FORMAT = 1,
+  /**
+   * Internal compile warning
+   */
+  INTERNAL_COMPILE_WARNING,
+  /**
+   * Internal compile error
+   */
+  INTERNAL_COMPILE_ERROR
+}
+
+/**
+ * Compile Options
+ *
+ * @remarks
+ * This optioins is used at {@link compile} function
+ *
+ * @public
+ */
+export interface CompileOptions {
+  /**
+   * Compile Error handler
+   */
+  onError?: (code: number, source: string, output: string, msg?: string) => void
+  /**
+   * Compile handler
+   */
+  onCompile?: (source: string, output: string) => void
+}
+
+/**
+ * Compile i18n resources
+ *
+ * @param source - the i18n resource source path, you can use glob pattern
+ * @param output - the compiled i18n resource output path
+ * @param options - {@link CompileOptions}
+ *
+ * @remarks
+ * This functoin is **asyncronous** function. If you want to get about error details, use the handler of {@link CompileOptions} and {@link CompileErrorCodes}
+ *
+ * @returns `true` when all i18n resource successfuly compile, not `false`
+ *
+ * @public
+ */
+export async function compile(
+  source: string,
+  output: string,
+  options: CompileOptions = {}
+): Promise<boolean> {
+  let ret = true
+
+  const targets = await globAsync(source)
+  debug('compile: targets', targets)
+
+  for (const target of targets) {
+    const parsed = path.parse(target)
+    debug('parsed', parsed)
+    if (!parsed.ext) {
+      continue
+    }
+    const filename = `${parsed.name}.js`
+    const generatePath = path.resolve(output, filename)
+    if (!SUPPORTED_FORMAT.includes(parsed.ext)) {
+      options.onError &&
+        options.onError(
+          CompileErrorCodes.NOT_SUPPORTED_FORMAT,
+          target,
+          generatePath
+        )
+      ret = false
+      continue
+    }
+    const source = await fs.readFile(target, { encoding: 'utf-8' })
+    const generate = /\.json?5/.test(parsed.ext) ? generateJSON : generateYAML
+    let occuredError = false
+    const { code } = generate(source, {
+      type: 'plain',
+      filename: target,
+      env: 'production',
+      onError: (msg: string): void => {
+        occuredError = true
+        options.onError &&
+          options.onError(
+            CompileErrorCodes.INTERNAL_COMPILE_ERROR,
+            target,
+            generatePath,
+            msg
+          )
+        ret = false
+      },
+      onWarn: (msg: string): void => {
+        options.onError &&
+          options.onError(
+            CompileErrorCodes.INTERNAL_COMPILE_WARNING,
+            target,
+            generatePath,
+            msg
+          )
+        ret = false
+      }
+    })
+    if (!occuredError) {
+      await writeGenerateCode(output, filename, code)
+      options.onCompile && options.onCompile(target, generatePath)
+    }
+  }
+
+  return ret
+}
+
+export async function writeGenerateCode(
+  target: string,
+  filename: string,
+  code: string
+): Promise<string> {
+  await fs.mkdir(target, { recursive: true })
+  const generatePath = path.resolve(target, filename)
+  await fs.writeFile(generatePath, code)
+  return generatePath
+}

src/commands/compile.ts

@@ -1,11 +1,10 @@
 import path from 'path'
-import { promises as fs } from 'fs'
 import chalk from 'chalk'
 import { Arguments, Argv } from 'yargs'
-import { generateJSON, generateYAML } from '../generator/index'
-import { globAsync } from '../utils'
+import { debug as Debug } from 'debug'
+import { CompileErrorCodes, compile } from '../api'
 
-const SUPPORTED_FORMAT = ['.json', '.json5', '.yaml', '.yml']
+const debug = Debug('@intlify/cli:compile')
 
 type CompileOptions = {
   source: string
@@ -36,59 +35,41 @@ export const handler = async (
 ): Promise<void> => {
   const output =
     args.output != null ? path.resolve(__dirname, args.output) : process.cwd()
-  const targets = await globAsync(args.source)
-  targets.forEach(async (target: string) => {
-    const parsed = path.parse(target)
-    if (!SUPPORTED_FORMAT.includes(parsed.ext)) {
-      console.warn(
-        chalk.yellow(
-          `${target}: Ignore compilation due to not supported '${parsed.ext}'`
-        )
-      )
-      return
-    }
-    const source = await fs.readFile(target, { encoding: 'utf-8' })
-    const generate = /\.json?5/.test(parsed.ext) ? generateJSON : generateYAML
-    const filename = `${parsed.name}.js`
-    const generatePath = path.resolve(output, filename)
-    let occuredError = false
-    const { code } = generate(source, {
-      type: 'plain',
-      filename: target,
-      env: 'production',
-      onError: (msg: string): void => {
-        occuredError = true
-        console.log(
-          chalk.green(`error compilation: ${target} -> ${generatePath}, ${msg}`)
-        )
-      },
-      onWarn: (msg: string): void => {
-        console.log(
-          chalk.yellow(
-            `warning compilation: ${target} -> ${generatePath}, ${msg}`
+  const ret = await compile(args.source, output, {
+    onCompile: (source: string, output: string): void => {
+      console.log(chalk.green(`success compilation: ${source} -> ${output}`))
+    },
+    onError: (
+      code: number,
+      source: string,
+      output: string,
+      msg?: string
+    ): void => {
+      switch (code) {
+        case CompileErrorCodes.NOT_SUPPORTED_FORMAT:
+          const parsed = path.parse(source)
+          console.warn(
+            chalk.yellow(
+              `${source}: Ignore compilation due to not supported '${parsed.ext}'`
+            )
+          )
+          break
+        case CompileErrorCodes.INTERNAL_COMPILE_WARNING:
+          console.log(
+            chalk.yellow(`warning compilation: ${source} -> ${output}, ${msg}`)
+          )
+          break
+        case CompileErrorCodes.INTERNAL_COMPILE_ERROR:
+          console.log(
+            chalk.green(`error compilation: ${source} -> ${output}, ${msg}`)
           )
-        )
+          break
+        default:
+          break
       }
-    })
-    if (!occuredError) {
-      const filename = `${parsed.name}.js`
-      await writeGenerateCode(output, filename, code)
-      console.log(
-        chalk.green(`success compilation: ${target} -> ${generatePath}`)
-      )
     }
   })
-}
-
-async function writeGenerateCode(
-  target: string,
-  filename: string,
-  code: string
-): Promise<string> {
-  await fs.mkdir(target, { recursive: true })
-  const generatePath = path.resolve(target, filename)
-  await fs.writeFile(generatePath, code)
-  return generatePath
+  debug('compile: ', ret)
 }
 
 export default {