plainscript-lang 1.0.0-beta → 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.
@@ -269,7 +269,7 @@ function parse(tokens) {
269
269
  if (token.type === TOKEN.IF) return parseIf();
270
270
  if (token.type === TOKEN.MAKE) return parseMake();
271
271
  if (token.type === TOKEN.GIVE) return parseGive();
272
- // v1.0.0 — generators: `yield <expr>` is only meaningful inside a function
272
+ // v1.0.0-latest — generators: `yield <expr>` is only meaningful inside a function
273
273
  // body; the generator marks the enclosing `make ... done` as a function*.
274
274
  if (token.type === TOKEN.YIELD) return parseYield();
275
275
  if (token.type === TOKEN.FOR) return parseForEach();
@@ -492,6 +492,15 @@ function parse(tokens) {
492
492
  return { type: 'StatusStatement', value };
493
493
  }
494
494
 
495
+ // v2.2.0 — redirect to "<url>": sends an HTTP redirect from a route
496
+ // handler. "redirect(...)" calls and "redirect becomes x" stay ordinary.
497
+ if (token.value === 'redirect' && peekAt(1).value === 'to') {
498
+ advance(); // redirect
499
+ advance(); // to
500
+ const url = parseExpression();
501
+ return { type: 'RedirectStatement', url };
502
+ }
503
+
495
504
  // ── v2.1.1 statements (all contextual, following the v2.1.0 pattern) ──
496
505
 
497
506
  // try … [recover [as <name>]] … done: deterministic error handling.
@@ -569,7 +578,7 @@ function parse(tokens) {
569
578
  return { type: 'GoogleOAuthStatement', options: parsePropertyList('"google oauth" block') };
570
579
  }
571
580
 
572
- // ── v1.0.0 — capability-gap features (all contextual, IOPL-native) ──
581
+ // ── v1.0.0-latest — capability-gap features (all contextual, IOPL-native) ──
573
582
 
574
583
  // define a kind called "Person" with … done → record schema (classes)
575
584
  if (token.value === 'define' &&
@@ -608,6 +617,29 @@ function parse(tokens) {
608
617
  return { type: 'ExportStatement', name };
609
618
  }
610
619
 
620
+ // throw <value> → raise an error for the caller's try/recover to catch.
621
+ // "throw(...)" calls and "throw becomes x" keep their ordinary meaning.
622
+ if (token.value === 'throw' &&
623
+ peekAt(1).type !== TOKEN.LPAREN && peekAt(1).type !== TOKEN.BECOMES) {
624
+ advance(); // throw
625
+ const value = parseExpression();
626
+ return { type: 'ThrowStatement', value };
627
+ }
628
+
629
+ // break / continue → loop control flow. Contextual keywords: a variable
630
+ // literally named break/continue is rejected by the teaching guard in
631
+ // generateStatement when not inside a loop.
632
+ if (token.value === 'break' &&
633
+ peekAt(1).type !== TOKEN.BECOMES && peekAt(1).type !== TOKEN.LPAREN) {
634
+ advance(); // break
635
+ return { type: 'BreakStatement' };
636
+ }
637
+ if (token.value === 'continue' &&
638
+ peekAt(1).type !== TOKEN.BECOMES && peekAt(1).type !== TOKEN.LPAREN) {
639
+ advance(); // continue
640
+ return { type: 'ContinueStatement' };
641
+ }
642
+
611
643
  const expr = parsePrimary();
612
644
 
613
645
  if (peek().type === TOKEN.BECOMES) {
@@ -867,7 +899,7 @@ function parse(tokens) {
867
899
  return { type: 'GiveStatement', value };
868
900
  }
869
901
 
870
- // v1.0.0 — generators: `yield <expr>` (optionally bare `yield`).
902
+ // v1.0.0-latest — generators: `yield <expr>` (optionally bare `yield`).
871
903
  function parseYield() {
872
904
  consume(TOKEN.YIELD);
873
905
  let value = null;
@@ -877,7 +909,7 @@ function parse(tokens) {
877
909
  return { type: 'YieldStatement', value };
878
910
  }
879
911
 
880
- // v1.0.0 — record kinds: `define a kind called "Person" with … done`
912
+ // v1.0.0-latest — record kinds: `define a kind called "Person" with … done`
881
913
  // The field block reuses the property-list grammar (`age is 0`), so each
882
914
  // field gets a default expression just like an object literal.
883
915
  function parseDefineKind() {
@@ -914,7 +946,7 @@ function parse(tokens) {
914
946
  return { type: 'DefineKindStatement', name, fields };
915
947
  }
916
948
 
917
- // v1.0.0 — record constructor (expression): `create a Person with name "Ada" and age 17`
949
+ // v1.0.0-latest — record constructor (expression): `create a Person with name "Ada" and age 17`
918
950
  function parseCreateKind() {
919
951
  advance(); // create
920
952
  advance(); // a / an
@@ -934,7 +966,7 @@ function parse(tokens) {
934
966
  return { type: 'CreateKindExpression', kind, pairs };
935
967
  }
936
968
 
937
- // v1.0.0 — native test DSL: `test "name" … done`
969
+ // v1.0.0-latest — native test DSL: `test "name" … done`
938
970
  function parseTestStatement() {
939
971
  advance(); // test
940
972
  const name = consume(TOKEN.STRING, 'Expected a test name string after "test".').value;
@@ -942,7 +974,7 @@ function parse(tokens) {
942
974
  return { type: 'TestStatement', name, body };
943
975
  }
944
976
 
945
- // v1.0.0 — assertions: `check <a> (equals|is|contains|raises) <b>`
977
+ // v1.0.0-latest — assertions: `check <a> (equals|is|contains|raises) <b>`
946
978
  function parseCheckStatement() {
947
979
  advance(); // check
948
980
  const a = parseExpression();
@@ -962,8 +994,49 @@ function parse(tokens) {
962
994
  // for every <item> in <collection> ... done (alias — "every" maps to EACH token)
963
995
  function parseForEach() {
964
996
  consume(TOKEN.FOR);
997
+
998
+ // for index <name> from <start> to <end> [by <step>] ... done
999
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'index') {
1000
+ advance(); // index
1001
+ const name = consume(
1002
+ TOKEN.IDENTIFIER,
1003
+ 'Expected an index name after "for index".\n\nExample:\n for index i from 0 to 9\n show i\n done'
1004
+ ).value;
1005
+ if (peek().type === TOKEN.IN || (peek().type === TOKEN.IDENTIFIER && peek().value === 'in')) {
1006
+ // for index <name> in <collection> — zero-based index over a list.
1007
+ advance(); // in
1008
+ const collection = parseExpression();
1009
+ const body = parseBody('"for index" loop');
1010
+ return { type: 'ForIndexStatement', name, start: null, end: collection, step: null, over: collection, body };
1011
+ }
1012
+ if (peek().type !== TOKEN.IDENTIFIER || peek().value !== 'from') {
1013
+ throw new Error(makeError(
1014
+ 'Expected "from" or "in" after the "for index" name.\n\nExample:\n for index i from 0 to 9\n for index i in players',
1015
+ peek()
1016
+ ));
1017
+ }
1018
+ advance(); // from
1019
+ const start = parseExpression();
1020
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'to') {
1021
+ advance(); // to
1022
+ } else {
1023
+ throw new Error(makeError(
1024
+ 'Expected "to" between the start and end of a "for index" loop.\n\nExample:\n for index i from 0 to 9',
1025
+ peek()
1026
+ ));
1027
+ }
1028
+ const end = parseExpression();
1029
+ let step = null;
1030
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'by') {
1031
+ advance(); // by
1032
+ step = parseExpression();
1033
+ }
1034
+ const body = parseBody('"for index" loop');
1035
+ return { type: 'ForIndexStatement', name, start, end, step, over: null, body };
1036
+ }
1037
+
965
1038
  consume(TOKEN.EACH,
966
- 'Expected "each" or "every" after "for".\n\nExample:\n for each item in players\n show item\n done');
1039
+ 'Expected "each", "every" or "index" after "for".\n\nExample:\n for each item in players\n show item\n done');
967
1040
  const item = consume(TOKEN.IDENTIFIER, 'Expected an item name after "each" or "every".').value;
968
1041
  consume(TOKEN.IN, `Expected "in" after "${item}".\n\nExample:\n for each item in players`);
969
1042
  const collection = parseExpression();
@@ -980,8 +1053,39 @@ function parse(tokens) {
980
1053
  }
981
1054
 
982
1055
  // import "./file.ps"
1056
+ // import { name1, name2 } from "./file.ps" (named imports — binds only the
1057
+ // listed symbols; the whole file is still bundled as a dependency)
983
1058
  function parseImport() {
984
1059
  consume(TOKEN.IMPORT);
1060
+
1061
+ // Named-import form: import { a, b } from "./file.ps"
1062
+ if (peek().type === TOKEN.LBRACE) {
1063
+ advance(); // {
1064
+ const names = [];
1065
+ while (true) {
1066
+ names.push(consume(
1067
+ TOKEN.IDENTIFIER,
1068
+ 'Expected an exported name inside the import braces.\n\nExample:\n import { helper } from "./util.ps"'
1069
+ ).value);
1070
+ if (peek().type === TOKEN.COMMA) { advance(); continue; }
1071
+ break;
1072
+ }
1073
+ consume(TOKEN.RBRACE,
1074
+ 'Expected "}" to close the import braces.\n\nExample:\n import { helper } from "./util.ps"');
1075
+ // The "from" is a plain identifier; tolerate its optional presence so
1076
+ // both "import { x } from "./f.ps"" and "import { x } "./f.ps"" read
1077
+ // naturally, but require it for the documented form.
1078
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'from') {
1079
+ advance(); // from
1080
+ }
1081
+ const filePath = consume(
1082
+ TOKEN.STRING,
1083
+ 'Expected a file path string after the import.\n\nExample:\n import { helper } from "./util.ps"'
1084
+ ).value;
1085
+ return { type: 'ImportStatement', path: filePath, names };
1086
+ }
1087
+
1088
+ // Whole-module form: import "./file.ps"
985
1089
  const filePath = consume(
986
1090
  TOKEN.STRING,
987
1091
  'Expected a file path string after "import".\n\nExample:\n import "./math.ps"'
@@ -1798,7 +1902,7 @@ function parse(tokens) {
1798
1902
 
1799
1903
  // primary → itemExpr | atom (postfix)*
1800
1904
  function parsePrimary() {
1801
- // v1.0.0 — record constructor: `create a Person with name "Ada" and age 17`.
1905
+ // v1.0.0-latest — record constructor: `create a Person with name "Ada" and age 17`.
1802
1906
  // `create` then an article ("a"/"an") then a kind name then "with" pairs.
1803
1907
  if (peek().type === TOKEN.IDENTIFIER && peek().value === 'create') {
1804
1908
  const a1 = peekAt(1);
@@ -1812,7 +1916,7 @@ function parse(tokens) {
1812
1916
  }
1813
1917
  }
1814
1918
 
1815
- // v1.0.0 — concurrency combinators: `all of [a(), b()]`, `any of [...]`,
1919
+ // v1.0.0-latest — concurrency combinators: `all of [a(), b()]`, `any of [...]`,
1816
1920
  // `settled of [...]`. Guard on the identifier + "of" lookahead so plain
1817
1921
  // property reads like `all of the_list` still work as well as prose.
1818
1922
  if (peek().type === TOKEN.IDENTIFIER &&
@@ -1824,7 +1928,7 @@ function parse(tokens) {
1824
1928
  return { type: 'ConcurrencyExpression', combo: comboKw, items };
1825
1929
  }
1826
1930
 
1827
- // v1.0.0 — `spread of <collection>` unfolds an iterable into a new array.
1931
+ // v1.0.0-latest — `spread of <collection>` unfolds an iterable into a new array.
1828
1932
  if (peek().type === TOKEN.IDENTIFIER && peek().value === 'spread' &&
1829
1933
  peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'of') {
1830
1934
  advance(); // spread
@@ -1844,8 +1948,31 @@ function parse(tokens) {
1844
1948
  node = { type: 'IndexExpression', object: node, index };
1845
1949
  } else if (peek().type === TOKEN.DOT) {
1846
1950
  advance();
1847
- const property = consume(TOKEN.IDENTIFIER, 'Expected a property name after ".".').value;
1951
+ // After ".", any word is a valid JS property/method name — including
1952
+ // words that are PlainScript keywords in other contexts (e.g. crypto
1953
+ // .update(...), obj .delete()). So accept any word token, not just an
1954
+ // identifier.
1955
+ const propToken = peek();
1956
+ if (propToken.type === TOKEN.EOF || !/^[A-Za-z_$]/.test(propToken.value)) {
1957
+ throw new Error(makeError('Expected a property name after ".".', propToken));
1958
+ }
1959
+ advance();
1960
+ const property = propToken.value;
1848
1961
  node = { type: 'MemberExpression', object: node, property };
1962
+ // Method call: object.method(args). Only member access may introduce
1963
+ // a call here; plain `name(args)` is handled in parseAtom.
1964
+ if (peek().type === TOKEN.LPAREN) {
1965
+ advance(); // (
1966
+ const { separator, args } = parseArgList();
1967
+ consume(TOKEN.RPAREN, 'Expected ")" to close the method call.');
1968
+ if (separator) {
1969
+ throw new Error(makeError(
1970
+ 'Method calls cannot use "to"/"from" arguments.\n\nExample:\n mrz.parse(line)',
1971
+ peek()
1972
+ ));
1973
+ }
1974
+ node = { type: 'CallExpression', callee: node, args };
1975
+ }
1849
1976
  } else if (peek().type === TOKEN.IDENTIFIER && peek().value === 'of') {
1850
1977
  if (node.type !== 'Identifier') {
1851
1978
  throw new Error(makeError(
@@ -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-beta';
4
+ const VERSION = '1.0.0-latest';
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 1.0.0-latest — 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 for the 1.0.0-latest milestone. 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.0-latest 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.0-latest "ready" until this audit is
19
19
  > complete and its shipped resolutions are exercised by the test suite.
20
20
  >
21
21
  > ---
@@ -110,7 +110,7 @@ define a kind called "Person" with
110
110
  age is 0
111
111
  done
112
112
 
113
- make a Person with name "Ada" and age 17
113
+ remember ada as create a Person with name "Ada" and age 17
114
114
  show name of ada // "Ada"
115
115
  ```
116
116
 
@@ -126,7 +126,7 @@ show name of ada // "Ada"
126
126
 
127
127
  | TypeScript | PlainScript resolution |
128
128
  |-------------------------|------------------------|
129
- | `class`, constructor | **IOPL-native `kind` + `make a X with ...`** (this release). |
129
+ | `class`, constructor | **IOPL-native `kind` + `create a X with ...`** (this release). |
130
130
  | Fields / properties | `kind` fields; access via `name of x` / `x.name`. |
131
131
  | Methods | Top-level `make` functions taking the record. |
132
132
  | `this` | **Rationale: unnecessary** — functions receive the record explicitly (no context bugs). |
@@ -366,7 +366,7 @@ rows without reducing capability parity.
366
366
 
367
367
  ---
368
368
 
369
- ## 21. 1.0.0 readiness gate
369
+ ## 21. 1.0.0-latest readiness gate
370
370
 
371
371
  The audit is **complete** only when:
372
372
 
@@ -376,4 +376,64 @@ The audit is **complete** only when:
376
376
  3. The runtime stdlib table, knowledge base, and README document every new
377
377
  capability.
378
378
 
379
- Until then the package version remains **below 1.0.0**.
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,4 +1,4 @@
1
- # PlainScript Language Specification (v1.0.0-beta)
1
+ # PlainScript Language Specification (v1.0.0-latest)
2
2
 
3
3
  Version: 2.1.1
4
4
  Status: Stable
@@ -155,7 +155,7 @@ While:
155
155
 
156
156
  ---
157
157
 
158
- ## Record Kinds, Classes & Concurrency (v1.0.0-beta)
158
+ ## Record Kinds, Classes & Concurrency (v1.0.0-latest)
159
159
 
160
160
  These features close the capability-gap audit (`docs/CAPABILITY_GAP_AUDIT.md`) in
161
161
  PlainScript's own intent-oriented grammar.
@@ -1147,5 +1147,5 @@ If a package is missing, the compiler prints a friendly error and stops:
1147
1147
 
1148
1148
  ---
1149
1149
 
1150
- This document is the single source of truth for PlainScript v1.0.0-beta.
1150
+ This document is the single source of truth for PlainScript v1.0.0-latest.
1151
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">v1.0.0-beta</span>
38
+ <span class="logo-ver">v1.0.0-latest</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">v1.0.0-beta — intent-oriented, TypeScript-capable</div>
88
+ <div class="hero-badge">v1.0.0-latest — 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>
@@ -109,11 +109,12 @@
109
109
  <button class="code-copy" aria-label="Copy code"><i class="far fa-copy"></i></button>
110
110
  </div>
111
111
  <div class="code-window-body">
112
- <pre><code>server on port 3000
113
- when someone visits "/"
114
- send "Hello, World!"
112
+ <pre><code>web app
113
+ route get "/"
114
+ reply "Hello, World!"
115
+ done
115
116
 
116
- log "Server is running"</code></pre>
117
+ show "Server is running"</code></pre>
117
118
  </div>
118
119
  </div>
119
120
  <div class="code-window">
@@ -235,16 +236,18 @@ console.log("Server is running");</code></pre>
235
236
  <button class="code-copy" aria-label="Copy code"><i class="far fa-copy"></i></button>
236
237
  </div>
237
238
  <div class="code-window-body">
238
- <pre><code>use express
239
-
240
- server on port 3000
241
- when someone visits "/"
242
- send "Hello, World!"
243
-
244
- when someone visits "/users"
245
- send json of users
246
-
247
- log "Server running on port 3000"</code></pre>
239
+ <pre><code>web app
240
+ route get "/"
241
+ reply "Hello, World!"
242
+ done
243
+
244
+ route get "/users"
245
+ reply json
246
+ count is 3
247
+ done
248
+ done
249
+
250
+ show "Server running on port 3000"</code></pre>
248
251
  </div>
249
252
  </div>
250
253
  <div class="code-window">
@@ -296,11 +299,13 @@ app.listen(3000, () => {
296
299
  <div class="code-window-body">
297
300
  <pre><code>database "app.db"
298
301
 
299
- query "SELECT * FROM users WHERE active = 1"
300
- save as results
302
+ remember results as query
303
+ SELECT * FROM users WHERE active = 1
304
+ done
301
305
 
302
306
  for each user in results
303
- log user.name</code></pre>
307
+ show user.name
308
+ done</code></pre>
304
309
  </div>
305
310
  </div>
306
311
  <div class="code-window">
@@ -602,7 +607,7 @@ use dotenv</code></pre>
602
607
  </div>
603
608
  <div class="footer-bottom">
604
609
  <p>&copy; 2026 PlainScript. Built by Ayokunle.</p>
605
- <span class="footer-badge">v1.0.0-beta</span>
610
+ <span class="footer-badge">v1.0.0-latest</span>
606
611
  </div>
607
612
  </div>
608
613
  </footer>
@@ -766,7 +766,7 @@ var LIBRARY = [
766
766
  {cat:"server",name:"404 Catch-All",desc:"Handle unmatched routes",ps:'when nothing matches\n status 404\n reply "Page not found"\ndone',js:'app.use((req, res) => {\n res.status(404);\n res.send("Page not found");\n});',skipRun:true},
767
767
  {cat:"server",name:"Validate Request Body",desc:"Require specific fields in the request body",ps:'route post "/users"\n validate(body of request, ["name", "email"])\n reply "Created"\ndone',js:'app.post("/users", (req, res) => {\n __validate(req.body, ["name", "email"]);\n res.send("Created");\n});',skipRun:true},
768
768
  {cat:"auth",name:"Google OAuth",desc:"Add Google login to your app",ps:'web app\ngoogle oauth\n id is env("GOOGLE_CLIENT_ID")\n secret is env("GOOGLE_CLIENT_SECRET")\n callback is "/auth/google/callback"\n landing is "/dashboard"\ndone',js:'__googleOAuth(app, {\n clientId: process.env["GOOGLE_CLIENT_ID"],\n clientSecret: process.env["GOOGLE_CLIENT_SECRET"],\n callbackUrl: "/auth/google/callback",\n afterLogin: "/dashboard"\n});'},
769
- {cat:"cli",name:"CLI: version",desc:"Print the PlainScript version",ps:'plainscript version',js:'// Prints v1.0.0-beta',skipRun:true},
769
+ {cat:"cli",name:"CLI: version",desc:"Print the PlainScript version",ps:'plainscript version',js:'// Prints v1.0.0-latest',skipRun:true},
770
770
  {cat:"cli",name:"CLI: help",desc:"Show available commands",ps:'plainscript help',js:'// Lists all CLI commands',skipRun:true},
771
771
  {cat:"cli",name:"CLI: info",desc:"Display platform and runtime info",ps:'plainscript info',js:'// Shows version, Node version, OS',skipRun:true},
772
772
  {cat:"cli",name:"CLI: clean",desc:"Remove compiled output",ps:'plainscript clean',js:'// Deletes dist/ folder',skipRun:true},
@@ -0,0 +1,56 @@
1
+ // PlainScript v1.0.0-latest — API key protection, rate limits and tokens
2
+ //
3
+ // Run with: API_KEY=my-secret plainscript run examples/auth-api.ps
4
+ // Then try:
5
+ // curl -H "x-api-key: my-secret" http://localhost:3000/status
6
+ // curl http://localhost:3000/status # 401 without the key
7
+ //
8
+ // Routes registered after "require api key" are guarded; the health route is
9
+ // registered first so uptime checks keep working.
10
+
11
+ web app
12
+
13
+ route get "/health"
14
+ reply "alive"
15
+ done
16
+
17
+ require api key from env("API_KEY")
18
+ limit requests to 60 per minute
19
+
20
+ remember secret as env("TOKEN_SECRET")
21
+
22
+ route get "/status"
23
+ reply json
24
+ status is "ok"
25
+ version is "1.0.0-latest"
26
+ done
27
+ done
28
+
29
+ route post "/token"
30
+ remember payload as
31
+ sub is "user-1"
32
+ role is "admin"
33
+ done
34
+ remember issued as createToken(payload, secret, 1800)
35
+ reply json
36
+ token is issued
37
+ done
38
+ done
39
+
40
+ route get "/verify"
41
+ remember supplied as header("x-token")
42
+ remember claims as readToken(supplied, secret)
43
+ if claims is empty
44
+ status 401
45
+ reply json
46
+ error is "invalid or expired token"
47
+ done
48
+ otherwise
49
+ reply json
50
+ sub is sub of claims
51
+ role is role of claims
52
+ done
53
+ done
54
+ done
55
+
56
+ start 3000
@@ -0,0 +1,49 @@
1
+ // PlainScript v1.0.0-latest — Concurrency: combinators, timeouts and workers
2
+ //
3
+ // Run with: plainscript run examples/concurrency.ps
4
+ //
5
+ // all / any / settled run several promises in parallel; withTimeout bounds
6
+ // how long one may take; run background fires work without blocking.
7
+
8
+ make fetchUsers()
9
+ sleep(300)
10
+ give { source: "users", count: 42 }
11
+ done
12
+
13
+ make fetchOrders()
14
+ sleep(150)
15
+ give { source: "orders", count: 17 }
16
+ done
17
+
18
+ make flakyFetch()
19
+ remember data as jsonDecode("not json")
20
+ give data
21
+ done
22
+
23
+ // Every item must resolve — an array of results
24
+ remember dashboard as all of [fetchUsers(), fetchOrders()]
25
+ for each panel in dashboard
26
+ show source of panel + ": " + text(count of panel)
27
+ done
28
+
29
+ // First to settle wins
30
+ remember first as any of [fetchUsers(), fetchOrders()]
31
+ show "first: " + source of first
32
+
33
+ // Never throws; each outcome is a record with a status
34
+ remember results as settled of [fetchUsers(), flakyFetch()]
35
+ for each outcome in results
36
+ if status of outcome is "fulfilled"
37
+ show "ok: " + text(value of outcome)
38
+ otherwise
39
+ show "failed: " + message of reason of outcome
40
+ done
41
+ done
42
+
43
+ // Bound a slow call
44
+ remember bounded as withTimeout(fetchUsers(), 2000)
45
+ show "bounded result ready"
46
+
47
+ // Fire-and-forget background work
48
+ run background fetchUsers()
49
+ show "background job launched — this line prints immediately"
@@ -0,0 +1,54 @@
1
+ // PlainScript v1.0.0-latest — Robust error handling
2
+ //
3
+ // Run with: plainscript run examples/error-handling.ps
4
+ //
5
+ // Shows deterministic recovery: typed "recover" blocks, silent swallowing,
6
+ // and automatic retries with backoff for flaky operations.
7
+
8
+ make parseSettings(raw)
9
+ remember settings as jsonDecode(raw)
10
+ if settings is empty
11
+ give { theme: "light" }
12
+ otherwise
13
+ give settings
14
+ done
15
+ done
16
+
17
+ // Recover with the thrown value
18
+ try
19
+ remember settings as parseSettings("{ bad json")
20
+ show theme of settings
21
+ recover as err
22
+ show "falling back: " + message of err
23
+ remember settings as { theme: "dark" }
24
+ show theme of settings
25
+ done
26
+
27
+ // Multiple typed recover clauses win on error name
28
+ try
29
+ remember parsed as jsonDecode("also not json")
30
+ recover when err catches "SyntaxError"
31
+ show "JSON parse error caught: " + message of err
32
+ recover as err
33
+ show "some other error: " + message of err
34
+ done
35
+
36
+ // Swallow failures silently when no recover is present
37
+ try
38
+ remember probe as read("does-not-exist.txt")
39
+ done
40
+ show "survived the failed read"
41
+
42
+ // Automatic retry with a delay
43
+ remember logs as []
44
+ make fetchStatus()
45
+ add("trying…" to logs)
46
+ give read("status.db.json")
47
+ done
48
+
49
+ retry 3 times every 1 second
50
+ remember body as fetchStatus()
51
+ show body
52
+ done
53
+
54
+ show length(logs)