plainscript-lang 0.1.7-rc → 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 +27 -2
- package/compiler/cli.js +1 -1
- package/compiler/generator.js +623 -10
- package/compiler/lexer.js +31 -2
- package/compiler/parser.js +537 -20
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +379 -0
- package/docs/PLINJS_SPEC.md +102 -2
- package/docs/index.html +18 -6
- package/docs/website/script.js +111 -36
- package/package.json +2 -2
|
@@ -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,4 +1,4 @@
|
|
|
1
|
-
# PlainScript Language Specification (
|
|
1
|
+
# PlainScript Language Specification (v1.0.0-beta)
|
|
2
2
|
|
|
3
3
|
Version: 2.1.1
|
|
4
4
|
Status: Stable
|
|
@@ -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.
|
|
@@ -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.
|
package/docs/index.html
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
<a href="#" class="nav-logo">
|
|
36
36
|
<img src="logo.jpg" alt="PlainScript Logo">
|
|
37
37
|
<span class="logo-word">PlainScript</span>
|
|
38
|
-
<span class="logo-ver">
|
|
38
|
+
<span class="logo-ver">v1.0.0-beta</span>
|
|
39
39
|
</a>
|
|
40
40
|
<div class="nav-links">
|
|
41
41
|
<a href="#language">Language</a>
|
|
@@ -85,7 +85,7 @@
|
|
|
85
85
|
<!-- Hero Section -->
|
|
86
86
|
<section class="hero">
|
|
87
87
|
<div class="hero-content">
|
|
88
|
-
<div class="hero-badge">
|
|
88
|
+
<div class="hero-badge">v1.0.0-beta — intent-oriented, TypeScript-capable</div>
|
|
89
89
|
<h1 class="hero-title">
|
|
90
90
|
Write code that<br>
|
|
91
91
|
reads like <span class="green">Plain English</span>
|
|
@@ -110,7 +110,7 @@
|
|
|
110
110
|
</div>
|
|
111
111
|
<div class="code-window-body">
|
|
112
112
|
<pre><code>server on port 3000
|
|
113
|
-
when someone
|
|
113
|
+
when someone visits "/"
|
|
114
114
|
send "Hello, World!"
|
|
115
115
|
|
|
116
116
|
log "Server is running"</code></pre>
|
|
@@ -238,10 +238,10 @@ console.log("Server is running");</code></pre>
|
|
|
238
238
|
<pre><code>use express
|
|
239
239
|
|
|
240
240
|
server on port 3000
|
|
241
|
-
when someone
|
|
241
|
+
when someone visits "/"
|
|
242
242
|
send "Hello, World!"
|
|
243
243
|
|
|
244
|
-
when someone
|
|
244
|
+
when someone visits "/users"
|
|
245
245
|
send json of users
|
|
246
246
|
|
|
247
247
|
log "Server running on port 3000"</code></pre>
|
|
@@ -493,6 +493,18 @@ use dotenv</code></pre>
|
|
|
493
493
|
<button class="lib-filter" data-cat="email">Email</button>
|
|
494
494
|
<button class="lib-filter" data-cat="upload">Uploads</button>
|
|
495
495
|
<button class="lib-filter" data-cat="cli">CLI</button>
|
|
496
|
+
<button class="lib-filter" data-cat="data">Data</button>
|
|
497
|
+
<button class="lib-filter" data-cat="ai">AI</button>
|
|
498
|
+
<button class="lib-filter" data-cat="reflection">Reflection</button>
|
|
499
|
+
<button class="lib-filter" data-cat="binary">Binary & Crypto</button>
|
|
500
|
+
<button class="lib-filter" data-cat="concurrency">Concurrency</button>
|
|
501
|
+
<button class="lib-filter" data-cat="generators">Generators</button>
|
|
502
|
+
<button class="lib-filter" data-cat="testing">Testing</button>
|
|
503
|
+
<button class="lib-filter" data-cat="pattern">Pattern Match</button>
|
|
504
|
+
<button class="lib-filter" data-cat="config">Config & Env</button>
|
|
505
|
+
<button class="lib-filter" data-cat="process">Process & CLI</button>
|
|
506
|
+
<button class="lib-filter" data-cat="paths">Paths</button>
|
|
507
|
+
<button class="lib-filter" data-cat="regex">Regex</button>
|
|
496
508
|
</div>
|
|
497
509
|
</div>
|
|
498
510
|
|
|
@@ -590,7 +602,7 @@ use dotenv</code></pre>
|
|
|
590
602
|
</div>
|
|
591
603
|
<div class="footer-bottom">
|
|
592
604
|
<p>© 2026 PlainScript. Built by Ayokunle.</p>
|
|
593
|
-
<span class="footer-badge">
|
|
605
|
+
<span class="footer-badge">v1.0.0-beta</span>
|
|
594
606
|
</div>
|
|
595
607
|
</div>
|
|
596
608
|
</footer>
|