plainscript-lang 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +173 -738
- package/compiler/bundler.js +83 -12
- package/compiler/cli.js +74 -27
- package/compiler/dependency-detector.js +11 -0
- package/compiler/generator.js +372 -35
- package/compiler/lexer.js +2 -0
- package/compiler/parser.js +410 -28
- package/compiler/sourcemap.js +142 -0
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +98 -534
- package/docs/PLAINSCRIPT-SPEC.md +304 -551
- package/docs/index.html +127 -598
- package/docs/website/script.js +185 -1006
- package/docs/website/style.css +220 -656
- package/examples/ai-providers.pln +7 -0
- package/examples/arrays.pln +4 -12
- package/examples/async-errors.pln +18 -0
- package/examples/auth-api.pln +3 -50
- package/examples/auth-sessions.pln +32 -0
- package/examples/basics.pln +14 -0
- package/examples/bots.pln +13 -0
- package/examples/cache-and-jobs.pln +6 -28
- package/examples/cache-schedule.pln +22 -0
- package/examples/collections.pln +15 -0
- package/examples/concurrency.pln +12 -43
- package/examples/conditions.pln +22 -0
- package/examples/database.pln +6 -39
- package/examples/day2.pln +6 -6
- package/examples/day3.pln +4 -10
- package/examples/deployment.pln +3 -9
- package/examples/email-send.pln +3 -22
- package/examples/error-handling.pln +6 -54
- package/examples/expressions.pln +7 -40
- package/examples/file-uploads.pln +5 -34
- package/examples/files-and-config.pln +5 -46
- package/examples/files.pln +12 -0
- package/examples/football-backend/app.pln +21 -20
- package/examples/functions.pln +17 -0
- package/examples/hello.pln +2 -3
- package/examples/http-client.pln +3 -44
- package/examples/http.pln +11 -0
- package/examples/id-verification/app.pln +4 -3
- package/examples/id-verification/make-sample-id.js +29 -42
- package/examples/json.pln +11 -0
- package/examples/loops.pln +13 -11
- package/examples/modules/app.pln +3 -16
- package/examples/modules/main.pln +4 -0
- package/examples/modules/math.pln +5 -16
- package/examples/mongo.pln +33 -0
- package/examples/objects.pln +3 -11
- package/examples/ocr.pln +22 -0
- package/examples/packages.pln +6 -0
- package/examples/record-kinds.pln +6 -42
- package/examples/records.pln +15 -0
- package/examples/rest-api-fetch.pln +6 -90
- package/examples/rest-api.pln +5 -65
- package/examples/scheduled-tasks.pln +4 -23
- package/examples/search-and-filter.pln +4 -34
- package/examples/server.pln +5 -24
- package/examples/sessions-and-cookies.pln +4 -50
- package/examples/sqlite.pln +23 -0
- package/examples/start.pln +2 -2
- package/examples/stdlib.pln +4 -41
- package/examples/string-verbs.pln +16 -0
- package/examples/telegram-ai-bot.pln +19 -0
- package/examples/telegram-bot.pln +4 -40
- package/examples/testing.pln +13 -0
- package/examples/web-api.pln +27 -0
- package/examples/web-app.pln +4 -16
- package/examples/websocket-server.pln +5 -26
- package/examples/websocket.pln +13 -0
- package/examples/whatsapp-bot/pairing.pln +4 -5
- package/examples/whatsapp-bot/qr.pln +7 -3
- package/package.json +3 -2
|
@@ -1,540 +1,104 @@
|
|
|
1
|
-
# PlainScript
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
##
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
|
50
|
-
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
| `await Promise.all([...])` in one line | `all of [...]` is already awaited — `let results is all of [a(), b()]`. |
|
|
93
|
-
| Worker threads / parallel jobs | **IOPL-native `run in parallel ... end [as results]`** (existing, RFC-0011 ¶9) and `run background <call>` (existing). |
|
|
94
|
-
| Cancellation / AbortController | **Runtime `withTimeout(promise, ms)`** raises on timeout (this release). |
|
|
95
|
-
|
|
96
|
-
**Audit status:** `all/any/settled of`, `withTimeout` ship on top of the existing
|
|
97
|
-
`wait for`/`run in parallel`. **Gap closed.**
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## 4. Classes / object systems
|
|
102
|
-
|
|
103
|
-
The single biggest capability TypeScript users expect from a language. PlainScript
|
|
104
|
-
delivers it IOPL-native as **record kinds** — a compile-time-checked schema plus a
|
|
105
|
-
prose constructor — rather than `class`/`new`/`extends` syntax.
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
define a kind called "Person" with
|
|
109
|
-
name is ""
|
|
110
|
-
age is 0
|
|
111
|
-
end
|
|
112
|
-
|
|
113
|
-
let ada is create a Person with name "Ada" and age 17
|
|
114
|
-
print name of ada // "Ada"
|
|
115
|
-
|
|
116
|
-
// v2.4 near-English alternative:
|
|
117
|
-
when ada has field "name"
|
|
118
|
-
print ada name at position 1 in name of ada
|
|
119
|
-
done
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
- Fields declared with defaults; constructors **prompt for missing required
|
|
123
|
-
fields** at compile time; unknown constructor fields are a compile error.
|
|
124
|
-
- Kind objects are plain JS objects, so `jsonEncode`, `sendMail`, DB rows,
|
|
125
|
-
and every existing stdlib works on them unchanged.
|
|
126
|
-
- Attach behaviour with ordinary `define` functions that take the record
|
|
127
|
-
(`define describe(person) give name of person + " is " + age of person`).
|
|
128
|
-
- **Inheritance** is deliberately *composition-first*: `kind` + stdlib
|
|
129
|
-
`merge(a, b)` (existing) covers the 80%. Deep prototype chains are a
|
|
130
|
-
TypeScript *syntax*, not a capability we need to replicate.
|
|
131
|
-
|
|
132
|
-
| TypeScript | PlainScript resolution |
|
|
133
|
-
|-------------------------|------------------------|
|
|
134
|
-
| `class`, constructor | **IOPL-native `kind` + `create a X with ...`** (this release). |
|
|
135
|
-
| Fields / properties | `kind` fields; access via `name of x` / `x.name`. |
|
|
136
|
-
| Methods | Top-level `define` functions taking the record. |
|
|
137
|
-
| `this` | **Rationale: unnecessary** — functions receive the record explicitly (no context bugs). |
|
|
138
|
-
| `static` members | Module-level `let`/`define` are naturally static. |
|
|
139
|
-
| Extension / mixins | `merge(a, b)` (existing) + nested kinds. |
|
|
140
|
-
| Access modifiers | **Rationale: unnecessary** — single-process bundles; `_field` is convention. |
|
|
141
|
-
|
|
142
|
-
**Audit status:** Record kinds ship with tested constructors, field validation,
|
|
143
|
-
and JSON/serialization compat. **Gap closed.**
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
## 5. Iterators / generators
|
|
148
|
-
|
|
149
|
-
| TypeScript | PlainScript resolution |
|
|
150
|
-
|------------------|------------------------|
|
|
151
|
-
| `for...of` | `for each item in x ... end` (existing) — works on arrays, strings, Maps, Sets, generators. |
|
|
152
|
-
| Generator `function*` / `yield` | **IOPL-native `yield`** inside `define ... end` (this release) — a `define` containing `yield` compiles to a `function*`. |
|
|
153
|
-
| `[Symbol.iterator]` | Accessible via JS Gateway / `kind` producer (this release: `define` with `yield`). |
|
|
154
|
-
| Iterator helpers (`map`/`filter`/`reduce`) | **IOPL-native** `gather each ... giving`, `filter each ... when`, `total each ... giving` (existing, functional map/filter/reduce). |
|
|
155
|
-
| Spread `/ rest` | **IOPL-native `spread of x`** unfolds an iterable into a new array (this release). |
|
|
156
|
-
| Lazy sequences | Generators via `yield` + `for each` (this release). |
|
|
157
|
-
|
|
158
|
-
**Audit status:** Generators, spread, and functional iteration ship. **Gap closed.**
|
|
159
|
-
|
|
160
|
-
---
|
|
161
|
-
|
|
162
|
-
## 6. Collections
|
|
163
|
-
|
|
164
|
-
| TypeScript | PlainScript resolution |
|
|
165
|
-
|--------------|------------------------|
|
|
166
|
-
| Array | Literals `[...]`, `first/last/N-th from`, `length(x)`, `add/remove`, `gather/filter/total` (all existing). |
|
|
167
|
-
| Map | **Runtime stdlib** `keyMap()`/`mapSet/mapGet/mapDelete/mapHas` wrapping JS `Map` (this release). |
|
|
168
|
-
| Set | **Runtime stdlib** `set()`/`unique(x)` (unique exists) — `addToSet/removeFromSet` (this release). |
|
|
169
|
-
| Object | `merge`, `keys`, `values`, `hasKey`, `of` chains (existing) + `fieldsOf` (this release). |
|
|
170
|
-
| Tuple | **`kind` with positional fields** (§4). |
|
|
171
|
-
|
|
172
|
-
**v2.4 enhancement:** Near-English syntax for collection access:
|
|
173
|
-
|
|
1
|
+
# PlainScript 1.0.3 Capability Audit
|
|
2
|
+
|
|
3
|
+
This audit is based on what the compiler actually supports right now.
|
|
4
|
+
If `plainscript check` validates it, it's listed here.
|
|
5
|
+
|
|
6
|
+
## Core Language
|
|
7
|
+
|
|
8
|
+
| Capability | Status | Current source form |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| Variables and assignment | Implemented | `remember x as 1`, `x becomes 2` |
|
|
11
|
+
| Strings and templates | Implemented | `"text"`, `` `Hello ${name}` `` |
|
|
12
|
+
| Numbers and BigInt | Implemented | `3.14`, `42n` |
|
|
13
|
+
| Arrays and objects | Implemented | `[1, 2]`, `{name: "Ada"}` |
|
|
14
|
+
| Records and record kinds | Implemented | `define a kind called "User" with ... done` |
|
|
15
|
+
| Conditions | Implemented | `if ... otherwise ... done` |
|
|
16
|
+
| Functions | Implemented | `make add(a, b) ... done` |
|
|
17
|
+
| Generators | Implemented | `yield value` |
|
|
18
|
+
| For and while loops | Implemented | `for each ... done`, `while ... done` |
|
|
19
|
+
| Match and switch | Implemented | `match value against ... done` |
|
|
20
|
+
| Loop control | Implemented | `break`, `continue` |
|
|
21
|
+
| Classes and `new` | Implemented | JavaScript-compatible class forms |
|
|
22
|
+
|
|
23
|
+
## Modules and Runtime
|
|
24
|
+
|
|
25
|
+
| Capability | Status | Notes |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| Relative PlainScript imports | Implemented | Imported files are bundled |
|
|
28
|
+
| Named imports and exports | Implemented | `import { name } from "./file.pln"` |
|
|
29
|
+
| npm packages | Implemented | `use package-name` and CLI dependency detection |
|
|
30
|
+
| JSON | Implemented | `jsonEncode`, `jsonDecode`, JSON response blocks |
|
|
31
|
+
| Files and paths | Implemented | Read/write, bytes, folders, path helpers |
|
|
32
|
+
| Crypto and auth helpers | Implemented | Hashes, passwords, tokens |
|
|
33
|
+
| Async/await | Implemented | `wait for`, `await`, async propagation |
|
|
34
|
+
| Concurrency | Implemented | `allOf`, `anyOf`, `settledOf`, `withTimeout` |
|
|
35
|
+
| Errors and retries | Implemented | `try`, `recover`, `finally`, `retry` |
|
|
36
|
+
| Native tests | Implemented | `test` and `check` assertions |
|
|
37
|
+
|
|
38
|
+
## Web and Services
|
|
39
|
+
|
|
40
|
+
| Capability | Status | Current source form |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| Express web app | Implemented | `web app` |
|
|
43
|
+
| HTTP routes | Implemented | `route get "/path" ... done` |
|
|
44
|
+
| JSON responses | Implemented | `reply json ... done` |
|
|
45
|
+
| CORS and fallback | Implemented | `allow cors`, `when nothing matches` |
|
|
46
|
+
| Request accessors | Implemented | `body`, `param`, `query`, `header`, uploads |
|
|
47
|
+
| Cookies and sessions | Implemented | `set cookie`, `enable sessions` |
|
|
48
|
+
| API keys and rate limits | Implemented | `require api key`, `limit requests` |
|
|
49
|
+
| File uploads | Implemented | `accept uploads` |
|
|
50
|
+
| HTTP client | Implemented | `get`, `post`, `put`, `patch`, `delete` |
|
|
51
|
+
| SQLite | Implemented | native and WebAssembly drivers |
|
|
52
|
+
| PostgreSQL generation | Implemented | `postgres connection` |
|
|
53
|
+
| SQL parameter binding | Implemented | `{variable}` placeholders |
|
|
54
|
+
| Email | Implemented | `mail transport`, `send mail` |
|
|
55
|
+
| Schedules and jobs | Implemented | `every`, `schedule`, `run background` |
|
|
56
|
+
| WebSockets | Implemented | `websocket server` |
|
|
57
|
+
| Redis/in-memory cache | Implemented | `cache`, `cacheGet`, `cacheSet` |
|
|
58
|
+
| Telegram bots | Implemented | `bot`, message/callback handlers |
|
|
59
|
+
| AI providers | Implemented | `chat`, `chatWith`, `embedText`, provider presets |
|
|
60
|
+
| WhatsApp bots | Implemented | `whatsapp bot` |
|
|
61
|
+
| OCR | Implemented | `ocr path of file as text` |
|
|
62
|
+
|
|
63
|
+
## Canonical Examples
|
|
64
|
+
|
|
65
|
+
Here are the example files that exercise each capability:
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
examples/basics.pln
|
|
69
|
+
examples/conditions.pln
|
|
70
|
+
examples/loops.pln
|
|
71
|
+
examples/functions.pln
|
|
72
|
+
examples/records.pln
|
|
73
|
+
examples/collections.pln
|
|
74
|
+
examples/json.pln
|
|
75
|
+
examples/files.pln
|
|
76
|
+
examples/packages.pln
|
|
77
|
+
examples/http.pln
|
|
78
|
+
examples/sqlite.pln
|
|
79
|
+
examples/web-api.pln
|
|
80
|
+
examples/auth-sessions.pln
|
|
81
|
+
examples/async-errors.pln
|
|
82
|
+
examples/concurrency.pln
|
|
83
|
+
examples/websocket.pln
|
|
84
|
+
examples/cache-schedule.pln
|
|
85
|
+
examples/bots.pln
|
|
86
|
+
examples/ocr.pln
|
|
87
|
+
examples/testing.pln
|
|
88
|
+
examples/modules/
|
|
89
|
+
examples/football-backend/
|
|
90
|
+
examples/id-verification/
|
|
91
|
+
examples/whatsapp-bot/
|
|
174
92
|
```
|
|
175
|
-
// Array indexing
|
|
176
|
-
let first be name at position 1 in players
|
|
177
93
|
|
|
178
|
-
|
|
179
|
-
when user has field "email"
|
|
180
|
-
show "has email"
|
|
181
|
-
done
|
|
94
|
+
Run this to make sure everything still compiles:
|
|
182
95
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
show "valid email"
|
|
186
|
-
done
|
|
96
|
+
```bash
|
|
97
|
+
find examples -name '*.pln' -exec node compiler/cli.js check {} \;
|
|
187
98
|
```
|
|
188
99
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
---
|
|
192
|
-
|
|
193
|
-
## 7. Decorators / metaprogramming
|
|
194
|
-
|
|
195
|
-
| TypeScript | PlainScript resolution |
|
|
196
|
-
|-----------------|------------------------|
|
|
197
|
-
| Decorators | **Rationale: unnecessary as syntax.** What decorators achieve — wrapping functions, logging, timing, auth — is done IOPL-natively with `when ... happens` pub/sub (existing), `run background`, and the JS Gateway. A bespoke `@` grammar adds complexity without new capability. |
|
|
198
|
-
| Method/class metadata | **Rationale: mostly unnecessary.** Since methods are top-level functions (no `this`), there is nothing to decorate. |
|
|
199
|
-
| `Proxy` / `Reflect` | **JS Gateway** exposes raw `Proxy`/`Reflect` when genuinely needed (existing). |
|
|
200
|
-
|
|
201
|
-
**Audit status:** Rationale documented; no decorator syntax. **No gap for 80%.**
|
|
202
|
-
|
|
203
|
-
---
|
|
204
|
-
|
|
205
|
-
## 8. Symbols / well-known keys
|
|
206
|
-
|
|
207
|
-
- **Rationale: unnecessary as a user-facing feature.** `Symbol` keys matter for
|
|
208
|
-
iterator identity and library protocol, both of which are *inside* the compiler
|
|
209
|
-
(generator `yield` uses `Symbol.iterator` transparently). Exposing `Symbol` as
|
|
210
|
-
an IOPL statement would leak implementation detail without capability gain.
|
|
211
|
-
- When a library genuinely requires a user-provided symbol, the **JS Gateway**
|
|
212
|
-
provides it.
|
|
213
|
-
|
|
214
|
-
**Audit status:** Rationale documented. **No gap.**
|
|
215
|
-
|
|
216
|
-
---
|
|
217
|
-
|
|
218
|
-
## 9. Proxies / reflection / duck typing
|
|
219
|
-
|
|
220
|
-
| TypeScript | PlainScript resolution |
|
|
221
|
-
|--------------|------------------------|
|
|
222
|
-
| `Reflect.*` | **Runtime reflection stdlib**: `typeOf(x)`, `fieldsOf(x)`, `hasField(rec, key)`, `valueOf(rec,key)`, `sizeOf(x)` (this release). |
|
|
223
|
-
| `Object.keys`| `keys(x)` (existing) / `fieldsOf(x)` (this release). |
|
|
224
|
-
| Duck typing | Provided naturally: functions receive records and read `name of x` regardless of construction site. |
|
|
225
|
-
|
|
226
|
-
**Audit status:** Runtime reflection ships. **Gap closed.**
|
|
227
|
-
|
|
228
|
-
---
|
|
229
|
-
|
|
230
|
-
## 10. Binary data
|
|
231
|
-
|
|
232
|
-
| TypeScript / Node | PlainScript resolution |
|
|
233
|
-
|-------------------|------------------------|
|
|
234
|
-
| `Buffer` | **Runtime stdlib** `textToBytes(s)`, `bytesToText(b)` (this release); `readBytes`/`writeBytes` exist. |
|
|
235
|
-
| `base64` | **Runtime stdlib** `base64Encode(x)`, `base64Decode(s)` (this release). |
|
|
236
|
-
| `ArrayBuffer`/typed arrays | Accessible through `readBytes()` returning a `Buffer` and the JS Gateway. |
|
|
237
|
-
| CRC / hash | `hashPassword` (existing) + `sha256(text)` (this release). |
|
|
238
|
-
|
|
239
|
-
**Audit status:** Binary + encoding stdlib ships. **Gap closed.**
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
## 11. Workers / processes
|
|
244
|
-
|
|
245
|
-
| TypeScript / Node | PlainScript resolution |
|
|
246
|
-
|-------------------|------------------------|
|
|
247
|
-
| Worker threads | **IOPL-native `run in parallel ... end`** (existing) and `run background <call>` (existing). |
|
|
248
|
-
| Child processes | **Runtime stdlib `runCommand(cmd, args)`** (async, captures stdout/stderr/exit) (this release). |
|
|
249
|
-
| `process.exit` | `exit(code)` (existing); `env()` (existing). |
|
|
250
|
-
| Signals / IPC | **Rationale: unnecessary for 80%** — batch/parallel covers CPU-bound; cross-process messaging is niche. JS Gateway for the rest. |
|
|
251
|
-
|
|
252
|
-
**Audit status:** Process execution ships; workers via existing parallel model.
|
|
253
|
-
**Gap closed.**
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
## 12. Filesystem
|
|
258
|
-
|
|
259
|
-
| Node fs | PlainScript resolution |
|
|
260
|
-
|--------------------|------------------------|
|
|
261
|
-
| Read/write text | `read`/`readFile`, `write`/`writeFile`, `appendFile` (all existing). |
|
|
262
|
-
| Binary | `readBytes`/`writeBytes` (existing). |
|
|
263
|
-
| Metadata | `fileExists`, `fileSize(path)`, `fileType(path)`, `lastModified(path)` (this release). |
|
|
264
|
-
| Directory ops | `makeFolder`, `deleteFolder`, `listFolder` (existing), `walkFolder(dir)` recursive (this release). |
|
|
265
|
-
| Copy/move/delete | `copyFile`, `moveFile`, `deleteFile` (existing). |
|
|
266
|
-
| Path helpers | `joinPath`, `baseName`, `folderOf(path)`, `extensionOf(path)` (this release). |
|
|
267
|
-
|
|
268
|
-
**Audit status:** Filesystem suite extended to metadata/walk/path. **Gap closed.**
|
|
269
|
-
|
|
270
|
-
---
|
|
271
|
-
|
|
272
|
-
## 13. Streams
|
|
273
|
-
|
|
274
|
-
| Node stream | PlainScript resolution |
|
|
275
|
-
|--------------------|------------------------|
|
|
276
|
-
| Read line-by-line | **IOPL-native `stream "file" as line ... end`** (existing). |
|
|
277
|
-
| Write append | `writeLine(file, text)` / `appendLine(file, text)` (this release). |
|
|
278
|
-
| Transform / pipe | **Rationale: necessary via JS Gateway only** — stream pipelines are an implementation detail; `write`/`read`/`stream` cover I/O. |
|
|
279
|
-
|
|
280
|
-
**Audit status:** Stream I/O rounded out. **Gap mostly closed.**
|
|
281
|
-
|
|
282
|
-
---
|
|
283
|
-
|
|
284
|
-
## 14. Networking
|
|
285
|
-
|
|
286
|
-
| Node net/http | PlainScript resolution |
|
|
287
|
-
|--------------------------|------------------------|
|
|
288
|
-
| HTTP server | `web app` + `route` + `start` (existing) and Express form (existing). |
|
|
289
|
-
| HTTP client | `get/post/put/patch/delete "<url>"` + `wait for fetch` (existing). |
|
|
290
|
-
| WebSocket server/client | `websocket server on ...` (existing, server side). |
|
|
291
|
-
| TCP server / client | **IOPL-native — omitted with rationale:** Node `net` is low-level; the 80% uses HTTP/WebSocket. Provided by JS Gateway on demand. |
|
|
292
|
-
| TLS / DNS / UDP | **Rationale: omitted** (niche; JS Gateway / `use`). |
|
|
293
|
-
|
|
294
|
-
**Audit status:** HTTP/WS cover the target; TCP documented as rationale.
|
|
295
|
-
**Gap closed for 80%.**
|
|
296
|
-
|
|
297
|
-
---
|
|
298
|
-
|
|
299
|
-
## 15. Serialization / configuration
|
|
300
|
-
|
|
301
|
-
| TypeScript / Node | PlainScript resolution |
|
|
302
|
-
|-------------------|------------------------|
|
|
303
|
-
| JSON | `jsonEncode`/`jsonDecode` (existing). |
|
|
304
|
-
| YAML | **Runtime stdlib `yamlDecode(s)`/`yamlEncode(v)`** (this release). |
|
|
305
|
-
| `.env` files | **IOPL-native `load env file "....env"`** statement + `envFile("path")` fallback (this release). |
|
|
306
|
-
| Config files | `loadEnvFile`; plus `plainscript.config.json` build config (existing). |
|
|
307
|
-
| `.toml` | **Rationale: niche** — YAML+JSON+env covers configuration; JS Gateway for TOML. |
|
|
308
|
-
| Binary serialization (msgpack/buffer) | `textToBytes`/`bytesToText`/`base64` (this release). |
|
|
309
|
-
|
|
310
|
-
**Audit status:** YAML + env-file configuration ship. **Gap closed.**
|
|
311
|
-
|
|
312
|
-
---
|
|
313
|
-
|
|
314
|
-
## 16. CLI tooling
|
|
315
|
-
|
|
316
|
-
| TypeScript / Node | PlainScript resolution |
|
|
317
|
-
|-------------------|------------------------|
|
|
318
|
-
| `process.argv` | **Runtime stdlib `args()`** returns the command-line argument array (this release). |
|
|
319
|
-
| argparse prompts | `ask "..." as x` (existing). |
|
|
320
|
-
| Subprocess CLI | `runCommand` (this release, §11). |
|
|
321
|
-
|
|
322
|
-
**Audit status:** `args()` ships. **Gap closed.**
|
|
323
|
-
|
|
324
|
-
---
|
|
325
|
-
|
|
326
|
-
## 17. Testing
|
|
327
|
-
|
|
328
|
-
| TypeScript / Node | PlainScript resolution |
|
|
329
|
-
|-------------------|------------------------|
|
|
330
|
-
| Test runner | **IOPL-native `test "name" ... end` blocks** with `check a equals b`, `check a is true`, `check raises` (this release). |
|
|
331
|
-
| Assertions | `check a equals b` / `check a contains b` / `check a raises <msg>` (this release). |
|
|
332
|
-
| Suite grouping | `test` blocks run in order; `check` failures print and exit `1` (this release). |
|
|
333
|
-
|
|
334
|
-
**v2.4 enhancement:** The near-English syntax extends to testing:
|
|
335
|
-
|
|
336
|
-
```
|
|
337
|
-
test "string checks"
|
|
338
|
-
check name starts as "Ay"
|
|
339
|
-
check name ends as "le"
|
|
340
|
-
check name made of "oku"
|
|
341
|
-
done
|
|
342
|
-
|
|
343
|
-
test "comparisons"
|
|
344
|
-
check age more than 18
|
|
345
|
-
check status same as "active"
|
|
346
|
-
done
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
**Audit status:** A native test DSL ships — no external runner needed. **Gap closed.**
|
|
350
|
-
|
|
351
|
-
---
|
|
352
|
-
|
|
353
|
-
## 18. JavaScript Gateway (escape hatch)
|
|
354
|
-
|
|
355
|
-
The **JavaScript Gateway** (`javascript ... end`, RFC-0011 §10) is the universal
|
|
356
|
-
fallback that closes *every* remaining micro-gap — any of TypeScript's capabilities
|
|
357
|
-
that is expressible in JS is reachable here without leaving PlainScript. This
|
|
358
|
-
single feature is why the audit can be honest about the many "rationale: omitted"
|
|
359
|
-
rows without reducing capability parity.
|
|
360
|
-
|
|
361
|
-
**Audit status:** Preexisting; retained.
|
|
362
|
-
|
|
363
|
-
---
|
|
364
|
-
|
|
365
|
-
## 19. Package / library authoring
|
|
366
|
-
|
|
367
|
-
| Capability | PlainScript resolution |
|
|
368
|
-
|-----------------------|------------------------|
|
|
369
|
-
| Publish npm library | `plainscript build` → `dist/`; `main`/`prepare` in package.json (existing). |
|
|
370
|
-
| Named exports | **IOPL-native `export <name>`** marks a top-level symbol for export; imported bindings re-exportable (this release). |
|
|
371
|
-
| Consumer API | `module.exports` of top-level `define` (existing) + explicit `export` (this release). |
|
|
372
|
-
| `exports` map / ESM | Standard `package.json` semantics (project model, existing). |
|
|
373
|
-
|
|
374
|
-
**Audit status:** export statement ships. **Gap closed.**
|
|
375
|
-
|
|
376
|
-
---
|
|
377
|
-
|
|
378
|
-
## 20. Summary scoring
|
|
379
|
-
|
|
380
|
-
| Area | Status |
|
|
381
|
-
|----------------------------|--------|
|
|
382
|
-
| Advanced typing/generics | ✅ runtime kinds + reflection; type grammar rationalised |
|
|
383
|
-
| Modules/imports/exports | ✅ named imports + loadModule + export |
|
|
384
|
-
| Async & concurrency | ✅ all/any/settled of, withTimeout |
|
|
385
|
-
| Classes/objects | ✅ record kinds |
|
|
386
|
-
| Iterators/generators | ✅ yield + spread of |
|
|
387
|
-
| Collections | ✅ Map/Set stdlib |
|
|
388
|
-
| Decorators/metadata | ⚪ documented (unnecessary) |
|
|
389
|
-
| Symbols | ⚪ documented (unnecessary) |
|
|
390
|
-
| Proxies/reflection | ✅ runtime reflection stdlib |
|
|
391
|
-
| Binary data | ✅ base64/bytes/sha256 |
|
|
392
|
-
| Workers/processes | ✅ runCommand + parallel |
|
|
393
|
-
| Filesystem | ✅ metadata/walk/path |
|
|
394
|
-
| Streams | ✅ writeLine/appendLine |
|
|
395
|
-
| Networking | ✅ HTTP/WS; TCP rationalised |
|
|
396
|
-
| Serialization/config | ✅ YAML + env-file |
|
|
397
|
-
| CLI tooling | ✅ args() + runCommand |
|
|
398
|
-
| Testing | ✅ test/check DSL |
|
|
399
|
-
| Package/library authoring | ✅ export + build model |
|
|
400
|
-
| v2.4 Near-English syntax | ✅ English comparisons, access, calls, error handling |
|
|
401
|
-
| JavaScript Gateway | ✅ universal fallback |
|
|
402
|
-
|
|
403
|
-
**Legend:** ✅ shipped + tested · ⚪ intentionally omitted with rationale.
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
## 21. 1.0.2 readiness gate
|
|
408
|
-
|
|
409
|
-
The audit is **complete** only when:
|
|
410
|
-
|
|
411
|
-
1. Every row above has a **shipped implementation with tests** or an **explicit
|
|
412
|
-
rationale** (both present in this document).
|
|
413
|
-
2. `npm test` is green with the new capability tests included.
|
|
414
|
-
3. The runtime stdlib table, knowledge base, and README document every new
|
|
415
|
-
capability.
|
|
416
|
-
|
|
417
|
-
Until then the package version remains **below 1.0.2**.
|
|
418
|
-
|
|
419
|
-
---
|
|
420
|
-
|
|
421
|
-
## 22. v2.2.0 — AI/ML, data/storage & web additions
|
|
422
|
-
|
|
423
|
-
The v2.0–v2.2 releases close further gaps beyond the 1.0.2 audit across the
|
|
424
|
-
AI/ML, data/storage and web/full-stack surface. All features below are
|
|
425
|
-
IOPL-native (intent-oriented) rather than TypeScript-syntax clones.
|
|
426
|
-
|
|
427
|
-
### AI / ML (module `ai`)
|
|
428
|
-
|
|
429
|
-
| Capability | IOPL stdlib |
|
|
430
|
-
| -------------------------------------------- | --------------------------------------------------------------------------- |
|
|
431
|
-
| LLM chat completion | `chat(model, messages, {options})` → text, async, OpenAI-compatible API |
|
|
432
|
-
| Text embeddings | `embedText(model, text, {options})` → vector, async |
|
|
433
|
-
| Vector similarity (cosine) | `similarity(a, b)` → -1..1 (identical → 1, orthogonal → 0, opposite → -1) |
|
|
434
|
-
| Auto-tagging convenience | `ai_tags(text)` → topic/category tags |
|
|
435
|
-
| Post / content generation | `ai_post(subject, ideas, options)` → generated prose |
|
|
436
|
-
| Auth | `OPENAI_API_KEY` env (override via `options.apiKey`/`options.baseURL`) |
|
|
437
|
-
|
|
438
|
-
**Audit status:** chat, embeddings, similarity ship with runtime tests; tag/post
|
|
439
|
-
compose the same runtime. **Gap closed.**
|
|
440
|
-
|
|
441
|
-
### Data / storage
|
|
442
|
-
|
|
443
|
-
| Capability | IOPL stdlib |
|
|
444
|
-
| -------------------- | --------------------------------------------------------------------------- |
|
|
445
|
-
| SQLite persistence | `http`+`db` runtime, `sql` queries, `table`/`row`/`query` DSL (existing) |
|
|
446
|
-
| In-memory cache fallback | `cacheGet/cacheSet/cacheDelete` use a Map-based store with TTL when no Redis is configured |
|
|
447
|
-
| Server-managed cache | Redis-backed cache when configured (existing) |
|
|
448
|
-
| Redis cache | existing TTL semantics, now with graceful no-config fallback |
|
|
449
|
-
| Pagination | `paginate(list, page, perPage)` → `{items, count, page, pages, perPage, hasNext, hasPrev}` |
|
|
450
|
-
|
|
451
|
-
**Audit status:** paginate + in-memory cache fallback ship and are tested.
|
|
452
|
-
**Gap closed.**
|
|
453
|
-
|
|
454
|
-
### Web / full-stack
|
|
455
|
-
|
|
456
|
-
| Capability | IOPL stdlib |
|
|
457
|
-
| ------------- | ------------------------------------------------------------------ |
|
|
458
|
-
| Request body | route-scoped `body(...)` accessor: `body()` → raw, `body("field")` → field |
|
|
459
|
-
| Redirect | `redirect to "<url>"` statement inside a route handler (`res.redirect`) |
|
|
460
|
-
| (existing) | routes, status, sessions, uploads, cookies, WebSocket, OAuth, email, schedules |
|
|
461
|
-
|
|
462
|
-
**Audit status:** `body` + `redirect to` ship, route-guarded with teaching
|
|
463
|
-
errors, compile-verified. **Gap closed.**
|
|
464
|
-
|
|
465
|
-
### Core collections & string primitives (module `coll`)
|
|
466
|
-
|
|
467
|
-
`range`, `clamp`, `first`, `last`, `flatten`, `includes`, `pick`, `omit`,
|
|
468
|
-
`groupBy`, `startsWith`, `endsWith`, `truncate`, `padStart`, `padEnd` — all
|
|
469
|
-
runtime-tested. `contains` is a reserved lexer keyword, so the membership helper
|
|
470
|
-
is named `includes`.
|
|
471
|
-
|
|
472
|
-
**Audit status:** shipped + tested. **Gap closed.**
|
|
473
|
-
|
|
474
|
-
> **Note on v2.2.0 testing:** `npm test` may not fully run in constrained
|
|
475
|
-
> sandboxes where native deps (`express`, `sql.js`, `ws`) cannot be installed;
|
|
476
|
-
> web/HTTP features are therefore **compile-verified** there. Core language,
|
|
477
|
-
> collections, AI (with a live key), and cache fallback run with real tests.
|
|
478
|
-
|
|
479
|
-
---
|
|
480
|
-
|
|
481
|
-
## 23. v2.4 — Near-English Syntax Additions
|
|
482
|
-
|
|
483
|
-
The v2.4 release introduces near-English syntax forms that make PlainScript code read like natural sentences. These forms improve readability and lower the barrier for non-programmers while maintaining full capability parity with TypeScript/Node.js.
|
|
484
|
-
|
|
485
|
-
### Readability & Comparisons
|
|
486
|
-
|
|
487
|
-
| Capability | v2.4 English Syntax | Existing Equivalent |
|
|
488
|
-
|-------------------------|----------------------------------------------------------|------------------------------|
|
|
489
|
-
| Greater than | `a more than b` | `a is greater than b` |
|
|
490
|
-
| Less than | `a fewer than b` | `a is less than b` |
|
|
491
|
-
| Strict equality | `a same as b` | `a is equal to b` |
|
|
492
|
-
| Strict inequality | `a different from b` | `a is not b` |
|
|
493
|
-
| Starts with | `name starts as "x"` | `name starts with "x"` |
|
|
494
|
-
| Ends with | `name ends as "x"` | `name ends with "x"` |
|
|
495
|
-
| Includes | `name made of "x"` | `name contains "x"` |
|
|
496
|
-
|
|
497
|
-
### Object & Array Access
|
|
498
|
-
|
|
499
|
-
| Capability | v2.4 English Syntax | Existing Equivalent |
|
|
500
|
-
|-------------------------|----------------------------------------------------------|------------------------------|
|
|
501
|
-
| Array indexing | `name at position N in list` | `list[N]` |
|
|
502
|
-
| Property check | `obj has field "name"` | `"name" in obj` |
|
|
503
|
-
|
|
504
|
-
### Control Flow
|
|
505
|
-
|
|
506
|
-
| Capability | v2.4 English Syntax | Existing Equivalent |
|
|
507
|
-
|-------------------------|----------------------------------------------------------|------------------------------|
|
|
508
|
-
| Ternary expression | `choosing cond then a otherwise b` | inline `when ... done` |
|
|
509
|
-
| Throw error | `raise "message"` | `throw "message"` |
|
|
510
|
-
| Simple recovery | `handled by` (no error binding) | `recover as err` |
|
|
511
|
-
|
|
512
|
-
### Function Calls
|
|
513
|
-
|
|
514
|
-
| Capability | v2.4 English Syntax | Existing Equivalent |
|
|
515
|
-
|-------------------------|----------------------------------------------------------|------------------------------|
|
|
516
|
-
| Call function | `func together arg1, arg2` | `func(arg1, arg2)` |
|
|
517
|
-
| Call and capture | `fill result with func together arg1, arg2` | `let result be func(arg1, arg2)` |
|
|
518
|
-
|
|
519
|
-
### Capability Gap Closure
|
|
520
|
-
|
|
521
|
-
The v2.4 near-English syntax addresses several readability gaps identified in earlier audits:
|
|
522
|
-
|
|
523
|
-
1. **Comparison verbosity** — Prior versions required `is greater than`, `is less than`, etc. The new `more than`/`fewer than` forms reduce cognitive load and read more naturally.
|
|
524
|
-
|
|
525
|
-
2. **String checking readability** — `starts as`, `ends as`, `made of` are more intuitive than `starts with`, `ends with`, `contains` for developers coming from natural language.
|
|
526
|
-
|
|
527
|
-
3. **Ternary readability** — The `choosing ... then ... otherwise` form replaces nested `when ... done` blocks for simple conditional assignment, closing the gap with TypeScript's `? :` operator in readability.
|
|
528
|
-
|
|
529
|
-
4. **Error handling clarity** — `raise` is clearer than `throw` for non-English speakers, and `handled by` provides a simpler alternative to `recover as` when the error value is not needed.
|
|
530
|
-
|
|
531
|
-
5. **Function call clarity** — The `together` keyword makes function calls explicit in prose code, and `fill ... with` provides a readable assignment form.
|
|
532
|
-
|
|
533
|
-
6. **Object/array access** — `at position N` and `has field` make indexing and property checks read like English sentences.
|
|
534
|
-
|
|
535
|
-
### Testing Notes
|
|
100
|
+
## Version Info
|
|
536
101
|
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
- **Backward-compatible** — existing PlainScript code continues to work unchanged
|
|
102
|
+
The release label for this repo is `1.0.3`. It covers the compiler,
|
|
103
|
+
package metadata, website, and editor tooling. Third-party dependency
|
|
104
|
+
versions are not tied to this label.
|