plainscript-lang 1.0.2-rfc → 1.0.3-beta

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.
Files changed (67) hide show
  1. package/README.md +194 -736
  2. package/compiler/cli.js +13 -17
  3. package/compiler/generator.js +93 -21
  4. package/compiler/version.js +1 -1
  5. package/docs/CAPABILITY_GAP_AUDIT.md +98 -536
  6. package/docs/PLAINSCRIPT-SPEC.md +308 -557
  7. package/docs/index.html +101 -599
  8. package/docs/website/script.js +59 -1029
  9. package/docs/website/style.css +74 -656
  10. package/examples/ai-providers.pln +7 -0
  11. package/examples/arrays.pln +4 -12
  12. package/examples/async-errors.pln +18 -0
  13. package/examples/auth-api.pln +3 -50
  14. package/examples/auth-sessions.pln +32 -0
  15. package/examples/basics.pln +14 -0
  16. package/examples/bots.pln +13 -0
  17. package/examples/cache-and-jobs.pln +6 -28
  18. package/examples/cache-schedule.pln +22 -0
  19. package/examples/collections.pln +15 -0
  20. package/examples/concurrency.pln +12 -43
  21. package/examples/conditions.pln +22 -0
  22. package/examples/database.pln +6 -39
  23. package/examples/day2.pln +6 -6
  24. package/examples/day3.pln +4 -10
  25. package/examples/deployment.pln +3 -9
  26. package/examples/email-send.pln +3 -22
  27. package/examples/error-handling.pln +6 -54
  28. package/examples/expressions.pln +7 -40
  29. package/examples/file-uploads.pln +5 -34
  30. package/examples/files-and-config.pln +5 -46
  31. package/examples/files.pln +12 -0
  32. package/examples/football-backend/app.pln +21 -20
  33. package/examples/functions.pln +17 -0
  34. package/examples/hello.pln +2 -3
  35. package/examples/http-client.pln +3 -44
  36. package/examples/http.pln +11 -0
  37. package/examples/id-verification/app.pln +4 -3
  38. package/examples/id-verification/make-sample-id.js +29 -42
  39. package/examples/json.pln +11 -0
  40. package/examples/loops.pln +13 -11
  41. package/examples/modules/app.pln +3 -16
  42. package/examples/modules/main.pln +4 -0
  43. package/examples/modules/math.pln +5 -16
  44. package/examples/objects.pln +3 -11
  45. package/examples/ocr.pln +22 -0
  46. package/examples/packages.pln +6 -0
  47. package/examples/record-kinds.pln +6 -42
  48. package/examples/records.pln +15 -0
  49. package/examples/rest-api-fetch.pln +6 -90
  50. package/examples/rest-api.pln +5 -65
  51. package/examples/scheduled-tasks.pln +4 -23
  52. package/examples/search-and-filter.pln +4 -34
  53. package/examples/server.pln +5 -24
  54. package/examples/sessions-and-cookies.pln +4 -50
  55. package/examples/sqlite.pln +23 -0
  56. package/examples/start.pln +2 -2
  57. package/examples/stdlib.pln +4 -41
  58. package/examples/telegram-ai-bot.pln +19 -0
  59. package/examples/telegram-bot.pln +4 -40
  60. package/examples/testing.pln +13 -0
  61. package/examples/web-api.pln +27 -0
  62. package/examples/web-app.pln +4 -16
  63. package/examples/websocket-server.pln +5 -26
  64. package/examples/websocket.pln +13 -0
  65. package/examples/whatsapp-bot/pairing.pln +4 -5
  66. package/examples/whatsapp-bot/qr.pln +7 -3
  67. package/package.json +2 -2
@@ -1,540 +1,102 @@
1
- # PlainScript 2.4 — Capability-Gap Audit vs. TypeScript / Node.js
2
-
3
- > **Purpose.** PlainScript's goal is **capability parity**, not syntax parity, with
4
- > modern TypeScript + Node.js. We do not clone TypeScript's syntax or its static
5
- > type system; we keep PlainScript an **Intent-Oriented Programming Language**
6
- > (IOPL) — you describe *what* you want, and the deterministic compiler decides
7
- > *how* to implement it in JavaScript.
8
- >
9
- > This document is the complete working audit through v2.4. For every
10
- > major TypeScript/Node.js capability area, it records:
11
- >
12
- > - **Status** — what PlainScript 1.0.2 already does,
13
- > - **Gap** — what is missing for real-world capability parity,
14
- > - **Resolution** — either an *IOPL-native implementation* (shipped in this
15
- > release and covered by tests) or an explicit *rationale* for why the
16
- > capability is unnecessary / already supplied by the host runtime.
17
- >
18
- > **Gate:** PlainScript must NOT be declared 1.0.2 "ready" until this audit is
19
- > complete and its shipped resolutions are exercised by the test suite.
20
- >
21
- > ---
22
-
23
- ## 0. The design contract (why IOPL ≠ TypeScript)
24
-
25
- Two deliberate departures make PlainScript *better suited* to its job rather
26
- than weaker:
27
-
28
- 1. **No static type system is needed for the 80% target.** TypeScript's type
29
- annotations exist to give an editor/compiler enough information to *predict*
30
- program behaviour. In PlainScript the value graph is constructed by the
31
- compiler itself (deterministic, whole-module bundling), and runtime behaviour
32
- is JavaScript. Structural, runtime-checked *record kinds* (see §8) give the
33
- same safety at the boundaries that "shape" typing would, without a type
34
- grammar the programmer must learn. **Resolution: unnecessary as a syntax;
35
- provided as runtime record kinds.**
36
- 2. **`any`-style type erasure is the norm.** Because we compile to JavaScript,
37
- every TypeScript capability that is *implementable in JS* is automatically
38
- available to PlainScript programmers through the JavaScript Gateway (§18) and
39
- the runtime stdlib. The compiler exposes the *meaningful* subset as first-class
40
- IOPL so the common 80% reads like prose.
41
-
42
- Everything below is measured against "can a PlainScript program, shipped as
43
- normal Node `dist/`, do what the TypeScript program can?"
44
-
45
- ---
46
-
47
- ## 1. Advanced typing & generics
48
-
49
- | TypeScript | PlainScript resolution |
50
- |------------------------------------|------------------------|
51
- | Interfaces / type aliases | **IOPL-native `kind` record schema** (§8). Declares fields + defaults; compile-checked constructors. |
52
- | Generics `<T>` | **Rationale: unnecessary.** PlainScript functions are untyped by design; JavaScript enforces runtime shapes. For generic *containers* (Map, Set, Promise<T>), use the JS Gateway or runtime stdlib, which are naturally generic. Provide `isArray`, `isText`, `isNumber` runtime predicates instead. |
53
- | Unions / literals | **Rationale: unnecessary.** `match <expr> against ... end` (existing) exhaustively branches on runtime values. |
54
- | Optional / default params | **IOPL-native** — `define f(x, y as 0)` (existing, RFC-0011). |
55
- | Rest params / spread | **IOPL-native `spread of`** — see §6 collections. |
56
- | Non-null / optional chaining | **Runtime null-safety stdlib** — `valueOf(key, fallback)`, `hasField(rec, key)` (§13). Avoids `?.` syntax. |
57
- | `typeof`/`keyof` type queries | **Runtime reflection stdlib** — `typeOf(x)`, `fieldsOf(x)` (§13). |
58
- | Mapped / conditional types | **Rationale: unnecessary** (type-level metaprogramming; no runtime value). |
59
- | Tuples / fixed-size arrays | **`tuple` record kind** — construct via `kind` with `fields`; runtime validated. |
60
- | Readonly / const assertions | **Rationale: unnecessary** (const-like behaviour via JS `const` output; compiler already emits `let`/`const` as needed). |
61
-
62
- **Audit status:** Runtime reflection + record kinds ship; type grammar deliberately
63
- omitted (rationale above). **Gap closed for 80% target.**
64
-
65
- ---
66
-
67
- ## 2. Modules / imports / exports
68
-
69
- | TypeScript | PlainScript resolution |
70
- |------------------------|------------------------|
71
- | ES `import`/`export` | **Exists**: `import "./file.pln"` (§ bundler), top-level `define` auto-exported to `module.exports`. |
72
- | Named imports | **IOPL-native `import ... from`** — `import { name } from "./util.pln"` binds only named symbols (this release). |
73
- | Dynamic `import()` | **Runtime stdlib `loadModule(path)`** returning the required module (this release). |
74
- | Circular imports | **Compile-time error** with a friendly cycle report (existing) — safer than TS's hoisted partials. |
75
- | Barrel files | **Works** — `import "./index.pln"` where index imports the rest (existing bundler de-dups). |
76
- | `import type` | **Rationale: unnecessary** — searchable types). |
77
- | Node built-ins | **Runtime stdlib** `use fs`, `use path`, and IOPL `read/write/...` (existing). |
78
-
79
- **Audit status:** Named imports + dynamic `loadModule` ship; barrel/cycle behaviour
80
- already present. **Gap closed.**
81
-
82
- ---
83
-
84
- ## 3. Async / await & concurrency
85
-
86
- | TypeScript | PlainScript resolution |
87
- |-------------------------|------------------------|
88
- | `async`/`await` | **IOPL `wait for <expr>`** (existing, RFC-0011 §10); `run`/`ask`/queries auto-await. |
89
- | `Promise.all` | **IOPL-native `all of [e1, e2, ...]`** (this release). |
90
- | `Promise.race` | **IOPL-native `any of [e1, e2, ...]`** (this release). |
91
- | `Promise.allSettled` | **IOPL-native `settled of [e1, e2, ...]`** returning `{ status, value/error }` records (this release). |
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
-
1
+ # PlainScript 1.0.3-beta capability audit
2
+
3
+ This audit is intentionally grounded in the implementation, not in old
4
+ examples. The parser and generator are the authority. A capability is listed
5
+ here only when a source program can be validated by `plainscript check`.
6
+
7
+ ## Core language
8
+
9
+ | Capability | Status | Current source form |
10
+ | --- | --- | --- |
11
+ | Variables and assignment | Implemented | `remember x as 1`, `x becomes 2` |
12
+ | Strings and templates | Implemented | `"text"`, `` `Hello ${name}` `` |
13
+ | Numbers and BigInt | Implemented | `3.14`, `42n` |
14
+ | Arrays and objects | Implemented | `[1, 2]`, `{name: "Ada"}` |
15
+ | Records and record kinds | Implemented | `define a kind called "User" with ... done` |
16
+ | Conditions | Implemented | `if ... otherwise ... done` |
17
+ | Functions | Implemented | `make add(a, b) ... done` |
18
+ | Generators | Implemented | `yield value` |
19
+ | For and while loops | Implemented | `for each ... done`, `while ... done` |
20
+ | Match and switch | Implemented | `match value against ... done` |
21
+ | Loop control | Implemented | `break`, `continue` |
22
+ | Classes and `new` | Implemented | JavaScript-compatible class forms |
23
+
24
+ ## Modules and runtime
25
+
26
+ | Capability | Status | Notes |
27
+ | --- | --- | --- |
28
+ | Relative PlainScript imports | Implemented | Imported files are bundled |
29
+ | Named imports and exports | Implemented | `import { name } from "./file.pln"` |
30
+ | npm packages | Implemented | `use package-name` and CLI dependency detection |
31
+ | JSON | Implemented | `jsonEncode`, `jsonDecode`, JSON response blocks |
32
+ | Files and paths | Implemented | Read/write, bytes, folders, path helpers |
33
+ | Crypto and auth helpers | Implemented | Hashes, passwords, tokens |
34
+ | Async/await | Implemented | `wait for`, `await`, async propagation |
35
+ | Concurrency | Implemented | `allOf`, `anyOf`, `settledOf`, `withTimeout` |
36
+ | Errors and retries | Implemented | `try`, `recover`, `finally`, `retry` |
37
+ | Native tests | Implemented | `test` and `check` assertions |
38
+
39
+ ## Web and services
40
+
41
+ | Capability | Status | Current source form |
42
+ | --- | --- | --- |
43
+ | Express web app | Implemented | `web app` |
44
+ | HTTP routes | Implemented | `route get "/path" ... done` |
45
+ | JSON responses | Implemented | `reply json ... done` |
46
+ | CORS and fallback | Implemented | `allow cors`, `when nothing matches` |
47
+ | Request accessors | Implemented | `body`, `param`, `query`, `header`, uploads |
48
+ | Cookies and sessions | Implemented | `set cookie`, `enable sessions` |
49
+ | API keys and rate limits | Implemented | `require api key`, `limit requests` |
50
+ | File uploads | Implemented | `accept uploads` |
51
+ | HTTP client | Implemented | `get`, `post`, `put`, `patch`, `delete` |
52
+ | SQLite | Implemented | native and WebAssembly drivers |
53
+ | PostgreSQL generation | Implemented | `postgres connection` |
54
+ | SQL parameter binding | Implemented | `{variable}` placeholders |
55
+ | Email | Implemented | `mail transport`, `send mail` |
56
+ | Schedules and jobs | Implemented | `every`, `schedule`, `run background` |
57
+ | WebSockets | Implemented | `websocket server` |
58
+ | Redis/in-memory cache | Implemented | `cache`, `cacheGet`, `cacheSet` |
59
+ | Telegram bots | Implemented | `bot`, message/callback handlers |
60
+ | AI providers | Implemented | `chat`, `chatWith`, `embedText`, provider presets |
61
+ | WhatsApp bots | Implemented | `whatsapp bot` |
62
+ | OCR | Implemented | `ocr path of file as text` |
63
+
64
+ ## Canonical examples
65
+
66
+ The maintained examples are the executable capability matrix:
67
+
68
+ ```text
69
+ examples/basics.pln
70
+ examples/conditions.pln
71
+ examples/loops.pln
72
+ examples/functions.pln
73
+ examples/records.pln
74
+ examples/collections.pln
75
+ examples/json.pln
76
+ examples/files.pln
77
+ examples/packages.pln
78
+ examples/http.pln
79
+ examples/sqlite.pln
80
+ examples/web-api.pln
81
+ examples/auth-sessions.pln
82
+ examples/async-errors.pln
83
+ examples/concurrency.pln
84
+ examples/websocket.pln
85
+ examples/cache-schedule.pln
86
+ examples/bots.pln
87
+ examples/ocr.pln
88
+ examples/testing.pln
89
+ examples/modules/
90
+ examples/football-backend/
91
+ examples/id-verification/
92
+ examples/whatsapp-bot/
107
93
  ```
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
-
174
- ```
175
- // Array indexing
176
- let first be name at position 1 in players
177
-
178
- // Property existence check
179
- when user has field "email"
180
- show "has email"
181
- done
182
-
183
- // String matching
184
- when email made of "@"
185
- show "valid email"
186
- done
187
- ```
188
-
189
- **Audit status:** Map/Set/`spread of` stdlib ship. **Gap closed.**
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
94
 
533
- 6. **Object/array access** — `at position N` and `has field` make indexing and property checks read like English sentences.
95
+ Run `find examples -name '*.pln' -exec node compiler/cli.js check {} \;`
96
+ before changing the language reference.
534
97
 
535
- ### Testing Notes
98
+ ## Version boundary
536
99
 
537
- All v2.4 near-English syntax forms are:
538
- - **Compile-verified** — the compiler accepts both old and new syntax interchangeably
539
- - **Runtime-tested** — the test suite exercises both forms for every feature
540
- - **Backward-compatible** — existing PlainScript code continues to work unchanged
100
+ The repository release label is `1.0.3-beta`. This label identifies the
101
+ compiler, package metadata, website, and editor tooling. It does not change
102
+ third-party dependency versions.