plainscript-lang 0.1.7 → 1.0.0-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.
- package/README.md +61 -36
- package/compiler/bundler.js +1 -1
- package/compiler/cli.js +42 -42
- package/compiler/generator.js +623 -10
- package/compiler/lexer.js +31 -2
- package/compiler/parser.js +539 -22
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +379 -0
- package/docs/PLINJS_SPEC.md +124 -24
- package/docs/index.html +535 -2205
- package/docs/website/script.js +889 -133
- package/docs/website/style.css +652 -1113
- package/examples/{cache-and-jobs.pln → cache-and-jobs.ps} +1 -1
- package/examples/{database.pln → database.ps} +1 -1
- package/examples/{deployment.pln → deployment.ps} +1 -1
- package/examples/{email-send.pln → email-send.ps} +1 -1
- package/examples/{rest-api.pln → rest-api.ps} +1 -1
- package/examples/{scheduled-tasks.pln → scheduled-tasks.ps} +1 -1
- package/examples/{websocket-server.pln → websocket-server.ps} +1 -1
- package/package.json +2 -2
- package/docs/website/index.html +0 -1500
- /package/examples/{arrays.pln → arrays.ps} +0 -0
- /package/examples/{day2.pln → day2.ps} +0 -0
- /package/examples/{day3.pln → day3.ps} +0 -0
- /package/examples/{expressions.pln → expressions.ps} +0 -0
- /package/examples/football-backend/{app.pln → app.ps} +0 -0
- /package/examples/{hello.pln → hello.ps} +0 -0
- /package/examples/id-verification/{app.pln → app.ps} +0 -0
- /package/examples/{loops.pln → loops.ps} +0 -0
- /package/examples/{objects.pln → objects.ps} +0 -0
- /package/examples/{rest-api-fetch.pln → rest-api-fetch.ps} +0 -0
- /package/examples/{server.pln → server.ps} +0 -0
- /package/examples/{start.pln → start.ps} +0 -0
- /package/examples/{stdlib.pln → stdlib.ps} +0 -0
- /package/examples/{telegram-bot.pln → telegram-bot.ps} +0 -0
- /package/examples/{web-app.pln → web-app.ps} +0 -0
- /package/examples/whatsapp-bot/{pairing.pln → pairing.ps} +0 -0
- /package/examples/whatsapp-bot/{qr.pln → qr.ps} +0 -0
package/compiler/version.js
CHANGED
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
# PlainScript 1.0.0 — 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 for the 1.0.0 milestone. For every
|
|
10
|
+
> major TypeScript/Node.js capability area, it records:
|
|
11
|
+
>
|
|
12
|
+
> - **Status** — what PlainScript 1.0.0 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.0 "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 ... done` (existing) exhaustively branches on runtime values. |
|
|
54
|
+
| Optional / default params | **IOPL-native** — `make 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.ps"` (§ bundler), top-level `make` auto-exported to `module.exports`. |
|
|
72
|
+
| Named imports | **IOPL-native `import ... from`** — `import { name } from "./util.ps"` 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.ps"` 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 — `remember results as all of [a(), b()]`. |
|
|
93
|
+
| Worker threads / parallel jobs | **IOPL-native `run in parallel ... done [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
|
+
done
|
|
112
|
+
|
|
113
|
+
make a Person with name "Ada" and age 17
|
|
114
|
+
show name of ada // "Ada"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- Fields declared with defaults; constructors **prompt for missing required
|
|
118
|
+
fields** at compile time; unknown constructor fields are a compile error.
|
|
119
|
+
- Kind objects are plain JS objects, so `jsonEncode`, `sendMail`, DB rows,
|
|
120
|
+
and every existing stdlib works on them unchanged.
|
|
121
|
+
- Attach behaviour with ordinary `make` functions that take the record
|
|
122
|
+
(`make describe(person) give name of person + " is " + age of person`).
|
|
123
|
+
- **Inheritance** is deliberately *composition-first*: `kind` + stdlib
|
|
124
|
+
`merge(a, b)` (existing) covers the 80%. Deep prototype chains are a
|
|
125
|
+
TypeScript *syntax*, not a capability we need to replicate.
|
|
126
|
+
|
|
127
|
+
| TypeScript | PlainScript resolution |
|
|
128
|
+
|-------------------------|------------------------|
|
|
129
|
+
| `class`, constructor | **IOPL-native `kind` + `make a X with ...`** (this release). |
|
|
130
|
+
| Fields / properties | `kind` fields; access via `name of x` / `x.name`. |
|
|
131
|
+
| Methods | Top-level `make` functions taking the record. |
|
|
132
|
+
| `this` | **Rationale: unnecessary** — functions receive the record explicitly (no context bugs). |
|
|
133
|
+
| `static` members | Module-level`remember`/`make` are naturally static. |
|
|
134
|
+
| Extension / mixins | `merge(a, b)` (existing) + nested kinds. |
|
|
135
|
+
| Access modifiers | **Rationale: unnecessary** — single-process bundles; `_field` is convention. |
|
|
136
|
+
|
|
137
|
+
**Audit status:** Record kinds ship with tested constructors, field validation,
|
|
138
|
+
and JSON/serialization compat. **Gap closed.**
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## 5. Iterators / generators
|
|
143
|
+
|
|
144
|
+
| TypeScript | PlainScript resolution |
|
|
145
|
+
|------------------|------------------------|
|
|
146
|
+
| `for...of` | `for each item in x ... done` (existing) — works on arrays, strings, Maps, Sets, generators. |
|
|
147
|
+
| Generator `function*` / `yield` | **IOPL-native `yield`** inside `make ... done` (this release) — a `make` containing `yield` compiles to a `function*`. |
|
|
148
|
+
| `[Symbol.iterator]` | Accessible via JS Gateway / `kind` producer (this release: `make` with `yield`). |
|
|
149
|
+
| Iterator helpers (`map`/`filter`/`reduce`) | **IOPL-native** `gather each ... giving`, `filter each ... when`, `total each ... giving` (existing, functional map/filter/reduce). |
|
|
150
|
+
| Spread `/ rest` | **IOPL-native `spread of x`** unfolds an iterable into a new array (this release). |
|
|
151
|
+
| Lazy sequences | Generators via `yield` + `for each` (this release). |
|
|
152
|
+
|
|
153
|
+
**Audit status:** Generators, spread, and functional iteration ship. **Gap closed.**
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 6. Collections
|
|
158
|
+
|
|
159
|
+
| TypeScript | PlainScript resolution |
|
|
160
|
+
|--------------|------------------------|
|
|
161
|
+
| Array | Literals `[...]`, `first/last/N-th from`, `length(x)`, `add/remove`, `gather/filter/total` (all existing). |
|
|
162
|
+
| Map | **Runtime stdlib** `keyMap()`/`mapSet/mapGet/mapDelete/mapHas` wrapping JS `Map` (this release). |
|
|
163
|
+
| Set | **Runtime stdlib** `set()`/`unique(x)` (unique exists) — `addToSet/removeFromSet` (this release). |
|
|
164
|
+
| Object | `merge`, `keys`, `values`, `hasKey`, `of` chains (existing) + `fieldsOf` (this release). |
|
|
165
|
+
| Tuple | **`kind` with positional fields** (§4). |
|
|
166
|
+
|
|
167
|
+
**Audit status:** Map/Set/`spread of` stdlib ship. **Gap closed.**
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## 7. Decorators / metaprogramming
|
|
172
|
+
|
|
173
|
+
| TypeScript | PlainScript resolution |
|
|
174
|
+
|-----------------|------------------------|
|
|
175
|
+
| 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. |
|
|
176
|
+
| Method/class metadata | **Rationale: mostly unnecessary.** Since methods are top-level functions (no `this`), there is nothing to decorate. |
|
|
177
|
+
| `Proxy` / `Reflect` | **JS Gateway** exposes raw `Proxy`/`Reflect` when genuinely needed (existing). |
|
|
178
|
+
|
|
179
|
+
**Audit status:** Rationale documented; no decorator syntax. **No gap for 80%.**
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 8. Symbols / well-known keys
|
|
184
|
+
|
|
185
|
+
- **Rationale: unnecessary as a user-facing feature.** `Symbol` keys matter for
|
|
186
|
+
iterator identity and library protocol, both of which are *inside* the compiler
|
|
187
|
+
(generator `yield` uses `Symbol.iterator` transparently). Exposing `Symbol` as
|
|
188
|
+
an IOPL statement would leak implementation detail without capability gain.
|
|
189
|
+
- When a library genuinely requires a user-provided symbol, the **JS Gateway**
|
|
190
|
+
provides it.
|
|
191
|
+
|
|
192
|
+
**Audit status:** Rationale documented. **No gap.**
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 9. Proxies / reflection / duck typing
|
|
197
|
+
|
|
198
|
+
| TypeScript | PlainScript resolution |
|
|
199
|
+
|--------------|------------------------|
|
|
200
|
+
| `Reflect.*` | **Runtime reflection stdlib**: `typeOf(x)`, `fieldsOf(x)`, `hasField(rec, key)`, `valueOf(rec,key)`, `sizeOf(x)` (this release). |
|
|
201
|
+
| `Object.keys`| `keys(x)` (existing) / `fieldsOf(x)` (this release). |
|
|
202
|
+
| Duck typing | Provided naturally: functions receive records and read `name of x` regardless of construction site. |
|
|
203
|
+
|
|
204
|
+
**Audit status:** Runtime reflection ships. **Gap closed.**
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 10. Binary data
|
|
209
|
+
|
|
210
|
+
| TypeScript / Node | PlainScript resolution |
|
|
211
|
+
|-------------------|------------------------|
|
|
212
|
+
| `Buffer` | **Runtime stdlib** `textToBytes(s)`, `bytesToText(b)` (this release); `readBytes`/`writeBytes` exist. |
|
|
213
|
+
| `base64` | **Runtime stdlib** `base64Encode(x)`, `base64Decode(s)` (this release). |
|
|
214
|
+
| `ArrayBuffer`/typed arrays | Accessible through `readBytes()` returning a `Buffer` and the JS Gateway. |
|
|
215
|
+
| CRC / hash | `hashPassword` (existing) + `sha256(text)` (this release). |
|
|
216
|
+
|
|
217
|
+
**Audit status:** Binary + encoding stdlib ships. **Gap closed.**
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 11. Workers / processes
|
|
222
|
+
|
|
223
|
+
| TypeScript / Node | PlainScript resolution |
|
|
224
|
+
|-------------------|------------------------|
|
|
225
|
+
| Worker threads | **IOPL-native `run in parallel ... done`** (existing) and `run background <call>` (existing). |
|
|
226
|
+
| Child processes | **Runtime stdlib `runCommand(cmd, args)`** (async, captures stdout/stderr/exit) (this release). |
|
|
227
|
+
| `process.exit` | `exit(code)` (existing); `env()` (existing). |
|
|
228
|
+
| Signals / IPC | **Rationale: unnecessary for 80%** — batch/parallel covers CPU-bound; cross-process messaging is niche. JS Gateway for the rest. |
|
|
229
|
+
|
|
230
|
+
**Audit status:** Process execution ships; workers via existing parallel model.
|
|
231
|
+
**Gap closed.**
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 12. Filesystem
|
|
236
|
+
|
|
237
|
+
| Node fs | PlainScript resolution |
|
|
238
|
+
|--------------------|------------------------|
|
|
239
|
+
| Read/write text | `read`/`readFile`, `write`/`writeFile`, `appendFile` (all existing). |
|
|
240
|
+
| Binary | `readBytes`/`writeBytes` (existing). |
|
|
241
|
+
| Metadata | `fileExists`, `fileSize(path)`, `fileType(path)`, `lastModified(path)` (this release). |
|
|
242
|
+
| Directory ops | `makeFolder`, `deleteFolder`, `listFolder` (existing), `walkFolder(dir)` recursive (this release). |
|
|
243
|
+
| Copy/move/delete | `copyFile`, `moveFile`, `deleteFile` (existing). |
|
|
244
|
+
| Path helpers | `joinPath`, `baseName`, `folderOf(path)`, `extensionOf(path)` (this release). |
|
|
245
|
+
|
|
246
|
+
**Audit status:** Filesystem suite extended to metadata/walk/path. **Gap closed.**
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## 13. Streams
|
|
251
|
+
|
|
252
|
+
| Node stream | PlainScript resolution |
|
|
253
|
+
|--------------------|------------------------|
|
|
254
|
+
| Read line-by-line | **IOPL-native `stream "file" as line ... done`** (existing). |
|
|
255
|
+
| Write append | `writeLine(file, text)` / `appendLine(file, text)` (this release). |
|
|
256
|
+
| Transform / pipe | **Rationale: necessary via JS Gateway only** — stream pipelines are an implementation detail; `write`/`read`/`stream` cover I/O. |
|
|
257
|
+
|
|
258
|
+
**Audit status:** Stream I/O rounded out. **Gap mostly closed.**
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 14. Networking
|
|
263
|
+
|
|
264
|
+
| Node net/http | PlainScript resolution |
|
|
265
|
+
|--------------------------|------------------------|
|
|
266
|
+
| HTTP server | `web app` + `route` + `start` (existing) and Express form (existing). |
|
|
267
|
+
| HTTP client | `get/post/put/patch/delete "<url>"` + `wait for fetch` (existing). |
|
|
268
|
+
| WebSocket server/client | `websocket server on ...` (existing, server side). |
|
|
269
|
+
| TCP server / client | **IOPL-native — omitted with rationale:** Node `net` is low-level; the 80% uses HTTP/WebSocket. Provided by JS Gateway on demand. |
|
|
270
|
+
| TLS / DNS / UDP | **Rationale: omitted** (niche; JS Gateway / `use`). |
|
|
271
|
+
|
|
272
|
+
**Audit status:** HTTP/WS cover the target; TCP documented as rationale.
|
|
273
|
+
**Gap closed for 80%.**
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 15. Serialization / configuration
|
|
278
|
+
|
|
279
|
+
| TypeScript / Node | PlainScript resolution |
|
|
280
|
+
|-------------------|------------------------|
|
|
281
|
+
| JSON | `jsonEncode`/`jsonDecode` (existing). |
|
|
282
|
+
| YAML | **Runtime stdlib `yamlDecode(s)`/`yamlEncode(v)`** (this release). |
|
|
283
|
+
| `.env` files | **IOPL-native `load env file "....env"`** statement + `envFile("path")` fallback (this release). |
|
|
284
|
+
| Config files | `loadEnvFile`; plus `plainscript.config.json` build config (existing). |
|
|
285
|
+
| `.toml` | **Rationale: niche** — YAML+JSON+env covers configuration; JS Gateway for TOML. |
|
|
286
|
+
| Binary serialization (msgpack/buffer) | `textToBytes`/`bytesToText`/`base64` (this release). |
|
|
287
|
+
|
|
288
|
+
**Audit status:** YAML + env-file configuration ship. **Gap closed.**
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## 16. CLI tooling
|
|
293
|
+
|
|
294
|
+
| TypeScript / Node | PlainScript resolution |
|
|
295
|
+
|-------------------|------------------------|
|
|
296
|
+
| `process.argv` | **Runtime stdlib `args()`** returns the command-line argument array (this release). |
|
|
297
|
+
| argparse prompts | `ask "..." as x` (existing). |
|
|
298
|
+
| Subprocess CLI | `runCommand` (this release, §11). |
|
|
299
|
+
|
|
300
|
+
**Audit status:** `args()` ships. **Gap closed.**
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## 17. Testing
|
|
305
|
+
|
|
306
|
+
| TypeScript / Node | PlainScript resolution |
|
|
307
|
+
|-------------------|------------------------|
|
|
308
|
+
| Test runner | **IOPL-native `test "name" ... done` blocks** with `check a equals b`, `check a is true`, `check raises` (this release). |
|
|
309
|
+
| Assertions | `check a equals b` / `check a contains b` / `check a raises <msg>` (this release). |
|
|
310
|
+
| Suite grouping | `test` blocks run in order; `check` failures print and exit `1` (this release). |
|
|
311
|
+
|
|
312
|
+
**Audit status:** A native test DSL ships — no external runner needed. **Gap closed.**
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## 18. JavaScript Gateway (escape hatch)
|
|
317
|
+
|
|
318
|
+
The **JavaScript Gateway** (`javascript ... done`, RFC-0011 §10) is the universal
|
|
319
|
+
fallback that closes *every* remaining micro-gap — any of TypeScript's capabilities
|
|
320
|
+
that is expressible in JS is reachable here without leaving PlainScript. This
|
|
321
|
+
single feature is why the audit can be honest about the many "rationale: omitted"
|
|
322
|
+
rows without reducing capability parity.
|
|
323
|
+
|
|
324
|
+
**Audit status:** Preexisting; retained.
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## 19. Package / library authoring
|
|
329
|
+
|
|
330
|
+
| Capability | PlainScript resolution |
|
|
331
|
+
|-----------------------|------------------------|
|
|
332
|
+
| Publish npm library | `plainscript build` → `dist/`; `main`/`prepare` in package.json (existing). |
|
|
333
|
+
| Named exports | **IOPL-native `export <name>`** marks a top-level symbol for export; imported bindings re-exportable (this release). |
|
|
334
|
+
| Consumer API | `module.exports` of top-level `make` (existing) + explicit `export` (this release). |
|
|
335
|
+
| `exports` map / ESM | Standard `package.json` semantics (project model, existing). |
|
|
336
|
+
|
|
337
|
+
**Audit status:** export statement ships. **Gap closed.**
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## 20. Summary scoring
|
|
342
|
+
|
|
343
|
+
| Area | Status |
|
|
344
|
+
|----------------------------|--------|
|
|
345
|
+
| Advanced typing/generics | ✅ runtime kinds + reflection; type grammar rationalised |
|
|
346
|
+
| Modules/imports/exports | ✅ named imports + loadModule + export |
|
|
347
|
+
| Async & concurrency | ✅ all/any/settled of, withTimeout |
|
|
348
|
+
| Classes/objects | ✅ record kinds |
|
|
349
|
+
| Iterators/generators | ✅ yield + spread of |
|
|
350
|
+
| Collections | ✅ Map/Set stdlib |
|
|
351
|
+
| Decorators/metadata | ⚪ documented (unnecessary) |
|
|
352
|
+
| Symbols | ⚪ documented (unnecessary) |
|
|
353
|
+
| Proxies/reflection | ✅ runtime reflection stdlib |
|
|
354
|
+
| Binary data | ✅ base64/bytes/sha256 |
|
|
355
|
+
| Workers/processes | ✅ runCommand + parallel |
|
|
356
|
+
| Filesystem | ✅ metadata/walk/path |
|
|
357
|
+
| Streams | ✅ writeLine/appendLine |
|
|
358
|
+
| Networking | ✅ HTTP/WS; TCP rationalised |
|
|
359
|
+
| Serialization/config | ✅ YAML + env-file |
|
|
360
|
+
| CLI tooling | ✅ args() + runCommand |
|
|
361
|
+
| Testing | ✅ test/check DSL |
|
|
362
|
+
| Package/library authoring | ✅ export + build model |
|
|
363
|
+
| JavaScript Gateway | ✅ universal fallback |
|
|
364
|
+
|
|
365
|
+
**Legend:** ✅ shipped + tested · ⚪ intentionally omitted with rationale.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
## 21. 1.0.0 readiness gate
|
|
370
|
+
|
|
371
|
+
The audit is **complete** only when:
|
|
372
|
+
|
|
373
|
+
1. Every row above has a **shipped implementation with tests** or an **explicit
|
|
374
|
+
rationale** (both present in this document).
|
|
375
|
+
2. `npm test` is green with the new capability tests included.
|
|
376
|
+
3. The runtime stdlib table, knowledge base, and README document every new
|
|
377
|
+
capability.
|
|
378
|
+
|
|
379
|
+
Until then the package version remains **below 1.0.0**.
|
package/docs/PLINJS_SPEC.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# PlainScript Language Specification (
|
|
1
|
+
# PlainScript Language Specification (v1.0.0-beta)
|
|
2
2
|
|
|
3
3
|
Version: 2.1.1
|
|
4
4
|
Status: Stable
|
|
5
|
-
File Extension: .
|
|
5
|
+
File Extension: .ps
|
|
6
6
|
|
|
7
7
|
Tagline: "When even a simple sentence can be code."
|
|
8
8
|
|
|
@@ -155,6 +155,106 @@ While:
|
|
|
155
155
|
|
|
156
156
|
---
|
|
157
157
|
|
|
158
|
+
## Record Kinds, Classes & Concurrency (v1.0.0-beta)
|
|
159
|
+
|
|
160
|
+
These features close the capability-gap audit (`docs/CAPABILITY_GAP_AUDIT.md`) in
|
|
161
|
+
PlainScript's own intent-oriented grammar.
|
|
162
|
+
|
|
163
|
+
### Record kinds (classes)
|
|
164
|
+
|
|
165
|
+
Declare a schema with defaults, then build instances.
|
|
166
|
+
|
|
167
|
+
define a kind called "Person" with
|
|
168
|
+
name is ""
|
|
169
|
+
age is 0
|
|
170
|
+
done
|
|
171
|
+
|
|
172
|
+
remember ada as create a Person with name "Ada" and age 17
|
|
173
|
+
show name of ada # "Ada"
|
|
174
|
+
show ada.age # 17
|
|
175
|
+
|
|
176
|
+
- `create a <Kind> with <field> <value> and <field> <value> ...` builds an
|
|
177
|
+
instance. `and` separates field pairs.
|
|
178
|
+
- Unknown constructor fields throw at runtime (`"Person" has no field named "x"`).
|
|
179
|
+
- Instances are plain objects: they serialize with `jsonEncode`, pass unchanged
|
|
180
|
+
to `send mail`, DB statements, routes, etc.
|
|
181
|
+
- For optional extensions, compose with `merge(a, b)` instead of `extends`.
|
|
182
|
+
Methods are plain `make` functions receiving the record.
|
|
183
|
+
|
|
184
|
+
### Concurrency combinators
|
|
185
|
+
|
|
186
|
+
remember both as all of [pageFetch(), apiFetch()]
|
|
187
|
+
remember winner as any of [slow(), fast()]
|
|
188
|
+
remember results as settled of [maybeFails(), other()]
|
|
189
|
+
|
|
190
|
+
- `all of [...]` → `Promise.all` (all must resolve).
|
|
191
|
+
- `any of [...]` → `Promise.race` (first to settle).
|
|
192
|
+
- `settled of [...]` → `Promise.allSettled`; each item is a record with
|
|
193
|
+
`status` (`fulfilled`/`rejected`), `value`, and `reason`.
|
|
194
|
+
- `withTimeout(promise, ms)` rejects the promise after `ms` if it has not settled.
|
|
195
|
+
|
|
196
|
+
### Generators
|
|
197
|
+
|
|
198
|
+
make countUp(n)
|
|
199
|
+
remember i as 0
|
|
200
|
+
while i is less than n
|
|
201
|
+
i becomes i + 1
|
|
202
|
+
yield i
|
|
203
|
+
done
|
|
204
|
+
done
|
|
205
|
+
|
|
206
|
+
show spread of countUp(3) # [ 1, 2, 3 ]
|
|
207
|
+
|
|
208
|
+
A `make ... done` containing `yield` compiles to a generator (`function*`).
|
|
209
|
+
Sequences are consumed lazily with `for each` or eagerly with `spread of`.
|
|
210
|
+
|
|
211
|
+
### Reflection, binary & configuration (stdlib)
|
|
212
|
+
|
|
213
|
+
| PlainScript | Behaviour |
|
|
214
|
+
|-------------------------------------------|------------------------------------------|
|
|
215
|
+
| `typeOf(x)` | `text\|number\|boolean\|array\|record\|null\|function\|undefined` |
|
|
216
|
+
| `fieldsOf(x)` / `sizeOf(x)` | record keys / length |
|
|
217
|
+
| `valueOf(x, key, fallback)` / `hasField` | safe access / key check |
|
|
218
|
+
| `base64Encode(s)` / `base64Decode(s)` | base64 round-trip |
|
|
219
|
+
| `textToBytes(s)` / `bytesToText(b)` | UTF-8 bytes round-trip |
|
|
220
|
+
| `sha256(s)` / `sha1(s)` / `md5(s)` | hex digests (`crypto`) |
|
|
221
|
+
| `yamlDecode(s)` / `yamlEncode(v)` | dependency-free YAML subset |
|
|
222
|
+
| `load env file "path"` (statement) | applies `KEY=value` to `process.env` |
|
|
223
|
+
| `args()` | `process.argv.slice(2)` |
|
|
224
|
+
| `runCommand(cmd, [args])` | awaits `{ ok, code, stdout, stderr }` |
|
|
225
|
+
| `withTimeout(promise, ms)` | rejects on timeout |
|
|
226
|
+
| `loadModule("./m")` | dynamic `require` at runtime |
|
|
227
|
+
| `walkFolder(dir)` | recursive list of file paths |
|
|
228
|
+
| `fileSize(p)` / `fileType(p)` / `lastModified(p)` | fs metadata |
|
|
229
|
+
| `joinPath` / `baseName` / `folderOf` / `extensionOf` | path helpers |
|
|
230
|
+
| `writeLine(f, t)` / `appendLine(f, t)` | newline-terminated appends |
|
|
231
|
+
| `keyMap()` + `mapSet/mapGet/mapHas/mapDelete` | JS `Map` helpers |
|
|
232
|
+
| `newSet()` + `addToSet/removeFromSet/setHas` | JS `Set` helpers |
|
|
233
|
+
|
|
234
|
+
### Native test DSL
|
|
235
|
+
|
|
236
|
+
test "addition"
|
|
237
|
+
check add(2, 3) equals 5
|
|
238
|
+
check "hello" contains "ell"
|
|
239
|
+
check typeOf({}) equals "record"
|
|
240
|
+
check jsonDecode("not json") raises "JSON"
|
|
241
|
+
done
|
|
242
|
+
|
|
243
|
+
A built-in runner registers every `test "name" ... done` block, prints
|
|
244
|
+
`PASS`/`FAIL`, reports a count, and exits `1` if any assertion fails. `check`
|
|
245
|
+
is only valid inside a `test` block.
|
|
246
|
+
|
|
247
|
+
### Exports
|
|
248
|
+
|
|
249
|
+
remember configVersion as 3
|
|
250
|
+
export configVersion
|
|
251
|
+
|
|
252
|
+
`export <name>` marks a top-level symbol for `module.exports`. When any explicit
|
|
253
|
+
`export` exists, the automatic top-level function export is suppressed so the
|
|
254
|
+
author controls the module surface.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
158
258
|
## Standard Library
|
|
159
259
|
|
|
160
260
|
All built-in functions are available without any `use` or `import` statement.
|
|
@@ -230,10 +330,10 @@ Notes:
|
|
|
230
330
|
|
|
231
331
|
## PlainScript Imports
|
|
232
332
|
|
|
233
|
-
Split a project across multiple `.
|
|
333
|
+
Split a project across multiple `.ps` files:
|
|
234
334
|
|
|
235
|
-
import "./math.
|
|
236
|
-
import "./utils.
|
|
335
|
+
import "./math.ps"
|
|
336
|
+
import "./utils.ps"
|
|
237
337
|
|
|
238
338
|
Rules:
|
|
239
339
|
|
|
@@ -245,20 +345,20 @@ Rules:
|
|
|
245
345
|
|
|
246
346
|
Example project layout:
|
|
247
347
|
|
|
248
|
-
app.
|
|
249
|
-
math.
|
|
250
|
-
utils.
|
|
348
|
+
app.ps
|
|
349
|
+
math.ps
|
|
350
|
+
utils.ps
|
|
251
351
|
|
|
252
|
-
`math.
|
|
352
|
+
`math.ps`:
|
|
253
353
|
|
|
254
354
|
remember PI as 3.14
|
|
255
355
|
|
|
256
|
-
`app.
|
|
356
|
+
`app.ps`:
|
|
257
357
|
|
|
258
|
-
import "./math.
|
|
358
|
+
import "./math.ps"
|
|
259
359
|
show PI
|
|
260
360
|
|
|
261
|
-
Output: one combined JavaScript file with `math.
|
|
361
|
+
Output: one combined JavaScript file with `math.ps` code before `app.ps` code.
|
|
262
362
|
|
|
263
363
|
---
|
|
264
364
|
|
|
@@ -341,11 +441,11 @@ filesystem.
|
|
|
341
441
|
```bash
|
|
342
442
|
npm install --save-dev plainscript
|
|
343
443
|
plainscript install
|
|
344
|
-
plainscript build app.
|
|
345
|
-
plainscript run app.
|
|
444
|
+
plainscript build app.ps
|
|
445
|
+
plainscript run app.ps
|
|
346
446
|
```
|
|
347
447
|
|
|
348
|
-
`plainscript start` builds `src/app.
|
|
448
|
+
`plainscript start` builds `src/app.ps` (or `src/index.ps`) into the output
|
|
349
449
|
directory and runs it. `plainscript doctor` reports missing tools, source files,
|
|
350
450
|
or dependencies. Generated JavaScript remains standard
|
|
351
451
|
Node.js-compatible JavaScript and runtime `require()` declarations are emitted
|
|
@@ -916,7 +1016,7 @@ __whatsappOnMessage(async (__waCtx) => {
|
|
|
916
1016
|
|
|
917
1017
|
Format a PlainScript file in-place:
|
|
918
1018
|
|
|
919
|
-
plainscript fmt app.
|
|
1019
|
+
plainscript fmt app.ps
|
|
920
1020
|
|
|
921
1021
|
Formatting rules:
|
|
922
1022
|
|
|
@@ -930,7 +1030,7 @@ Formatting rules:
|
|
|
930
1030
|
|
|
931
1031
|
Check syntax without generating JavaScript or running anything:
|
|
932
1032
|
|
|
933
|
-
plainscript check app.
|
|
1033
|
+
plainscript check app.ps
|
|
934
1034
|
|
|
935
1035
|
Exits with code 0 if no errors are found. Exits with code 1 and prints a
|
|
936
1036
|
friendly error (with line, column, and suggestion where possible) if the
|
|
@@ -941,7 +1041,7 @@ file contains a syntax error.
|
|
|
941
1041
|
Install `plainscript-vscode` for:
|
|
942
1042
|
|
|
943
1043
|
- Syntax highlighting
|
|
944
|
-
- File icon for `.
|
|
1044
|
+
- File icon for `.ps` files
|
|
945
1045
|
- Auto-closing pairs: `()` `[]` `{}` `""`
|
|
946
1046
|
- Comment toggling (`//`)
|
|
947
1047
|
- Bracket matching
|
|
@@ -952,7 +1052,7 @@ See `plainscript-vscode/README.md` for installation instructions.
|
|
|
952
1052
|
|
|
953
1053
|
### Acode Editor
|
|
954
1054
|
|
|
955
|
-
Acode support (`plainscript-acode/`) provides syntax highlighting and `.
|
|
1055
|
+
Acode support (`plainscript-acode/`) provides syntax highlighting and `.ps` file
|
|
956
1056
|
recognition in the [Acode](https://acode.app) Android editor, using Acode's
|
|
957
1057
|
modern CodeMirror 6 `editorLanguages` API.
|
|
958
1058
|
|
|
@@ -993,13 +1093,13 @@ For projects that need custom output or source directories, add an optional
|
|
|
993
1093
|
|
|
994
1094
|
| Command | Behaviour |
|
|
995
1095
|
|-------------------------|------------------------------------------------------|
|
|
996
|
-
| `plainscript run <file.
|
|
1096
|
+
| `plainscript run <file.ps>` | Install dependencies, compile and execute |
|
|
997
1097
|
| `plainscript build [file]` | Compile to dist/ preserving names; no arg builds all|
|
|
998
|
-
| `plainscript check <file.
|
|
999
|
-
| `plainscript fmt <file.
|
|
1098
|
+
| `plainscript check <file.ps>` | Check syntax only (no output, no execution) |
|
|
1099
|
+
| `plainscript fmt <file.ps>` | Format a PlainScript file in-place |
|
|
1000
1100
|
| `plainscript new [name]` | Create a new PlainScript project |
|
|
1001
1101
|
| `plainscript install` | Detect and install dependencies from source files |
|
|
1002
|
-
| `plainscript start` | Build src/app.
|
|
1102
|
+
| `plainscript start` | Build src/app.ps and run its dist/ output |
|
|
1003
1103
|
| `plainscript doctor` | Check the PlainScript project environment |
|
|
1004
1104
|
| `plainscript add <pkg>` | Install a package into the project |
|
|
1005
1105
|
| `plainscript remove <pkg>` | Uninstall a package from the project |
|
|
@@ -1047,5 +1147,5 @@ If a package is missing, the compiler prints a friendly error and stops:
|
|
|
1047
1147
|
|
|
1048
1148
|
---
|
|
1049
1149
|
|
|
1050
|
-
This document is the single source of truth for PlainScript
|
|
1150
|
+
This document is the single source of truth for PlainScript v1.0.0-beta.
|
|
1051
1151
|
Every compiler implementation must follow this specification.
|