plainscript-lang 1.0.363 → 1.1.1

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.
@@ -4,7 +4,7 @@ This document is the single source of truth for the PlainScript language
4
4
  surface. Compiler behavior (`compiler/lexer.js`, `compiler/parser.js`,
5
5
  `compiler/generator.js`) overrides any prose in this or other docs.
6
6
 
7
- Version: 1.0.363
7
+ Version: 1.1.1
8
8
 
9
9
  ---
10
10
 
@@ -62,6 +62,14 @@ Line 1, Column 10: Expected a variable name after "remember".
62
62
  Pick a different name (see docs/PLAINSCRIPT-GRAMMAR.md).
63
63
  ```
64
64
 
65
+ Reserved words may be used deliberately by enclosing the word in backticks. The
66
+ escaped form is an identifier, not a template string:
67
+
68
+ ```plainscript
69
+ remember `now` as 1
70
+ show `now`
71
+ ```
72
+
65
73
  ### Operators
66
74
 
67
75
  | Token | Meaning |
@@ -74,6 +82,11 @@ Pick a different name (see docs/PLAINSCRIPT-GRAMMAR.md).
74
82
  | `...` | spread |
75
83
  | `(` `)` `[` `]` `{` `}` `,` `:` | grouping, literals, comma, object colon |
76
84
 
85
+ Natural-language comparisons normalize to the same binary operators. Supported
86
+ forms include `is greater than` / `is more than` (`>`), `is less than` / `is
87
+ fewer than` (`<`), `is greater than or equal to` / `is more than or equal to`
88
+ (`>=`), `is less than or equal to` (`<=`), and `is at least` / `is at most`.
89
+
77
90
  ### Assignment operators
78
91
 
79
92
  | Operator | Meaning |
@@ -151,6 +164,14 @@ let y be 6
151
164
  remember z as 7
152
165
  ```
153
166
 
167
+ Mutable bindings may carry a recursive collection or record contract between
168
+ the name and initializer:
169
+
170
+ ```text
171
+ let users as list of User is [{ id: 1, name: "Ada" }]
172
+ let usersById as dictionary of User is { first: { id: 1, name: "Ada" } }
173
+ ```
174
+
154
175
  Reassignment (word-formed; PlainScript has no `=` symbol):
155
176
 
156
177
  ```plainscript
@@ -206,9 +227,31 @@ make greet(user as User)
206
227
  done
207
228
  ```
208
229
 
209
- The generated function validates `user` before entering its body. This slice
210
- provides runtime contracts; static inference and compile-time field checking
211
- are not yet implemented.
230
+ The generated function validates `user` before entering its body. The static
231
+ checker also validates literal arguments, typed bindings, return contracts,
232
+ collection elements, nested fields, and known member access. It remains
233
+ conservative for expressions whose types are unknown.
234
+
235
+ ### Async values and Promise contracts
236
+
237
+ Calls to asynchronous functions are tracked as `Promise of T` values. A
238
+ function body containing `wait for` is therefore asynchronous even when its
239
+ resolved return contract is written as `returns text`. Use `wait for` when a
240
+ resolved value is required:
241
+
242
+ ```plainscript
243
+ make verify() returns text
244
+ wait for sleep(10)
245
+ give "verified"
246
+ done
247
+
248
+ remember result as wait for verify()
249
+ ```
250
+
251
+ The checker reports `PLN-ASYNC-MISSING-AWAIT` when a Promise is assigned,
252
+ passed to a typed synchronous parameter, or returned where a resolved value is
253
+ required. Explicit raw contracts may use `returns Promise of text`; the body
254
+ is still checked against the resolved `text` value.
212
255
 
213
256
  ## 5. Statements and blocks
214
257
 
@@ -228,18 +271,73 @@ equivalent; `end` maps to the same terminator as `done` in the lexer.
228
271
  | `switch <value> against` | `->` cases | `done` |
229
272
  | `try` | body with `recover as <err>` / `finally` clauses | `done` |
230
273
  | `web app` / `route <method> "<path>"` / `when someone visits "<path>"` / `listen on <port>` blocks | body | `done` |
231
- | `database "file.db"` SQL blocks (`query`, `insert`, `update`, `delete`, `execute`) | raw SQL | `done` (or `end`) |
274
+ | `database "file.db"` SQL blocks (`query`, `insert`, `update`, `delete`, `execute`) | raw SQL with `{name}` bound parameters | `done` (or `end`) |
232
275
  | `run in parallel` | concurrent statements (each statement's value is awaited and resolved with `Promise.all`, collected in body order) | `done as <name>` |
233
276
  | `when "<event>" happens` | body | `done` |
234
277
  | `every <interval>` / `schedule "<cron>"` | body | `done` |
235
278
  | `websocket server`, `bot`, `whatsapp bot`, `mail transport` | body | `done` |
236
279
  | `stream "<file>" as <line>` | body | `done` |
237
- | `test "<name>"` | `check` / `equals` / `raises` | `done` |
280
+ | `test "<name>"` | `check` / `equals` / `raises` / `has field` | `done` |
238
281
 
239
282
  A `make` body that contains `yield` compiles to a generator function
240
- (`function*`). SQL block text is passed through verbatim to SQLite.
283
+ (`function*`). SQL block text is passed through to the selected database driver,
284
+ except for safe PlainScript parameter placeholders.
285
+
286
+ Native tests can assert the shape of JSON-like records with
287
+ `check data of response has field "status"`. The assertion checks for an own
288
+ property and fails when the value is null or the field is absent.
289
+
290
+ ### SQL interpolation
291
+
292
+ SQL placeholders use a PlainScript value expression inside braces. The compiler
293
+ replaces `{name}` or `{imageHash(image)}` with a driver parameter marker and
294
+ passes the resulting value separately to the prepared statement; values are
295
+ never concatenated into SQL text.
296
+
297
+ ```plainscript
298
+ remember email as request.body.email
299
+ remember rows as query
300
+ SELECT receipt_id FROM receipts WHERE email = {email}
301
+ done
302
+ ```
303
+
304
+ Expressions are parsed as PlainScript before compilation. Malformed or raw
305
+ statement text is rejected at compile time; for example, this is invalid:
306
+
307
+ ```text
308
+ {imageHash(image); DROP TABLE receipts}
309
+ ```
310
+
311
+ For complex expressions, binding first is still recommended because it makes
312
+ the source and inferred value easier to read:
313
+
314
+ ```plainscript
315
+ remember receiptHash as imageHash(image)
316
+ remember rows as query
317
+ SELECT receipt_id FROM receipts WHERE hash = {receiptHash}
318
+ done
319
+ ```
320
+
321
+ The same binding rule applies to `query`, `insert`, `update`, `delete`, and
322
+ `execute`. SQL injection attempts supplied as values remain data because the
323
+ prepared statement receives them as parameters.
324
+
325
+ ## 6. Module and npm imports
326
+
327
+ Selective imports may rename an exported symbol with `as`:
328
+
329
+ ```plainscript
330
+ import { createHash as hash, randomUUID } from "crypto"
331
+ ```
332
+
333
+ For npm packages, the compiler emits a CommonJS `require` and destructures the
334
+ requested exports. The example creates local bindings named `hash` and
335
+ `randomUUID`, while the package exports remain `createHash` and `randomUUID`.
336
+ The same syntax works for local `.pln` modules; the bundler creates the alias
337
+ after resolving the dependency. A plain `import { name } from ...` keeps the
338
+ exported name unchanged.
241
339
 
242
- ## 6. Expressions
340
+ ## 7. Expressions
243
341
 
244
342
  Recursive-descent parsing with precedence. Member access uses `of`:
245
343
 
@@ -134,6 +134,26 @@ done
134
134
  show add(2, 3)
135
135
  ```
136
136
 
137
+ Functions and intents may declare a return contract with `returns` (or the
138
+ equivalent `returning`) after the parameter list. The static checker validates
139
+ each `give`/`return` value and reports a missing return when a declared
140
+ function has no return value:
141
+
142
+ ```plainscript
143
+ make add(a as number, b as number) returns number
144
+ give a + b
145
+ done
146
+
147
+ intend greeting(name as text) returns text
148
+ give `Hello, ${name}`
149
+ done
150
+ ```
151
+
152
+ Return contracts use the same primitive, optional, list, dictionary, union, and
153
+ declared-record types as parameter contracts. Untyped functions remain valid,
154
+ and a function call with a return contract contributes that type to subsequent
155
+ static checking.
156
+
137
157
  Function parameters can have simple defaults:
138
158
 
139
159
  ```plainscript
@@ -211,6 +231,19 @@ The checker powers the stdio language server started with `plainscript-lsp`.
211
231
  The server publishes these diagnostics and provides hover, completion,
212
232
  definition, and document-symbol responses using standard LSP JSON-RPC framing.
213
233
 
234
+ Mutable bindings can declare recursive collection contracts with `as` before
235
+ the initializer:
236
+
237
+ ```text
238
+ let users as list of User is [{ id: 1, name: "Ada" }]
239
+ let usersById as dictionary of User is { first: { id: 1, name: "Ada" } }
240
+ ```
241
+
242
+ The checker validates every list element and dictionary value, including nested
243
+ record fields. Optional and union element types use the same rules as function
244
+ contracts. A known `list of T` or `dictionary of T` contributes `T` to indexed
245
+ access, and null checks narrow optional values within the checked branch.
246
+
214
247
  ## Control flow
215
248
 
216
249
  ```plainscript
@@ -0,0 +1,220 @@
1
+ # PlainScript v1.1.0: Typed Collections Design
2
+
3
+ **Status:** Design proposal
4
+ **Milestone:** v1.1.0 · Language Depth
5
+ **Predecessor:** Function return contracts
6
+
7
+ ## Purpose
8
+
9
+ Typed collections are the next increment after return contracts. Return contracts
10
+ make a function's result visible to the checker. Typed collections make the
11
+ shape of that result useful when it contains repeated or nested values.
12
+
13
+ The feature must solve one narrow problem well: when PlainScript has a declared
14
+ collection type and a collection literal is available, the checker must verify
15
+ every element against the declared element type. This includes nested lists,
16
+ dictionaries, and declared record contracts. The implementation must not become
17
+ a general-purpose whole-program inference system in this branch.
18
+
19
+ ## Proposed surface syntax
20
+
21
+ PlainScript already uses `list of T` and `dictionary of T` in record fields and
22
+ function parameter contracts. The same type expressions will be valid for local
23
+ mutable bindings by placing the annotation between the variable name and its
24
+ initializer:
25
+
26
+ ```text
27
+ type User
28
+ id is number
29
+ name is text
30
+ done
31
+
32
+ let users as list of User is [
33
+ { id: 1, name: "David" },
34
+ { id: 2, name: "Samuel" }
35
+ ]
36
+
37
+ let usersById as dictionary of User is {
38
+ first: { id: 1, name: "David" },
39
+ second: { id: 2, name: "Samuel" }
40
+ }
41
+ ```
42
+
43
+ The existing `let name is value` form remains unchanged. The existing
44
+ `remember name as value` form also remains unchanged in this milestone because
45
+ `as` is already its initializer separator. Typed immutable bindings are not
46
+ needed to establish collection checking and can be designed separately without
47
+ making `remember` ambiguous.
48
+
49
+ The feature does not introduce a new collection literal syntax. Square brackets
50
+ remain list literals, and braces remain object or dictionary literals according
51
+ to their existing parsing context.
52
+
53
+ ## Type model
54
+
55
+ The parser will continue to produce the existing recursive type-specification
56
+ shape:
57
+
58
+ ```text
59
+ name -> { kind: "name", name }
60
+ optional T -> { kind: "optional", value: T }
61
+ list of T -> { kind: "list", value: T }
62
+ dictionary of T -> { kind: "dictionary", value: T }
63
+ T or U -> { kind: "union", values: [T, U] }
64
+ ```
65
+
66
+ The checker should treat these specifications as recursive values rather than
67
+ flattening collection types to the single string `list` or `dictionary`. A
68
+ small internal `TypeRef` normalization layer may be introduced if the current
69
+ string-based inference prevents recursive comparisons. That refactoring belongs
70
+ inside the checker and must preserve existing diagnostic codes and messages for
71
+ primitive contracts.
72
+
73
+ A declared record name remains a named type. Its value is valid only when the
74
+ checker can verify an object literal against the corresponding `type`
75
+ declaration, or when the value's known type is that declared record. A plain
76
+ `object` remains intentionally less specific and accepts any object value.
77
+
78
+ ## Static checking rules
79
+
80
+ When a typed binding has an initializer, the checker performs these checks:
81
+
82
+ 1. `list of T` requires a list literal or a known list value. Every element is
83
+ checked recursively against `T`.
84
+ 2. `dictionary of T` requires an object or known dictionary value. Every value is
85
+ checked recursively against `T`; dictionary keys remain unconstrained text
86
+ keys.
87
+ 3. `optional T` accepts a missing value or `null`, and otherwise checks the
88
+ value against `T`.
89
+ 4. `T or U` accepts a value matching at least one branch. Literal diagnostics
90
+ should report the complete expected union when no branch matches.
91
+ 5. A named record type checks required fields, optional fields, unknown fields,
92
+ and each field value recursively. If a field itself has type `list of User`,
93
+ every list element is checked as a `User` record.
94
+ 6. A literal with an expression-valued element is not rejected merely because
95
+ the expression is not yet inferable. The checker reports a mismatch only
96
+ when the expression has a known incompatible type. Expression propagation is
97
+ the following v1.1.0 milestone.
98
+
99
+ For example, this program must produce a field diagnostic for the second list
100
+ element:
101
+
102
+ ```text
103
+ type User
104
+ id is number
105
+ name is text
106
+ done
107
+
108
+ make loadUsers() returns list of User
109
+ give [
110
+ { id: 1, name: "David" },
111
+ { id: "wrong", name: "Samuel" }
112
+ ]
113
+ done
114
+ ```
115
+
116
+ The diagnostic should identify the collection context and element path, such as
117
+ `Return value element 2 field "id" expects number, received text.` The exact
118
+ wording may evolve, but the diagnostic must retain the existing
119
+ `PLN-TYPE-FIELD` or `PLN-TYPE-RETURN` family and point to the collection's source
120
+ range until element-level source spans are available.
121
+
122
+ ## Contract propagation within this milestone
123
+
124
+ The checker should record a typed local binding's declared type in its
125
+ environment. A call to a function returning `list of User` or `dictionary of
126
+ User` should likewise retain that recursive return type rather than reducing it
127
+ to `list` or `dictionary`.
128
+
129
+ This milestone only requires enough propagation to validate collection values at
130
+ contract boundaries and to validate indexed access when the type is already
131
+ known. Indexing a known `list of T` may produce `T`, and reading a known
132
+ `dictionary of T` may produce `T`. Rich propagation through arbitrary operators,
133
+ branches, aliases, and callbacks belongs to the next expression-typing branch.
134
+
135
+ ## Runtime behavior
136
+
137
+ Typed collections do not add runtime behavior. Existing generated JavaScript
138
+ already represents lists as arrays and dictionaries as objects. Runtime record
139
+ validation remains the responsibility of the existing function-entry contract
140
+ checks. The new work is static validation of literal collection contents and
141
+ preservation of recursive type information in the checker.
142
+
143
+ If a typed collection is passed to a function at runtime, the generated program
144
+ must continue to use the same contract validation path as an equivalent record
145
+ field. The design must not introduce a second incompatible runtime validator.
146
+
147
+ ## Diagnostics
148
+
149
+ The implementation should add only diagnostics needed to explain collection
150
+ mismatches:
151
+
152
+ | Code | Meaning |
153
+ | --- | --- |
154
+ | `PLN-TYPE-COLLECTION` | A value is not a list or dictionary where the contract requires one. |
155
+ | `PLN-TYPE-ELEMENT` | A list element or dictionary value does not match its element type. |
156
+ | `PLN-TYPE-FIELD` | A nested declared record has a missing, invalid, or unknown field. |
157
+ | `PLN-TYPE-ARG` | A function argument does not match a collection parameter contract. |
158
+ | `PLN-TYPE-RETURN` | A return value does not match a collection return contract. |
159
+
160
+ Existing field and argument diagnostics should be reused where they already
161
+ explain the failure. New codes are justified only when they distinguish the
162
+ collection boundary from the nested value. Diagnostics should include the
163
+ expected recursive type using the existing `typeName` rendering, for example
164
+ `list of User` or `dictionary of optional text`.
165
+
166
+ ## Parser and checker changes
167
+
168
+ The implementation branch should make the following bounded changes:
169
+
170
+ - Extend `let` declarations to accept `let name as Type is value` and preserve
171
+ the parsed type on the `RememberStatement` node as `typeAnnotation`.
172
+ - Validate the annotation through the same unknown-type path used by parameter
173
+ and return contracts.
174
+ - Replace literal-only contract validation with a recursive validator that can
175
+ descend through `ArrayLiteral`, `InlineObjectLiteral`, and `ObjectLiteral`
176
+ nodes.
177
+ - Store the declared recursive type on the local checker environment.
178
+ - Preserve recursive return types from function calls.
179
+ - Add focused tests for lists, dictionaries, nested records, unions, optional
180
+ elements, invalid element values, and unknown nested contract names.
181
+ - Update the language specification and README examples only after the grammar
182
+ and checker tests pass.
183
+
184
+ No generator changes are expected unless the existing runtime contract emitter
185
+ cannot consume recursive collection specifications. No LSP feature work belongs
186
+ in this branch.
187
+
188
+ ## Explicit non-goals
189
+
190
+ This branch will not implement flow-sensitive narrowing, full operator typing,
191
+ collection mutation checking, generic type parameters, tuple types, inferred
192
+ annotations for every variable, cross-file type resolution, or advanced LSP
193
+ features. It will not attempt to prove that every possible runtime collection
194
+ value is valid. Static guarantees apply to values and expressions whose types
195
+ are known at the checking point.
196
+
197
+ ## Acceptance criteria
198
+
199
+ The branch is ready for review when all of the following hold:
200
+
201
+ - A valid `list of User` literal passes static checking.
202
+ - An invalid nested record inside a list produces a deterministic diagnostic.
203
+ - A valid `dictionary of User` literal passes static checking.
204
+ - An invalid dictionary value is reported without masking unrelated diagnostics.
205
+ - Nested lists and dictionaries recurse through at least two levels.
206
+ - Optional and union element types behave consistently with existing contracts.
207
+ - A function returning `list of User` preserves that return type for a caller.
208
+ - Existing untyped programs and existing parameter contracts remain unchanged.
209
+ - Focused type tests, LSP tests, documentation checks, and the full test suite
210
+ pass before the branch is opened.
211
+
212
+ ## References
213
+
214
+ [1]: https://github.com/ayoistooslick/plainscript/blob/main/docs/PLAINSCRIPT-SPEC.md "PlainScript language specification"
215
+ [2]: https://github.com/ayoistooslick/plainscript/blob/main/compiler/type-checker.js "PlainScript static type checker"
216
+ [3]: https://github.com/ayoistooslick/plainscript/blob/main/compiler/parser.js "PlainScript parser"
217
+ [4]: https://github.com/ayoistooslick/plainscript/blob/main/tests/types.test.js "PlainScript type tests"
218
+
219
+ The proposal is grounded in the existing contract syntax and checker behavior
220
+ specified in [1] and implemented in [2]–[4].
@@ -0,0 +1,21 @@
1
+ type User
2
+ id is number
3
+ name is text
4
+ done
5
+
6
+ let users as list of User is [
7
+ { id: 1, name: "Ada" },
8
+ { id: 2, name: "Grace" }
9
+ ]
10
+
11
+ let usersById as dictionary of User is {
12
+ first: { id: 1, name: "Ada" },
13
+ second: { id: 2, name: "Grace" }
14
+ }
15
+
16
+ make firstUser() returns User
17
+ give users[0]
18
+ done
19
+
20
+ show firstUser().name
21
+ show usersById.first.name
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "plainscript-lang",
3
- "version": "1.0.363",
3
+ "version": "1.1.1",
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": {