plainscript-lang 1.0.0 → 1.0.2-rfc

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 (52) hide show
  1. package/README.md +157 -150
  2. package/compiler/bundler.js +2 -2
  3. package/compiler/cli.js +172 -65
  4. package/compiler/formatter.js +1 -1
  5. package/compiler/generator.js +905 -184
  6. package/compiler/lexer.js +128 -54
  7. package/compiler/parser.js +1075 -155
  8. package/compiler/version.js +1 -1
  9. package/docs/CAPABILITY_GAP_AUDIT.md +131 -30
  10. package/docs/PLAINSCRIPT-SPEC.md +584 -0
  11. package/docs/index.html +48 -52
  12. package/docs/website/script.js +110 -24
  13. package/docs/website/style.css +4 -4
  14. package/examples/arrays.pln +12 -0
  15. package/examples/{auth-api.ps → auth-api.pln} +3 -3
  16. package/examples/{cache-and-jobs.ps → cache-and-jobs.pln} +1 -1
  17. package/examples/{concurrency.ps → concurrency.pln} +8 -8
  18. package/examples/{database.ps → database.pln} +1 -1
  19. package/examples/{deployment.ps → deployment.pln} +2 -2
  20. package/examples/{email-send.ps → email-send.pln} +1 -1
  21. package/examples/{error-handling.ps → error-handling.pln} +8 -7
  22. package/examples/{expressions.ps → expressions.pln} +1 -1
  23. package/examples/{file-uploads.ps → file-uploads.pln} +4 -4
  24. package/examples/{files-and-config.ps → files-and-config.pln} +4 -4
  25. package/examples/football-backend/{app.ps → app.pln} +2 -2
  26. package/examples/{http-client.ps → http-client.pln} +18 -18
  27. package/examples/id-verification/{app.ps → app.pln} +1 -1
  28. package/examples/{loops.ps → loops.pln} +2 -3
  29. package/examples/modules/{app.ps → app.pln} +4 -4
  30. package/examples/modules/{math.ps → math.pln} +1 -1
  31. package/examples/{record-kinds.ps → record-kinds.pln} +4 -4
  32. package/examples/{rest-api-fetch.ps → rest-api-fetch.pln} +1 -1
  33. package/examples/{rest-api.ps → rest-api.pln} +5 -5
  34. package/examples/{scheduled-tasks.ps → scheduled-tasks.pln} +2 -2
  35. package/examples/{search-and-filter.ps → search-and-filter.pln} +5 -5
  36. package/examples/{sessions-and-cookies.ps → sessions-and-cookies.pln} +2 -2
  37. package/examples/start.pln +2 -0
  38. package/examples/{stdlib.ps → stdlib.pln} +2 -2
  39. package/examples/{telegram-bot.ps → telegram-bot.pln} +2 -2
  40. package/examples/{websocket-server.ps → websocket-server.pln} +1 -1
  41. package/package.json +2 -2
  42. package/docs/PLINJS_SPEC.md +0 -1151
  43. package/examples/arrays.ps +0 -13
  44. package/examples/start.ps +0 -2
  45. /package/examples/{day2.ps → day2.pln} +0 -0
  46. /package/examples/{day3.ps → day3.pln} +0 -0
  47. /package/examples/{hello.ps → hello.pln} +0 -0
  48. /package/examples/{objects.ps → objects.pln} +0 -0
  49. /package/examples/{server.ps → server.pln} +0 -0
  50. /package/examples/{web-app.ps → web-app.pln} +0 -0
  51. /package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +0 -0
  52. /package/examples/whatsapp-bot/{qr.ps → qr.pln} +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 = '1.0.0';
4
+ const VERSION = '1.0.2';
5
5
 
6
6
  module.exports = { VERSION };
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.0 — Capability-Gap Audit vs. TypeScript / Node.js
1
+ # PlainScript 2.4 — Capability-Gap Audit vs. TypeScript / Node.js
2
2
 
3
3
  > **Purpose.** PlainScript's goal is **capability parity**, not syntax parity, with
4
4
  > modern TypeScript + Node.js. We do not clone TypeScript's syntax or its static
@@ -6,16 +6,16 @@
6
6
  > (IOPL) — you describe *what* you want, and the deterministic compiler decides
7
7
  > *how* to implement it in JavaScript.
8
8
  >
9
- > This document is the complete working audit for the 1.0.0 milestone. For every
9
+ > This document is the complete working audit through v2.4. For every
10
10
  > major TypeScript/Node.js capability area, it records:
11
11
  >
12
- > - **Status** — what PlainScript 1.0.0 already does,
12
+ > - **Status** — what PlainScript 1.0.2 already does,
13
13
  > - **Gap** — what is missing for real-world capability parity,
14
14
  > - **Resolution** — either an *IOPL-native implementation* (shipped in this
15
15
  > release and covered by tests) or an explicit *rationale* for why the
16
16
  > capability is unnecessary / already supplied by the host runtime.
17
17
  >
18
- > **Gate:** PlainScript must NOT be declared 1.0.0 "ready" until this audit is
18
+ > **Gate:** PlainScript must NOT be declared 1.0.2 "ready" until this audit is
19
19
  > complete and its shipped resolutions are exercised by the test suite.
20
20
  >
21
21
  > ---
@@ -50,8 +50,8 @@ normal Node `dist/`, do what the TypeScript program can?"
50
50
  |------------------------------------|------------------------|
51
51
  | Interfaces / type aliases | **IOPL-native `kind` record schema** (§8). Declares fields + defaults; compile-checked constructors. |
52
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). |
53
+ | Unions / literals | **Rationale: unnecessary.** `match <expr> against ... end` (existing) exhaustively branches on runtime values. |
54
+ | Optional / default params | **IOPL-native** — `define f(x, y as 0)` (existing, RFC-0011). |
55
55
  | Rest params / spread | **IOPL-native `spread of`** — see §6 collections. |
56
56
  | Non-null / optional chaining | **Runtime null-safety stdlib** — `valueOf(key, fallback)`, `hasField(rec, key)` (§13). Avoids `?.` syntax. |
57
57
  | `typeof`/`keyof` type queries | **Runtime reflection stdlib** — `typeOf(x)`, `fieldsOf(x)` (§13). |
@@ -68,11 +68,11 @@ omitted (rationale above). **Gap closed for 80% target.**
68
68
 
69
69
  | TypeScript | PlainScript resolution |
70
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). |
71
+ | ES `import`/`export` | **Exists**: `import "./file.pln"` (§ bundler), top-level `define` auto-exported to `module.exports`. |
72
+ | Named imports | **IOPL-native `import ... from`** — `import { name } from "./util.pln"` binds only named symbols (this release). |
73
73
  | Dynamic `import()` | **Runtime stdlib `loadModule(path)`** returning the required module (this release). |
74
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). |
75
+ | Barrel files | **Works** — `import "./index.pln"` where index imports the rest (existing bundler de-dups). |
76
76
  | `import type` | **Rationale: unnecessary** — searchable types). |
77
77
  | Node built-ins | **Runtime stdlib** `use fs`, `use path`, and IOPL `read/write/...` (existing). |
78
78
 
@@ -89,8 +89,8 @@ already present. **Gap closed.**
89
89
  | `Promise.all` | **IOPL-native `all of [e1, e2, ...]`** (this release). |
90
90
  | `Promise.race` | **IOPL-native `any of [e1, e2, ...]`** (this release). |
91
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). |
92
+ | `await Promise.all([...])` in one line | `all of [...]` is already awaited — `let results is all of [a(), b()]`. |
93
+ | Worker threads / parallel jobs | **IOPL-native `run in parallel ... end [as results]`** (existing, RFC-0011 ¶9) and `run background <call>` (existing). |
94
94
  | Cancellation / AbortController | **Runtime `withTimeout(promise, ms)`** raises on timeout (this release). |
95
95
 
96
96
  **Audit status:** `all/any/settled of`, `withTimeout` ship on top of the existing
@@ -108,29 +108,34 @@ prose constructor — rather than `class`/`new`/`extends` syntax.
108
108
  define a kind called "Person" with
109
109
  name is ""
110
110
  age is 0
111
- done
111
+ end
112
+
113
+ let ada is create a Person with name "Ada" and age 17
114
+ print name of ada // "Ada"
112
115
 
113
- make a Person with name "Ada" and age 17
114
- show name of ada // "Ada"
116
+ // v2.4 near-English alternative:
117
+ when ada has field "name"
118
+ print ada name at position 1 in name of ada
119
+ done
115
120
  ```
116
121
 
117
122
  - Fields declared with defaults; constructors **prompt for missing required
118
123
  fields** at compile time; unknown constructor fields are a compile error.
119
124
  - Kind objects are plain JS objects, so `jsonEncode`, `sendMail`, DB rows,
120
125
  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`).
126
+ - Attach behaviour with ordinary `define` functions that take the record
127
+ (`define describe(person) give name of person + " is " + age of person`).
123
128
  - **Inheritance** is deliberately *composition-first*: `kind` + stdlib
124
129
  `merge(a, b)` (existing) covers the 80%. Deep prototype chains are a
125
130
  TypeScript *syntax*, not a capability we need to replicate.
126
131
 
127
132
  | TypeScript | PlainScript resolution |
128
133
  |-------------------------|------------------------|
129
- | `class`, constructor | **IOPL-native `kind` + `make a X with ...`** (this release). |
134
+ | `class`, constructor | **IOPL-native `kind` + `create a X with ...`** (this release). |
130
135
  | Fields / properties | `kind` fields; access via `name of x` / `x.name`. |
131
- | Methods | Top-level `make` functions taking the record. |
136
+ | Methods | Top-level `define` functions taking the record. |
132
137
  | `this` | **Rationale: unnecessary** — functions receive the record explicitly (no context bugs). |
133
- | `static` members | Module-level`remember`/`make` are naturally static. |
138
+ | `static` members | Module-level `let`/`define` are naturally static. |
134
139
  | Extension / mixins | `merge(a, b)` (existing) + nested kinds. |
135
140
  | Access modifiers | **Rationale: unnecessary** — single-process bundles; `_field` is convention. |
136
141
 
@@ -143,9 +148,9 @@ and JSON/serialization compat. **Gap closed.**
143
148
 
144
149
  | TypeScript | PlainScript resolution |
145
150
  |------------------|------------------------|
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`). |
151
+ | `for...of` | `for each item in x ... end` (existing) — works on arrays, strings, Maps, Sets, generators. |
152
+ | Generator `function*` / `yield` | **IOPL-native `yield`** inside `define ... end` (this release) — a `define` containing `yield` compiles to a `function*`. |
153
+ | `[Symbol.iterator]` | Accessible via JS Gateway / `kind` producer (this release: `define` with `yield`). |
149
154
  | Iterator helpers (`map`/`filter`/`reduce`) | **IOPL-native** `gather each ... giving`, `filter each ... when`, `total each ... giving` (existing, functional map/filter/reduce). |
150
155
  | Spread `/ rest` | **IOPL-native `spread of x`** unfolds an iterable into a new array (this release). |
151
156
  | Lazy sequences | Generators via `yield` + `for each` (this release). |
@@ -164,6 +169,23 @@ and JSON/serialization compat. **Gap closed.**
164
169
  | Object | `merge`, `keys`, `values`, `hasKey`, `of` chains (existing) + `fieldsOf` (this release). |
165
170
  | Tuple | **`kind` with positional fields** (§4). |
166
171
 
172
+ **v2.4 enhancement:** Near-English syntax for collection access:
173
+
174
+ ```
175
+ // Array indexing
176
+ let first be name at position 1 in players
177
+
178
+ // Property existence check
179
+ when user has field "email"
180
+ show "has email"
181
+ done
182
+
183
+ // String matching
184
+ when email made of "@"
185
+ show "valid email"
186
+ done
187
+ ```
188
+
167
189
  **Audit status:** Map/Set/`spread of` stdlib ship. **Gap closed.**
168
190
 
169
191
  ---
@@ -222,7 +244,7 @@ and JSON/serialization compat. **Gap closed.**
222
244
 
223
245
  | TypeScript / Node | PlainScript resolution |
224
246
  |-------------------|------------------------|
225
- | Worker threads | **IOPL-native `run in parallel ... done`** (existing) and `run background <call>` (existing). |
247
+ | Worker threads | **IOPL-native `run in parallel ... end`** (existing) and `run background <call>` (existing). |
226
248
  | Child processes | **Runtime stdlib `runCommand(cmd, args)`** (async, captures stdout/stderr/exit) (this release). |
227
249
  | `process.exit` | `exit(code)` (existing); `env()` (existing). |
228
250
  | Signals / IPC | **Rationale: unnecessary for 80%** — batch/parallel covers CPU-bound; cross-process messaging is niche. JS Gateway for the rest. |
@@ -251,7 +273,7 @@ and JSON/serialization compat. **Gap closed.**
251
273
 
252
274
  | Node stream | PlainScript resolution |
253
275
  |--------------------|------------------------|
254
- | Read line-by-line | **IOPL-native `stream "file" as line ... done`** (existing). |
276
+ | Read line-by-line | **IOPL-native `stream "file" as line ... end`** (existing). |
255
277
  | Write append | `writeLine(file, text)` / `appendLine(file, text)` (this release). |
256
278
  | Transform / pipe | **Rationale: necessary via JS Gateway only** — stream pipelines are an implementation detail; `write`/`read`/`stream` cover I/O. |
257
279
 
@@ -305,17 +327,32 @@ and JSON/serialization compat. **Gap closed.**
305
327
 
306
328
  | TypeScript / Node | PlainScript resolution |
307
329
  |-------------------|------------------------|
308
- | Test runner | **IOPL-native `test "name" ... done` blocks** with `check a equals b`, `check a is true`, `check raises` (this release). |
330
+ | Test runner | **IOPL-native `test "name" ... end` blocks** with `check a equals b`, `check a is true`, `check raises` (this release). |
309
331
  | Assertions | `check a equals b` / `check a contains b` / `check a raises <msg>` (this release). |
310
332
  | Suite grouping | `test` blocks run in order; `check` failures print and exit `1` (this release). |
311
333
 
334
+ **v2.4 enhancement:** The near-English syntax extends to testing:
335
+
336
+ ```
337
+ test "string checks"
338
+ check name starts as "Ay"
339
+ check name ends as "le"
340
+ check name made of "oku"
341
+ done
342
+
343
+ test "comparisons"
344
+ check age more than 18
345
+ check status same as "active"
346
+ done
347
+ ```
348
+
312
349
  **Audit status:** A native test DSL ships — no external runner needed. **Gap closed.**
313
350
 
314
351
  ---
315
352
 
316
353
  ## 18. JavaScript Gateway (escape hatch)
317
354
 
318
- The **JavaScript Gateway** (`javascript ... done`, RFC-0011 §10) is the universal
355
+ The **JavaScript Gateway** (`javascript ... end`, RFC-0011 §10) is the universal
319
356
  fallback that closes *every* remaining micro-gap — any of TypeScript's capabilities
320
357
  that is expressible in JS is reachable here without leaving PlainScript. This
321
358
  single feature is why the audit can be honest about the many "rationale: omitted"
@@ -331,7 +368,7 @@ rows without reducing capability parity.
331
368
  |-----------------------|------------------------|
332
369
  | Publish npm library | `plainscript build` → `dist/`; `main`/`prepare` in package.json (existing). |
333
370
  | 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). |
371
+ | Consumer API | `module.exports` of top-level `define` (existing) + explicit `export` (this release). |
335
372
  | `exports` map / ESM | Standard `package.json` semantics (project model, existing). |
336
373
 
337
374
  **Audit status:** export statement ships. **Gap closed.**
@@ -360,13 +397,14 @@ rows without reducing capability parity.
360
397
  | CLI tooling | ✅ args() + runCommand |
361
398
  | Testing | ✅ test/check DSL |
362
399
  | Package/library authoring | ✅ export + build model |
400
+ | v2.4 Near-English syntax | ✅ English comparisons, access, calls, error handling |
363
401
  | JavaScript Gateway | ✅ universal fallback |
364
402
 
365
403
  **Legend:** ✅ shipped + tested · ⚪ intentionally omitted with rationale.
366
404
 
367
405
  ---
368
406
 
369
- ## 21. 1.0.0 readiness gate
407
+ ## 21. 1.0.2 readiness gate
370
408
 
371
409
  The audit is **complete** only when:
372
410
 
@@ -376,13 +414,13 @@ The audit is **complete** only when:
376
414
  3. The runtime stdlib table, knowledge base, and README document every new
377
415
  capability.
378
416
 
379
- Until then the package version remains **below 1.0.0**.
417
+ Until then the package version remains **below 1.0.2**.
380
418
 
381
419
  ---
382
420
 
383
421
  ## 22. v2.2.0 — AI/ML, data/storage & web additions
384
422
 
385
- The v2.0–v2.2 releases close further gaps beyond the 1.0.0 audit across the
423
+ The v2.0–v2.2 releases close further gaps beyond the 1.0.2 audit across the
386
424
  AI/ML, data/storage and web/full-stack surface. All features below are
387
425
  IOPL-native (intent-oriented) rather than TypeScript-syntax clones.
388
426
 
@@ -437,3 +475,66 @@ is named `includes`.
437
475
  > sandboxes where native deps (`express`, `sql.js`, `ws`) cannot be installed;
438
476
  > web/HTTP features are therefore **compile-verified** there. Core language,
439
477
  > collections, AI (with a live key), and cache fallback run with real tests.
478
+
479
+ ---
480
+
481
+ ## 23. v2.4 — Near-English Syntax Additions
482
+
483
+ The v2.4 release introduces near-English syntax forms that make PlainScript code read like natural sentences. These forms improve readability and lower the barrier for non-programmers while maintaining full capability parity with TypeScript/Node.js.
484
+
485
+ ### Readability & Comparisons
486
+
487
+ | Capability | v2.4 English Syntax | Existing Equivalent |
488
+ |-------------------------|----------------------------------------------------------|------------------------------|
489
+ | Greater than | `a more than b` | `a is greater than b` |
490
+ | Less than | `a fewer than b` | `a is less than b` |
491
+ | Strict equality | `a same as b` | `a is equal to b` |
492
+ | Strict inequality | `a different from b` | `a is not b` |
493
+ | Starts with | `name starts as "x"` | `name starts with "x"` |
494
+ | Ends with | `name ends as "x"` | `name ends with "x"` |
495
+ | Includes | `name made of "x"` | `name contains "x"` |
496
+
497
+ ### Object & Array Access
498
+
499
+ | Capability | v2.4 English Syntax | Existing Equivalent |
500
+ |-------------------------|----------------------------------------------------------|------------------------------|
501
+ | Array indexing | `name at position N in list` | `list[N]` |
502
+ | Property check | `obj has field "name"` | `"name" in obj` |
503
+
504
+ ### Control Flow
505
+
506
+ | Capability | v2.4 English Syntax | Existing Equivalent |
507
+ |-------------------------|----------------------------------------------------------|------------------------------|
508
+ | Ternary expression | `choosing cond then a otherwise b` | inline `when ... done` |
509
+ | Throw error | `raise "message"` | `throw "message"` |
510
+ | Simple recovery | `handled by` (no error binding) | `recover as err` |
511
+
512
+ ### Function Calls
513
+
514
+ | Capability | v2.4 English Syntax | Existing Equivalent |
515
+ |-------------------------|----------------------------------------------------------|------------------------------|
516
+ | Call function | `func together arg1, arg2` | `func(arg1, arg2)` |
517
+ | Call and capture | `fill result with func together arg1, arg2` | `let result be func(arg1, arg2)` |
518
+
519
+ ### Capability Gap Closure
520
+
521
+ The v2.4 near-English syntax addresses several readability gaps identified in earlier audits:
522
+
523
+ 1. **Comparison verbosity** — Prior versions required `is greater than`, `is less than`, etc. The new `more than`/`fewer than` forms reduce cognitive load and read more naturally.
524
+
525
+ 2. **String checking readability** — `starts as`, `ends as`, `made of` are more intuitive than `starts with`, `ends with`, `contains` for developers coming from natural language.
526
+
527
+ 3. **Ternary readability** — The `choosing ... then ... otherwise` form replaces nested `when ... done` blocks for simple conditional assignment, closing the gap with TypeScript's `? :` operator in readability.
528
+
529
+ 4. **Error handling clarity** — `raise` is clearer than `throw` for non-English speakers, and `handled by` provides a simpler alternative to `recover as` when the error value is not needed.
530
+
531
+ 5. **Function call clarity** — The `together` keyword makes function calls explicit in prose code, and `fill ... with` provides a readable assignment form.
532
+
533
+ 6. **Object/array access** — `at position N` and `has field` make indexing and property checks read like English sentences.
534
+
535
+ ### Testing Notes
536
+
537
+ All v2.4 near-English syntax forms are:
538
+ - **Compile-verified** — the compiler accepts both old and new syntax interchangeably
539
+ - **Runtime-tested** — the test suite exercises both forms for every feature
540
+ - **Backward-compatible** — existing PlainScript code continues to work unchanged