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
@@ -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
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — Cache, background jobs and cron working together
2
2
  //
3
- // Run with: REDIS_URL=redis://localhost:6379 plainscript run examples/cache-and-jobs.pln
3
+ // Run with: REDIS_URL=redis://localhost:6379 plainscript run examples/cache-and-jobs.ps
4
4
  //
5
5
  // Heavy work is pushed off the request path with "run background", shared
6
6
  // state lives in Redis, and a cron job refreshes it every minute.
@@ -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"
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — Databases: SQLite, parameters and transactions
2
2
  //
3
- // Run with: plainscript run examples/database.pln
3
+ // Run with: plainscript run examples/database.ps
4
4
  //
5
5
  // SQL placeholders are written {likeThis} and bind to PlainScript variables of
6
6
  // the same name. A transaction block runs all enclosed writes atomically.
@@ -1,7 +1,7 @@
1
1
  // PlainScript v1.0.1 — runtime dependency and deployment example
2
2
  //
3
3
  // `plainscript build` and `plainscript run` detect express from `web app` and install it
4
- // when it is missing. `plainscript start` builds src/app.pln by default.
4
+ // when it is missing. `plainscript start` builds src/app.ps by default.
5
5
 
6
6
  web app
7
7
 
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — Sending email
2
2
  //
3
- // Run with: MAIL_PASS=secret plainscript run examples/email-send.pln
3
+ // Run with: MAIL_PASS=secret plainscript run examples/email-send.ps
4
4
  //
5
5
  // Configure the outgoing transport once, then send as many mails as you
6
6
  // like. Credentials come from the environment — never hardcode them.
@@ -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)
@@ -0,0 +1,39 @@
1
+ // PlainScript v1.0.0-latest — File uploads
2
+ //
3
+ // Run with: plainscript run examples/file-uploads.ps
4
+ // Then try:
5
+ // curl -F photo=@some-image.png http://localhost:3000/upload
6
+ // curl -F doc=@notes.txt http://localhost:3000/upload-many
7
+ //
8
+ // Uploaded files are kept in memory (no folder) so nothing touches the disk.
9
+ // A file over 5 MB is rejected with HTTP 413 and a non-image with HTTP 415.
10
+
11
+ web app
12
+
13
+ accept uploads limit "5 MB" allow ["image/png", "image/jpeg", "text/plain"]
14
+
15
+ route post "/upload"
16
+ remember file as upload("file")
17
+ if file is not empty
18
+ reply json
19
+ name is name of file
20
+ type is type of file
21
+ size is size of file
22
+ done
23
+ otherwise
24
+ reply json
25
+ error is "no file under the 'file' field"
26
+ done
27
+ done
28
+ done
29
+
30
+ route post "/upload-many"
31
+ remember files as uploads("docs")
32
+ gather each file in files giving name of file
33
+ reply json
34
+ received is length(files)
35
+ names is files
36
+ done
37
+ done
38
+
39
+ start 3000
@@ -0,0 +1,47 @@
1
+ // PlainScript v1.0.0-latest — File I/O, YAML and environment configuration
2
+ //
3
+ // Run with: plainscript run examples/files-and-config.ps
4
+ //
5
+ // Writes and reads files, walks a folder, round-trips YAML and applies a
6
+ // .env file. Everything is deterministic and dependency-free.
7
+
8
+ makeFolder("example-output")
9
+ writeFile("example-output/greeting.txt", "Hello, files!")
10
+ writeLine("example-output/log.txt", "first line")
11
+ appendLine("example-output/log.txt", "second line")
12
+
13
+ show readFile("example-output/greeting.txt")
14
+ show readFile("example-output/log.txt")
15
+ show fileExists("example-output/greeting.txt")
16
+ show fileSize("example-output/greeting.txt")
17
+ show fileType("example-output") // directory
18
+ show lastModified("example-output/greeting.txt")
19
+
20
+ show listFolder("example-output")
21
+ show walkFolder("example-output")
22
+
23
+ remember settings as
24
+ app is "plainscript"
25
+ limits is { requests: 100, window: "hour" }
26
+ done
27
+
28
+ remember encoded as yamlEncode(settings)
29
+ show encoded
30
+
31
+ remember parsed as yamlDecode(encoded)
32
+ show app of parsed
33
+ remember limits as limits of parsed
34
+ show requests of limits
35
+
36
+ load env file ".env"
37
+ show env("APP_ENV")
38
+
39
+ // JSON round-trip stays convenient too
40
+ remember backup as jsonEncode(settings)
41
+ show jsonDecode(backup)
42
+
43
+ // Clean up after ourselves
44
+ deleteFile("example-output/greeting.txt")
45
+ deleteFile("example-output/log.txt")
46
+ deleteFolder("example-output")
47
+ show "cleanup done"
@@ -0,0 +1,44 @@
1
+ // PlainScript v1.0.0-latest — HTTP client: every method, headers and timeouts
2
+ //
3
+ // Run with: plainscript run examples/http-client.ps
4
+ //
5
+ // Uses the public JSONPlaceholder API. Every call returns a record with
6
+ // ok / status / headers / data; JSON bodies are parsed automatically.
7
+
8
+ // GET with an explicit timeout
9
+ remember users as get "https://jsonplaceholder.typicode.com/users" timeout 8000
10
+ show "GET users -> " + text(status of users) + ", count " + text(length(data of users))
11
+
12
+ // POST an inline object, sent as JSON
13
+ remember created as post "https://jsonplaceholder.typicode.com/posts" with {
14
+ title: "Hello from PlainScript",
15
+ userId: 1
16
+ }
17
+ show "POST -> status " + text(status of created)
18
+ if ok of created is true
19
+ show "new post id " + text(id of data of created)
20
+ done
21
+
22
+ // PUT replaces the whole resource
23
+ remember replaced as put "https://jsonplaceholder.typicode.com/posts/1" with {
24
+ title: "Updated",
25
+ body: "new body",
26
+ userId: 1
27
+ }
28
+ show "PUT -> status " + text(status of replaced)
29
+
30
+ // PATCH merges into the resource
31
+ remember patched as patch "https://jsonplaceholder.typicode.com/posts/1" with {
32
+ title: "Patched title"
33
+ }
34
+ show "PATCH -> status " + text(status of patched)
35
+
36
+ // DELETE
37
+ remember removed as delete "https://jsonplaceholder.typicode.com/posts/1"
38
+ show "DELETE -> ok " + text(ok of removed)
39
+
40
+ // Custom headers and error surfacing
41
+ remember guarded as get "https://api.example.com/private" headers {
42
+ Authorization: "Bearer test"
43
+ } timeout 3000
44
+ show "guard called? " + text(ok of guarded) + " (status " + text(status of guarded) + ")"
@@ -0,0 +1,16 @@
1
+ // PlainScript v1.0.0-latest — Importing your own modules
2
+ //
3
+ // Run with: plainscript run examples/modules/app.ps
4
+ //
5
+ // Files are compiled in dependency order (deepest first), so the helpers in
6
+ // math.ps are visible here before app.ps runs.
7
+
8
+ import "./math.ps"
9
+
10
+ show PI // 3.14
11
+ show double(21) // 42
12
+ show square(9) // 81
13
+ show circumference(10) // 62.8
14
+
15
+ remember radius as 2.5
16
+ show "circle area: " + text(square(radius) * PI)
@@ -0,0 +1,20 @@
1
+ // PlainScript v1.0.0-latest — reusable module, imported by app.ps
2
+
3
+ remember PI as 3.14
4
+
5
+ make double(n)
6
+ give n * 2
7
+ done
8
+
9
+ make square(n)
10
+ give n * n
11
+ done
12
+
13
+ make circumference(radius)
14
+ give 2 * PI * radius
15
+ done
16
+
17
+ export PI
18
+ export double
19
+ export square
20
+ export circumference
@@ -0,0 +1,43 @@
1
+ // PlainScript v1.0.0-latest — Record kinds, generators and the test DSL
2
+ //
3
+ // Run with: plainscript run examples/record-kinds.ps
4
+ //
5
+ // Defines a schema, builds instances, composes records, streams values from
6
+ // generators, and verifies behaviour with the built-in test runner.
7
+
8
+ define a kind called "Book" with
9
+ title is ""
10
+ pages is 0
11
+ rating is 0
12
+ done
13
+
14
+ remember fav as create a Book with title "IOPL in Action" and pages 240
15
+ fav.rating becomes 4.5
16
+
17
+ show title of fav
18
+ show pages of fav
19
+ show rating of fav
20
+
21
+ remember extended as merge(fav, { author: "Ada" })
22
+ show author of extended
23
+ show fieldsOf(extended)
24
+
25
+ test "book schema"
26
+ check title of fav equals "IOPL in Action"
27
+ check rating of fav equals 4.5
28
+ check hasField(fav, "author") equals false
29
+ done
30
+
31
+ test "generator"
32
+ remember ids as spread of range(1, 4)
33
+ check length(ids) equals 3
34
+ check sum(ids) equals 6
35
+ done
36
+
37
+ make makeTitles(catalog)
38
+ for each book in catalog
39
+ yield title of book
40
+ done
41
+ done
42
+
43
+ show spread of makeTitles([fav, extended])
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — A real REST API
2
2
  //
3
- // Run with: plainscript run examples/rest-api.pln
3
+ // Run with: plainscript run examples/rest-api.ps
4
4
  // Try: curl http://localhost:3000/api/users
5
5
  //
6
6
  // Demonstrates method routes, route groups, CORS, request validation,
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — Scheduled and recurring tasks
2
2
  //
3
- // Run with: plainscript run examples/scheduled-tasks.pln
3
+ // Run with: plainscript run examples/scheduled-tasks.ps
4
4
  //
5
5
  // "every" covers simple intervals; "schedule" accepts any standard cron
6
6
  // expression (powered by croner).
@@ -0,0 +1,34 @@
1
+ // PlainScript v1.0.0-latest — Functional transformations
2
+ //
3
+ // Run with: plainscript run examples/search-and-filter.ps
4
+ //
5
+ // gather / filter / total map, filter and reduce in place; match routes a
6
+ // value to behaviour.
7
+
8
+ remember scores as [70, 45, 92, 38, 60]
9
+
10
+ gather each score in scores giving score + 5
11
+ show scores // [ 75, 50, 97, 43, 65 ]
12
+
13
+ filter each score in scores when score is at least 60
14
+ show scores // [ 75, 97, 65 ]
15
+
16
+ remember prices as [19.99, 4.99, 29.99]
17
+ total each price in prices giving price
18
+ show prices // 54.97
19
+
20
+ // Pattern matching
21
+ remember day as "wed"
22
+
23
+ match day against
24
+ "mon" -> show "Start of the week"
25
+ "wed" -> show "Middle of the week"
26
+ "fri" -> show "Almost there"
27
+ otherwise -> show "Another day"
28
+ done
29
+
30
+ // Regex matching extracts a group into a variable
31
+ match pattern "^([0-9]+)$" in "2026" as digits
32
+ if digits is not empty
33
+ show "matched digits: " + first of digits
34
+ done
@@ -0,0 +1,54 @@
1
+ // PlainScript v1.0.0-latest — Sessions, cookies and rate limiting
2
+ //
3
+ // Run with: plainscript run examples/sessions-and-cookies.ps
4
+ // Then try:
5
+ // curl -c cookies.txt -b cookies.txt http://localhost:3000/login
6
+ // curl -c cookies.txt -b cookies.txt http://localhost:3000/profile
7
+ // curl -c cookies.txt -b cookies.txt http://localhost:3000/logout
8
+ //
9
+ // The app shows login/logout flow backed by signed sessions, preference
10
+ // cookies, and a per-IP rate limit.
11
+
12
+ web app
13
+
14
+ limit requests to 100 per minute
15
+ enable sessions "a-long-random-secret-minimum"
16
+
17
+ allow cors
18
+
19
+ route get "/login"
20
+ user of session of request becomes "ada"
21
+ set cookie "theme" to "dark" expires in 7 days
22
+ reply json
23
+ welcome is true
24
+ who is user of session of request
25
+ done
26
+ done
27
+
28
+ route get "/profile"
29
+ remember who as user of session of request
30
+ if who is empty
31
+ status 401
32
+ reply "Please log in first via /login"
33
+ otherwise
34
+ reply json
35
+ user is who
36
+ theme is cookie("theme")
37
+ done
38
+ done
39
+ done
40
+
41
+ route post "/logout"
42
+ destroy session
43
+ clear cookie "theme"
44
+ reply "Logged out. Goodbye!"
45
+ done
46
+
47
+ when nothing matches
48
+ status 404
49
+ reply json
50
+ error is "no such road"
51
+ done
52
+ done
53
+
54
+ start 3000
@@ -1,6 +1,6 @@
1
1
  // PlainScript v2.1 — WebSocket chat server
2
2
  //
3
- // Run with: plainscript run examples/websocket-server.pln
3
+ // Run with: plainscript run examples/websocket-server.ps
4
4
  // Then connect any ws client to ws://localhost:8080 and start typing.
5
5
  // Every message a client sends is echoed back to it and broadcast to
6
6
  // everyone else.
package/package.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "name": "plainscript-lang",
3
- "version": "0.1.7",
3
+ "version": "1.0.0-latest",
4
4
  "description": "PlainScript — an Intent-Oriented Programming Language. When even a simple sentence can be code.",
5
5
  "main": "compiler/cli.js",
6
6
  "bin": {
7
7
  "plainscript": "./compiler/cli.js"
8
8
  },
9
9
  "scripts": {
10
- "test": "node tests/compiler.test.js && node tests/build.test.js && node tests/telegram.test.js && node tests/ocr.test.js && node tests/backend.test.js && node tests/runtime.test.js && node tests/acceptance.test.js && node tests/whatsapp.test.js"
10
+ "test": "node tests/compiler.test.js && node tests/build.test.js && node tests/telegram.test.js && node tests/ocr.test.js && node tests/backend.test.js && node tests/runtime.test.js && node tests/acceptance.test.js && node tests/whatsapp.test.js && node tests/audit.test.js && node tests/compat/language.test.js && node tests/compat/node.test.js && node tests/compat/binary.test.js && node tests/compat/errors.test.js && node tests/compat/async.test.js && node tests/compat/modules.test.js && node tests/compat/npm.test.js && node tests/compat/web.test.js && node tests/compat/real-world.test.js"
11
11
  },
12
12
  "files": [
13
13
  "compiler",