plainscript-lang 0.1.7 → 1.0.0-latest

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 (49) hide show
  1. package/README.md +98 -40
  2. package/compiler/bundler.js +1 -1
  3. package/compiler/cli.js +166 -57
  4. package/compiler/generator.js +878 -19
  5. package/compiler/lexer.js +31 -2
  6. package/compiler/parser.js +668 -24
  7. package/compiler/version.js +1 -1
  8. package/docs/CAPABILITY_GAP_AUDIT.md +439 -0
  9. package/docs/PLINJS_SPEC.md +124 -24
  10. package/docs/index.html +555 -2220
  11. package/docs/website/script.js +889 -133
  12. package/docs/website/style.css +652 -1113
  13. package/examples/auth-api.ps +56 -0
  14. package/examples/{cache-and-jobs.pln → cache-and-jobs.ps} +1 -1
  15. package/examples/concurrency.ps +49 -0
  16. package/examples/{database.pln → database.ps} +1 -1
  17. package/examples/{deployment.pln → deployment.ps} +1 -1
  18. package/examples/{email-send.pln → email-send.ps} +1 -1
  19. package/examples/error-handling.ps +54 -0
  20. package/examples/file-uploads.ps +39 -0
  21. package/examples/files-and-config.ps +47 -0
  22. package/examples/http-client.ps +44 -0
  23. package/examples/modules/app.ps +16 -0
  24. package/examples/modules/math.ps +20 -0
  25. package/examples/record-kinds.ps +43 -0
  26. package/examples/{rest-api.pln → rest-api.ps} +1 -1
  27. package/examples/{scheduled-tasks.pln → scheduled-tasks.ps} +1 -1
  28. package/examples/search-and-filter.ps +34 -0
  29. package/examples/sessions-and-cookies.ps +54 -0
  30. package/examples/{websocket-server.pln → websocket-server.ps} +1 -1
  31. package/package.json +2 -2
  32. package/docs/website/index.html +0 -1500
  33. /package/examples/{arrays.pln → arrays.ps} +0 -0
  34. /package/examples/{day2.pln → day2.ps} +0 -0
  35. /package/examples/{day3.pln → day3.ps} +0 -0
  36. /package/examples/{expressions.pln → expressions.ps} +0 -0
  37. /package/examples/football-backend/{app.pln → app.ps} +0 -0
  38. /package/examples/{hello.pln → hello.ps} +0 -0
  39. /package/examples/id-verification/{app.pln → app.ps} +0 -0
  40. /package/examples/{loops.pln → loops.ps} +0 -0
  41. /package/examples/{objects.pln → objects.ps} +0 -0
  42. /package/examples/{rest-api-fetch.pln → rest-api-fetch.ps} +0 -0
  43. /package/examples/{server.pln → server.ps} +0 -0
  44. /package/examples/{start.pln → start.ps} +0 -0
  45. /package/examples/{stdlib.pln → stdlib.ps} +0 -0
  46. /package/examples/{telegram-bot.pln → telegram-bot.ps} +0 -0
  47. /package/examples/{web-app.pln → web-app.ps} +0 -0
  48. /package/examples/whatsapp-bot/{pairing.pln → pairing.ps} +0 -0
  49. /package/examples/whatsapp-bot/{qr.pln → qr.ps} +0 -0
@@ -1,6 +1,6 @@
1
1
  // Single source of truth for the compiler version.
2
2
  // Consumed by cli.js help/version output.
3
3
 
4
- const VERSION = '0.1.7';
4
+ const VERSION = '1.0.0-latest';
5
5
 
6
6
  module.exports = { VERSION };
@@ -0,0 +1,439 @@
1
+ # PlainScript 1.0.0-latest — 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-latest milestone. For every
10
+ > major TypeScript/Node.js capability area, it records:
11
+ >
12
+ > - **Status** — what PlainScript 1.0.0-latest 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-latest "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
+ remember ada as create 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` + `create 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-latest 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-latest**.
380
+
381
+ ---
382
+
383
+ ## 22. v2.2.0 — AI/ML, data/storage & web additions
384
+
385
+ The v2.0–v2.2 releases close further gaps beyond the 1.0.0-latest audit across the
386
+ AI/ML, data/storage and web/full-stack surface. All features below are
387
+ IOPL-native (intent-oriented) rather than TypeScript-syntax clones.
388
+
389
+ ### AI / ML (module `ai`)
390
+
391
+ | Capability | IOPL stdlib |
392
+ | -------------------------------------------- | --------------------------------------------------------------------------- |
393
+ | LLM chat completion | `chat(model, messages, {options})` → text, async, OpenAI-compatible API |
394
+ | Text embeddings | `embedText(model, text, {options})` → vector, async |
395
+ | Vector similarity (cosine) | `similarity(a, b)` → -1..1 (identical → 1, orthogonal → 0, opposite → -1) |
396
+ | Auto-tagging convenience | `ai_tags(text)` → topic/category tags |
397
+ | Post / content generation | `ai_post(subject, ideas, options)` → generated prose |
398
+ | Auth | `OPENAI_API_KEY` env (override via `options.apiKey`/`options.baseURL`) |
399
+
400
+ **Audit status:** chat, embeddings, similarity ship with runtime tests; tag/post
401
+ compose the same runtime. **Gap closed.**
402
+
403
+ ### Data / storage
404
+
405
+ | Capability | IOPL stdlib |
406
+ | -------------------- | --------------------------------------------------------------------------- |
407
+ | SQLite persistence | `http`+`db` runtime, `sql` queries, `table`/`row`/`query` DSL (existing) |
408
+ | In-memory cache fallback | `cacheGet/cacheSet/cacheDelete` use a Map-based store with TTL when no Redis is configured |
409
+ | Server-managed cache | Redis-backed cache when configured (existing) |
410
+ | Redis cache | existing TTL semantics, now with graceful no-config fallback |
411
+ | Pagination | `paginate(list, page, perPage)` → `{items, count, page, pages, perPage, hasNext, hasPrev}` |
412
+
413
+ **Audit status:** paginate + in-memory cache fallback ship and are tested.
414
+ **Gap closed.**
415
+
416
+ ### Web / full-stack
417
+
418
+ | Capability | IOPL stdlib |
419
+ | ------------- | ------------------------------------------------------------------ |
420
+ | Request body | route-scoped `body(...)` accessor: `body()` → raw, `body("field")` → field |
421
+ | Redirect | `redirect to "<url>"` statement inside a route handler (`res.redirect`) |
422
+ | (existing) | routes, status, sessions, uploads, cookies, WebSocket, OAuth, email, schedules |
423
+
424
+ **Audit status:** `body` + `redirect to` ship, route-guarded with teaching
425
+ errors, compile-verified. **Gap closed.**
426
+
427
+ ### Core collections & string primitives (module `coll`)
428
+
429
+ `range`, `clamp`, `first`, `last`, `flatten`, `includes`, `pick`, `omit`,
430
+ `groupBy`, `startsWith`, `endsWith`, `truncate`, `padStart`, `padEnd` — all
431
+ runtime-tested. `contains` is a reserved lexer keyword, so the membership helper
432
+ is named `includes`.
433
+
434
+ **Audit status:** shipped + tested. **Gap closed.**
435
+
436
+ > **Note on v2.2.0 testing:** `npm test` may not fully run in constrained
437
+ > sandboxes where native deps (`express`, `sql.js`, `ws`) cannot be installed;
438
+ > web/HTTP features are therefore **compile-verified** there. Core language,
439
+ > collections, AI (with a live key), and cache fallback run with real tests.
@@ -1,8 +1,8 @@
1
- # PlainScript Language Specification (v0.1.7)
1
+ # PlainScript Language Specification (v1.0.0-latest)
2
2
 
3
3
  Version: 2.1.1
4
4
  Status: Stable
5
- File Extension: .pln
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-latest)
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 `.pln` files:
333
+ Split a project across multiple `.ps` files:
234
334
 
235
- import "./math.pln"
236
- import "./utils.pln"
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.pln
249
- math.pln
250
- utils.pln
348
+ app.ps
349
+ math.ps
350
+ utils.ps
251
351
 
252
- `math.pln`:
352
+ `math.ps`:
253
353
 
254
354
  remember PI as 3.14
255
355
 
256
- `app.pln`:
356
+ `app.ps`:
257
357
 
258
- import "./math.pln"
358
+ import "./math.ps"
259
359
  show PI
260
360
 
261
- Output: one combined JavaScript file with `math.pln` code before `app.pln` code.
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.pln
345
- plainscript run app.pln
444
+ plainscript build app.ps
445
+ plainscript run app.ps
346
446
  ```
347
447
 
348
- `plainscript start` builds `src/app.pln` (or `src/index.pln`) into the output
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.pln
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.pln
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 `.pln` files
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 `.pln` file
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.pln>` | Install dependencies, compile and execute |
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.pln>` | Check syntax only (no output, no execution) |
999
- | `plainscript fmt <file.pln>` | Format a PlainScript file in-place |
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.pln and run its dist/ output |
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 v0.1.7.
1150
+ This document is the single source of truth for PlainScript v1.0.0-latest.
1051
1151
  Every compiler implementation must follow this specification.