@lcap/nasl 0.3.15-beta → 1.0.0-alpha.2

package/DEVELOPMENT.md

@@ -1,58 +1,42 @@
 # Development
 
-开发时，这块尽量能够单独发包。
-
-## 规范
-
-- 为了兼容 Vue，属性至少全部声明 undefined
-- 都声明 constructor
-- 按 JSON 创建节点时，优先使用 from
-- 添加和删除操作，先请求再变更；设置属性的话，简单一些先修改数据再请求
-- 发送请求处理数据，返回时按最小情况 pick
-### 增删改查定义方式
-
-#### 增1
-```
-const entity = new Entity({
-    serviceId: '292c8df3-a74b-4434-83ec-14eb7798bc5e',
-    ...
-});
-await entity.create();
-```
-
-#### 增2
-```
-await service.addEntity(entityOptions);
-```
-
-#### 删1
-```
-await entity.delete();
-```
-
-#### 删1
-```
-await service.removeEntity(entity);
-```
-
-#### 改1
-```
-entity.assign({ name: 'bbb' });
-entity.update();
-```
-
-#### 改2
-```
-entity.setName('bbb');
-```
-
-#### 查
-```
-const entity = new Entity({ id: 'e457acee-d69b-4f5b-bbe5-64ac8fdbf7ce' });
-entity.load(); => handle
-```
-
-#### [v] 查列表
+## 目录结构
+
+```
+- src/                          # 源文件
+    - common/                   # 通用类
+    - concepts/                 # 所有概念类
+    - decorators/               # 装饰器
+    - generator/                # 生成器
+    - manager/                  # 管理器（类型检查）
+    - server/                   # LanguageServer
+    - service/                  # 后端请求 Service
+    - templator/                # 生成实体拖拽的模板器
+    - terms/                    # 术语
+    - test/                     # 测试脚本，由于 ts 是统一编译，一般就放在 src 下面了
+    - translator/               # 翻译器（编译器的部分）
+    - utils/                    # 工具库
+```
+
+## 依赖层级
+
+大家不要反向引用。
+
+```mermaid
+graph BT;
+    service --> config
+    common --> service
+    common --> decorators
+    common --> translator
+    common --> utils
+    concepts --> common
+    server --> concepts
+    manager --> concepts
+    templator --> concepts
+    generator --> concepts
+    designer --> concepts
+    designer --> server
+    designer --> manager
+    designer --> templator
+    designer --> generator
 ```
-service.loadEntities(); => handle
-```

package/README.md

@@ -2,10 +2,83 @@
 
 Software Development Kit of NetEase Application Specific Language.
 
-网易轻舟低代码平台 NASL 语言软件开发工具包，支持在 Browser 和 Node.js 上使用。
+NASL SDK 是针对 NASL 投射编辑的无可视化的软件工具包，与用户在编辑器中的实际操作一致。轻舟低代码平台的 IDE 和前端生成服务便是主要以它为核心开发的。
 
-## 目录
+可运行在 现代浏览器 和 [Node.js](https://nodejs.org) (>=14) 环境上。
 
-- [NASL 规范描述文档]()
-- [前端 @lcap/asl 包的 TypeScript 文档]()
-- [前端 NASL 开发文档](./DEVELOPMENT.md)
+🧐 NASL SDK 主要包含以下功能：
+
+- NASL Object Model，即 NASL 语法树节点结合增删改查等行为的实例化对象，类似 HTML 之于 [DOM](https://developer.mozilla.org/zh-CN/docs/Web/API/Document_Object_Model/Introduction)、CSS 之于 [CSSOM](https://developer.mozilla.org/zh-CN/docs/Glossary/CSSOM)
+- 用于生成中间代码或 Vue 等最终代码的编译方法
+- 实体拖拽的方法
+- 请求、遍历树、去重名等工具库
+- ...
+
+NASL SDK 不包含以下功能：
+
+- 应用本身的创建和删除
+- 应用的发布
+
+## 快速开始 ⏱️
+
+我们以一个在 Node.js 环境运行的脚本为例，您可以在上面进行快速开发。这里推荐使用 [TypeScript](https://www.typescriptlang.org)，它可以给您提供很方便的关于 NASL Object Model 的类型提示。
+
+### 1. 准备
+
+安装 [Node.js](https://nodejs.org) (>=14)
+
+### 2. 安装
+
+```shell
+npm i --save nasl@1.0.0-alpha
+```
+
+### 3. 三种方式
+
+#### Browser 方式
+
+```ts
+import * as nasl from 'nasl';
+
+async function start() {
+    await nasl.connect('http', '/some/path');
+    const app = await nasl.loadApp('aw9fajff90j323');
+    // Do your things
+}
+
+start();
+```
+
+#### Node.js 请求方式
+
+```ts
+import * as nasl from 'nasl';
+
+async function start() {
+    await nasl.connect('http', 'http://dogfood.lcap.163yun.com', 'username', 'password');
+    const app = await nasl.loadApp('aw9fajff90j323');
+    // Do your things
+}
+
+start();
+```
+
+#### Node.js 本地文件方式
+
+```ts
+import * as nasl from 'nasl';
+
+async function start() {
+    await nasl.connect('file', './demo-app.json');
+    const app = await nasl.loadApp();
+}
+
+start();
+```
+
+## Test
+
+### 测试一个文件
+```bash
+npm run test:one -- src/test/integration/connect-file.ts
+```

package/bin/naslc

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+// TODO

package/docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/docs/assets/custom.css

@@ -0,0 +1,3 @@
+body {
+    /* font-size: 12px; */
+}

package/docs/assets/highlight.css

@@ -0,0 +1,78 @@
+:root {
+    --light-hl-0: #000000;
+    --dark-hl-0: #D4D4D4;
+    --light-hl-1: #AF00DB;
+    --dark-hl-1: #C586C0;
+    --light-hl-2: #0000FF;
+    --dark-hl-2: #569CD6;
+    --light-hl-3: #001080;
+    --dark-hl-3: #9CDCFE;
+    --light-hl-4: #A31515;
+    --dark-hl-4: #CE9178;
+    --light-hl-5: #795E26;
+    --dark-hl-5: #DCDCAA;
+    --light-hl-6: #0070C1;
+    --dark-hl-6: #4FC1FF;
+    --light-hl-7: #008000;
+    --dark-hl-7: #6A9955;
+    --light-code-background: #F5F5F5;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --code-background: var(--dark-code-background);
+} }
+
+body.light {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --code-background: var(--light-code-background);
+}
+
+body.dark {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --code-background: var(--dark-code-background);
+}
+
+.hl-0 { color: var(--hl-0); }
+.hl-1 { color: var(--hl-1); }
+.hl-2 { color: var(--hl-2); }
+.hl-3 { color: var(--hl-3); }
+.hl-4 { color: var(--hl-4); }
+.hl-5 { color: var(--hl-5); }
+.hl-6 { color: var(--hl-6); }
+.hl-7 { color: var(--hl-7); }
+pre, code { background: var(--code-background); }