plainscript-lang 1.1.0 → 1.1.5

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.
@@ -53,13 +53,44 @@ const TIME_UNITS = {
53
53
 
54
54
  // v2.1.0 - split raw SQL into placeholder-free text and ordered parameter
55
55
  // names. "{name}" marks a bound parameter; the generator renders "?" for
56
- // SQLite or "$1…" for PostgreSQL.
56
+ // SQLite or "$1…" for PostgreSQL. A value expression is also accepted after
57
+ // parsing it as PlainScript, but its result remains a bound parameter and is
58
+ // never inserted into the SQL text.
57
59
  function extractSqlParams(rawSql) {
58
60
  const params = [];
59
- const sql = String(rawSql).replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
61
+ const source = String(rawSql);
62
+ const sql = source.replace(/\{([^{}]*)\}/g, (_match, content) => {
63
+ const name = String(content).trim();
64
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
65
+ if (/[;{}]/.test(name)) {
66
+ throw new Error(
67
+ 'SQL placeholders must contain a PlainScript value expression, not raw statement text.\n\n' +
68
+ `Found "{${content}}". Bind the expression before the query, for example:\n` +
69
+ ' remember receiptHash as imageHash(image)\n' +
70
+ ' query\n SELECT * FROM receipts WHERE hash = {receiptHash}\n done'
71
+ );
72
+ }
73
+ try {
74
+ const expressionAst = parse(tokenize(`remember __sqlParameter as ${name}`));
75
+ if (!expressionAst || expressionAst.body.length !== 1 || expressionAst.body[0].type !== 'RememberStatement') throw new Error('invalid expression');
76
+ } catch (_) {
77
+ throw new Error(
78
+ 'SQL placeholders must contain a valid PlainScript value expression.\n\n' +
79
+ `Found "{${content}}". Bind the expression before the query, for example:\n` +
80
+ ' remember receiptHash as imageHash(image)\n' +
81
+ ' query\n SELECT * FROM receipts WHERE hash = {receiptHash}\n done'
82
+ );
83
+ }
84
+ }
60
85
  params.push(name);
61
86
  return '?';
62
87
  });
88
+ if (/[{}]/.test(sql)) {
89
+ throw new Error(
90
+ 'SQL interpolation contains an unmatched "{" or "}".\n\n' +
91
+ 'Use {name} for a bound PlainScript value; SQL text must not contain raw interpolated expressions.'
92
+ );
93
+ }
63
94
  return { sql, params };
64
95
  }
65
96
 
@@ -145,9 +176,13 @@ function parse(tokens) {
145
176
  let pos = 0;
146
177
  let _inRepeatCount = false;
147
178
  const declaredTypeNames = new Set(['any', 'number', 'text', 'boolean', 'null', 'object']);
179
+ let activeGenericNames = new Set();
148
180
  function peek() { return tokens[pos]; }
149
181
  function peekAt(offset) { return tokens[pos + offset] || { type: TOKEN.EOF }; }
150
182
  function advance() { return tokens[pos++]; }
183
+ function isIdentifierToken(token) {
184
+ return token && (token.type === TOKEN.IDENTIFIER || token.type === TOKEN.ESCAPED_IDENTIFIER);
185
+ }
151
186
  // v1.0.363 - at a block terminator? A done/together followed by "of" is a
152
187
  // FIELD read ("done of item" - the README todo example), so it never closes a
153
188
  // block. Every statement-bearing body loop must ask this instead of comparing
@@ -529,15 +564,31 @@ function parse(tokens) {
529
564
  return { type: 'BinaryCondition', left, op: '===', right };
530
565
  }
531
566
 
532
- // is more than <expr>
567
+ // is more than [or equal to] <expr>
533
568
  if (peek().type === TOKEN.IDENTIFIER && peek().value === 'more' &&
534
569
  (peekAt(1).type === TOKEN.THAN || (peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'than'))) {
535
570
  advance(); // more
536
571
  advance(); // than
572
+ if (peek().type === TOKEN.OR && peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'equal') {
573
+ advance();
574
+ advance();
575
+ if (peek().type === TOKEN.TO || (peek().type === TOKEN.IDENTIFIER && peek().value === 'to')) advance();
576
+ const right = parseBooleanAtom();
577
+ return { type: 'BinaryCondition', left, op: '>=', right };
578
+ }
537
579
  const right = parseBooleanAtom();
538
580
  return { type: 'BinaryCondition', left, op: '>', right };
539
581
  }
540
582
 
583
+ // is fewer than <expr> (natural-language alias for less than)
584
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'fewer' &&
585
+ (peekAt(1).type === TOKEN.THAN || (peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'than'))) {
586
+ advance();
587
+ advance();
588
+ const right = parseBooleanAtom();
589
+ return { type: 'BinaryCondition', left, op: '<', right };
590
+ }
591
+
541
592
  // is above (alias: >)
542
593
  if (peek().type === TOKEN.ABOVE) {
543
594
  advance();
@@ -1391,7 +1442,7 @@ function parse(tokens) {
1391
1442
  // Allow contextual keywords as variable names in remember declarations
1392
1443
  let nameToken = peek();
1393
1444
  const REMEMBER_KEYWORDS = new Set([TOKEN.BACK, TOKEN.TOTAL, TOKEN.REPLY, TOKEN.RESPOND, TOKEN.SEND_BACK, TOKEN.FILE_KW]);
1394
- if (REMEMBER_KEYWORDS.has(nameToken.type) || isSqlWordIdentifier(nameToken)) {
1445
+ if (isIdentifierToken(nameToken) || REMEMBER_KEYWORDS.has(nameToken.type) || isSqlWordIdentifier(nameToken)) {
1395
1446
  advance();
1396
1447
  target = nameToken.value;
1397
1448
  } else {
@@ -1593,13 +1644,27 @@ function parseAsk() {
1593
1644
  const keyword = isDefine ? 'define' : isFunction ? 'function' : 'make';
1594
1645
  // Allow "load" as a function name (it's also a keyword for "load env file")
1595
1646
  const nameToken = peek();
1596
- if (nameToken.type !== TOKEN.IDENTIFIER && nameToken.type !== TOKEN.LOAD) {
1647
+ if (!isIdentifierToken(nameToken) && nameToken.type !== TOKEN.LOAD) {
1597
1648
  throw new Error(makeError(
1598
1649
  `Expected a function name after "${keyword}".${reservedWordHint(nameToken)}\n\nExample:\n ${keyword} greet()\n show "Hello"\n done`,
1599
1650
  nameToken
1600
1651
  ));
1601
1652
  }
1602
1653
  const name = advance().value;
1654
+ const genericParams = [];
1655
+ if (peek().type === TOKEN.LESS_THAN) {
1656
+ advance();
1657
+ while (peek().type !== TOKEN.GREATER_THAN) {
1658
+ const param = consume(TOKEN.IDENTIFIER, 'Expected a generic type parameter name.');
1659
+ if (genericParams.includes(param.value)) throw new Error(makeError(`Generic parameter "${param.value}" is declared more than once.`, param));
1660
+ genericParams.push(param.value);
1661
+ if (peek().type !== TOKEN.COMMA) break;
1662
+ advance();
1663
+ }
1664
+ consume(TOKEN.GREATER_THAN, 'Expected ">" after generic type parameters.');
1665
+ }
1666
+ const previousGenericNames = activeGenericNames;
1667
+ activeGenericNames = new Set(genericParams);
1603
1668
  consume(TOKEN.LPAREN, `Expected "(" after function name "${name}".`);
1604
1669
  const params = parseParamList();
1605
1670
  consume(TOKEN.RPAREN, 'Expected ")" to close the parameter list.');
@@ -1609,12 +1674,15 @@ function parseAsk() {
1609
1674
  returnType = parseTypeSpec();
1610
1675
  }
1611
1676
  const body = parseBody(`function "${name}"`);
1612
- return { type: 'FunctionDeclaration', name, params, returnType, body };
1677
+ activeGenericNames = previousGenericNames;
1678
+ return { type: 'FunctionDeclaration', name, params, returnType, body, genericParams };
1613
1679
  }
1614
1680
 
1615
1681
  function parseIntentDeclaration() {
1616
1682
  advance(); // intend
1617
- const nameToken = consume(TOKEN.IDENTIFIER, 'Expected an intent name after "intend".');
1683
+ const nameToken = peek();
1684
+ if (!isIdentifierToken(nameToken)) throw new Error(makeError('Expected an intent name after "intend".', nameToken));
1685
+ advance();
1618
1686
  const name = nameToken.value;
1619
1687
  consume(TOKEN.LPAREN, `Expected "(" after intent name "${name}".`);
1620
1688
  const params = parseParamList();
@@ -1638,24 +1706,44 @@ function parseAsk() {
1638
1706
  const primitiveTypeNames = new Set(['any', 'number', 'text', 'boolean', 'null', 'object']);
1639
1707
  function isTypeNameStart(token) {
1640
1708
  return token && token.type === TOKEN.IDENTIFIER &&
1641
- (declaredTypeNames.has(token.value) || primitiveTypeNames.has(token.value) ||
1642
- ['optional', 'list', 'dictionary'].includes(token.value) || /^[A-Z]/.test(token.value));
1709
+ (declaredTypeNames.has(token.value) || activeGenericNames.has(token.value) || primitiveTypeNames.has(token.value) ||
1710
+ ['optional', 'list', 'dictionary', 'map', 'set', 'tuple'].includes(token.value) || /^[A-Z]/.test(token.value));
1643
1711
  }
1644
1712
  function parseTypeAtom() {
1645
1713
  const token = peek();
1714
+ if (token.type === TOKEN.IDENTIFIER && (token.value === 'Promise' || token.value === 'promise')) {
1715
+ advance();
1716
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'of') advance();
1717
+ return { kind: 'promise', value: parseTypeSpec() };
1718
+ }
1646
1719
  if (token.type === TOKEN.IDENTIFIER && token.value === 'optional') {
1647
1720
  advance();
1648
1721
  return { kind: 'optional', value: parseTypeSpec() };
1649
1722
  }
1650
- if (token.type === TOKEN.IDENTIFIER && (token.value === 'list' || token.value === 'dictionary')) {
1723
+ if (token.type === TOKEN.IDENTIFIER && (token.value === 'list' || token.value === 'dictionary' || token.value === 'set')) {
1651
1724
  const kind = advance().value;
1652
1725
  if (peek().type === TOKEN.IDENTIFIER && peek().value === 'of') advance();
1653
1726
  return { kind, value: parseTypeSpec() };
1654
1727
  }
1728
+ if (token.type === TOKEN.IDENTIFIER && token.value === 'map') {
1729
+ advance();
1730
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'of') advance();
1731
+ const key = parseTypeAtom();
1732
+ if (peek().type === TOKEN.TO || peek().type === TOKEN.IDENTIFIER && (peek().value === 'to' || peek().value === 'of')) advance();
1733
+ return { kind: 'map', key, value: parseTypeSpec() };
1734
+ }
1735
+ if (token.type === TOKEN.IDENTIFIER && token.value === 'tuple') {
1736
+ advance();
1737
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'of') advance();
1738
+ const values = [parseTypeAtom()];
1739
+ while (peek().type === TOKEN.COMMA) { advance(); values.push(parseTypeAtom()); }
1740
+ return { kind: 'tuple', values };
1741
+ }
1655
1742
  if (!isTypeNameStart(token) && token.type !== TOKEN.NULL_KW) {
1656
1743
  throw new Error(makeError('Expected a type name (number, text, boolean, object, or a declared type).', token));
1657
1744
  }
1658
1745
  advance();
1746
+ if (activeGenericNames.has(token.value)) return { kind: 'typeParam', name: token.value };
1659
1747
  return { kind: 'name', name: token.value };
1660
1748
  }
1661
1749
  function parseTypeSpec() {
@@ -1675,6 +1763,10 @@ function parseAsk() {
1675
1763
  throw new Error(makeError(`Type "${name}" is already declared.`, nameToken));
1676
1764
  }
1677
1765
  declaredTypeNames.add(name);
1766
+ if (peek().type === TOKEN.IS || peek().type === TOKEN.BE) {
1767
+ advance();
1768
+ return { type: 'TypeAlias', name, target: parseTypeSpec() };
1769
+ }
1678
1770
  const fields = [];
1679
1771
  while (!atBlockEnd()) {
1680
1772
  if (peek().type === TOKEN.EOF) {
@@ -2137,7 +2229,9 @@ function parseAsk() {
2137
2229
  // Rest parameter: ...args
2138
2230
  if (peek().type === TOKEN.SPREAD) {
2139
2231
  advance();
2140
- const name = consume(TOKEN.IDENTIFIER, 'Expected a parameter name after "...".').value;
2232
+ const restToken = peek();
2233
+ if (!isIdentifierToken(restToken)) throw new Error(makeError('Expected a parameter name after "...".', restToken));
2234
+ const name = advance().value;
2141
2235
  return { type: 'RestElement', name };
2142
2236
  }
2143
2237
  // Destructuring: [a, b] or {x, y}
@@ -2166,7 +2260,7 @@ function parseAsk() {
2166
2260
  // identifier names when used as a parameter, mirroring `remember`.
2167
2261
  const PARAM_KEYWORDS = new Set([TOKEN.BACK, TOKEN.REPLY, TOKEN.RESPOND, TOKEN.SEND_BACK, TOKEN.FILE_KW]);
2168
2262
  let name;
2169
- if (PARAM_KEYWORDS.has(peek().type)) {
2263
+ if (isIdentifierToken(peek()) || PARAM_KEYWORDS.has(peek().type)) {
2170
2264
  name = advance().value;
2171
2265
  } else {
2172
2266
  name = consume(TOKEN.IDENTIFIER, 'Expected a parameter name.').value;
@@ -2335,6 +2429,14 @@ function parseAsk() {
2335
2429
  // fold `a contains b` into a comparison here.
2336
2430
  const a = parseNullish();
2337
2431
  const opToken = peek();
2432
+ if (opToken.value === 'has' && peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'field') {
2433
+ advance(); // has
2434
+ advance(); // field
2435
+ const field = consume(TOKEN.STRING,
2436
+ 'Expected a field name string after "has field".\n\nExample:\n check data of response has field "status"'
2437
+ ).value;
2438
+ return { type: 'CheckStatement', a, op: 'has-field', b: { type: 'StringLiteral', value: field } };
2439
+ }
2338
2440
  if (!['equals', 'is', 'contains', 'raises'].includes(opToken.value)) {
2339
2441
  throw new Error(makeError(
2340
2442
  'Expected "equals", "is", "contains" or "raises" after the value in a "check".\n\nExample:\n check score equals 42',
@@ -2476,11 +2578,19 @@ function parseAsk() {
2476
2578
  if (peek().type === TOKEN.LBRACE) {
2477
2579
  advance(); // {
2478
2580
  const names = [];
2581
+ const namedImports = [];
2479
2582
  while (true) {
2480
- names.push(consume(
2583
+ const imported = consume(
2481
2584
  TOKEN.IDENTIFIER,
2482
2585
  'Expected an exported name inside the import braces.\n\nExample:\n import { helper } from "./util.pln"'
2483
- ).value);
2586
+ ).value;
2587
+ let local = imported;
2588
+ if (peek().type === TOKEN.AS) {
2589
+ advance();
2590
+ local = consume(TOKEN.IDENTIFIER, 'Expected a local name after "as" in the import braces.').value;
2591
+ }
2592
+ names.push(imported);
2593
+ namedImports.push({ imported, local });
2484
2594
  if (peek().type === TOKEN.COMMA) { advance(); continue; }
2485
2595
  break;
2486
2596
  }
@@ -2492,7 +2602,7 @@ function parseAsk() {
2492
2602
  TOKEN.STRING,
2493
2603
  'Expected a file path string after the import.\n\nExample:\n import { helper } from "./util.pln"'
2494
2604
  ).value;
2495
- return { type: 'ImportStatement', path: filePath, names };
2605
+ return { type: 'ImportStatement', path: filePath, names, namedImports };
2496
2606
  }
2497
2607
 
2498
2608
  // Form 2: bring all from "path" as math / import all as math from "path" / import * as math from "path"
@@ -4242,7 +4352,7 @@ function parseAsk() {
4242
4352
  advance();
4243
4353
  return { type: 'Identifier', name: token.value };
4244
4354
  }
4245
- if (token.type === TOKEN.IDENTIFIER || IDENTIFIER_KEYWORDS.has(token.type) || isSqlWordIdentifier(token)) {
4355
+ if (isIdentifierToken(token) || IDENTIFIER_KEYWORDS.has(token.type) || isSqlWordIdentifier(token)) {
4246
4356
  if (peekAt(1).type === TOKEN.USES || peekAt(1).type === TOKEN.FILLS) {
4247
4357
  const callee = { type: 'Identifier', name: token.value };
4248
4358
  advance();
@@ -4304,7 +4414,7 @@ function parseAsk() {
4304
4414
  function tokenStartsValue(token) {
4305
4415
  return [
4306
4416
  TOKEN.STRING, TOKEN.TEMPLATE_STRING, TOKEN.NUMBER,
4307
- TOKEN.IDENTIFIER, TOKEN.LBRACKET, TOKEN.LBRACE,
4417
+ TOKEN.IDENTIFIER, TOKEN.ESCAPED_IDENTIFIER, TOKEN.LBRACKET, TOKEN.LBRACE,
4308
4418
  TOKEN.TRUE_KW, TOKEN.FALSE_KW, TOKEN.NULL_KW,
4309
4419
  ].includes(token.type);
4310
4420
  }
@@ -4395,7 +4505,7 @@ function parseAsk() {
4395
4505
  // "done" from the block terminator), plus strings ("with space": 1) and numbers
4396
4506
  // ({ 3: "three" }) for data-shaped objects. A keyword is only accepted as a key when an
4397
4507
  // explicit colon follows, so block-terminator usage of "done" can never be misread here.
4398
- const keyIsWord = keyToken.type === TOKEN.IDENTIFIER || keyToken.type === TOKEN.STRING ||
4508
+ const keyIsWord = keyToken.type === TOKEN.IDENTIFIER || keyToken.type === TOKEN.ESCAPED_IDENTIFIER || keyToken.type === TOKEN.STRING ||
4399
4509
  keyToken.type === TOKEN.NUMBER || keyToken.type === TOKEN.BACK;
4400
4510
  const keyIsColonKeyword = keyToken.type !== TOKEN.IDENTIFIER &&
4401
4511
  typeof keyToken.value === 'string' && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(keyToken.value) &&