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.
- package/README.md +41 -8
- package/compiler/cli.js +127 -18
- package/compiler/generator.js +276 -30
- package/compiler/lexer.js +1 -1
- package/compiler/parser.js +139 -12
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +68 -8
- package/docs/PLINJS_SPEC.md +3 -3
- package/docs/index.html +25 -20
- package/docs/website/script.js +1 -1
- package/examples/auth-api.ps +56 -0
- package/examples/concurrency.ps +49 -0
- package/examples/error-handling.ps +54 -0
- package/examples/file-uploads.ps +39 -0
- package/examples/files-and-config.ps +47 -0
- package/examples/http-client.ps +44 -0
- package/examples/modules/app.ps +16 -0
- package/examples/modules/math.ps +20 -0
- package/examples/record-kinds.ps +43 -0
- package/examples/search-and-filter.ps +34 -0
- package/examples/sessions-and-cookies.ps +54 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# PlainScript
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<img src="docs/logo.jpg" alt="PlainScript Logo" width="200" />
|
|
4
|
+
<img src="https://github.com/ayoistooslick/plainscript/blob/main/docs/logo.jpg" alt="PlainScript Logo" width="200" />
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
7
|
> "When even a simple sentence can be code."
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
PlainScript is an Intent-Oriented Programming Language (IOPL). You describe **what** you want; the compiler decides **how** to implement it in JavaScript.
|
|
11
11
|
|
|
12
|
-
**Current version:** v1.0.0-
|
|
12
|
+
**Current version:** v1.0.0-latest — the `plainscript` npm package with a TypeScript-style production build (`plainscript build` → `dist/`, source names preserved).
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
@@ -108,7 +108,7 @@ For projects that need custom output or source directories, add a
|
|
|
108
108
|
"build": "plainscript build",
|
|
109
109
|
"prepare": "plainscript build"
|
|
110
110
|
},
|
|
111
|
-
"devDependencies": { "plainscript": "^1.0.0-
|
|
111
|
+
"devDependencies": { "plainscript": "^1.0.0-latest" }
|
|
112
112
|
}
|
|
113
113
|
```
|
|
114
114
|
|
|
@@ -297,9 +297,9 @@ use node-fetch
|
|
|
297
297
|
use @scope/package-name
|
|
298
298
|
```
|
|
299
299
|
|
|
300
|
-
### TypeScript-parity capabilities (1.0.0-
|
|
300
|
+
### TypeScript-parity capabilities (1.0.0-latest)
|
|
301
301
|
|
|
302
|
-
The full capability-gap audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](docs/CAPABILITY_GAP_AUDIT.md).
|
|
302
|
+
The full capability-gap audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](https://github.com/ayoistooslick/plainscript/blob/main/docs/CAPABILITY_GAP_AUDIT.md).
|
|
303
303
|
These features close it in PlainScript's own grammar:
|
|
304
304
|
|
|
305
305
|
- **Record kinds (classes):** `define a kind called "Person" with name is "" done`
|
|
@@ -583,7 +583,9 @@ start env("PORT")
|
|
|
583
583
|
```
|
|
584
584
|
|
|
585
585
|
`param("id")`, `query("page")` and `header("x-token")` read request data;
|
|
586
|
-
`
|
|
586
|
+
`body()` / `body("field")` read the JSON request body; `group` composes path
|
|
587
|
+
prefixes; `status <n>` sets the response code and `redirect to "<url>"` issues a
|
|
588
|
+
redirect.
|
|
587
589
|
|
|
588
590
|
### Databases with parameters and transactions
|
|
589
591
|
|
|
@@ -645,15 +647,46 @@ websocket server on 8080
|
|
|
645
647
|
done
|
|
646
648
|
```
|
|
647
649
|
|
|
648
|
-
### Cache (Redis)
|
|
650
|
+
### Cache (Redis with in-memory fallback)
|
|
649
651
|
|
|
650
652
|
```plainscript
|
|
651
|
-
cache env("REDIS_URL")
|
|
653
|
+
cache env("REDIS_URL") // omit for an in-memory Map store with TTL
|
|
652
654
|
remember token as cacheGet("token")
|
|
653
655
|
cacheSet("greeting", "hi", 60)
|
|
654
656
|
cacheDelete("greeting")
|
|
655
657
|
```
|
|
656
658
|
|
|
659
|
+
Without a configured Redis, `cacheGet`/`cacheSet`/`cacheDelete` transparently fall
|
|
660
|
+
back to an in-memory store, so naive caching works out of the box.
|
|
661
|
+
|
|
662
|
+
### AI / ML
|
|
663
|
+
|
|
664
|
+
```plainscript
|
|
665
|
+
remember reply as chat("gpt-4o-mini", [
|
|
666
|
+
{ role: "user", content: "Say hello in two words" }
|
|
667
|
+
])
|
|
668
|
+
|
|
669
|
+
remember vec as embedText("text-embedding-3-small", "PlainScript rocks")
|
|
670
|
+
remember score as similarity(vec, embedText("text-embedding-3-small", "I love PlainScript"))
|
|
671
|
+
|
|
672
|
+
remember tags as ai_tags("PlainScript is an intent-oriented language")
|
|
673
|
+
remember article as ai_post("Welcome to PlainScript", ["why IOPL", "quick start"])
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
`chat` and `embedText` are async OpenAI-compatible calls (from `OPENAI_API_KEY`,
|
|
677
|
+
override with `options.apiKey`/`options.baseURL`); `similarity` returns -1..1.
|
|
678
|
+
|
|
679
|
+
### Pagination
|
|
680
|
+
|
|
681
|
+
```plainscript
|
|
682
|
+
remember page as paginate(allUsers, 2, 10)
|
|
683
|
+
show page.items # second page of 10
|
|
684
|
+
show page.hasNext # true if another page exists
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
`paginate(list, page, perPage)` returns
|
|
688
|
+
`{ items, count, page, pages, perPage, hasNext, hasPrev }`.
|
|
689
|
+
|
|
657
690
|
---
|
|
658
691
|
|
|
659
692
|
## Multi-file projects
|
package/compiler/cli.js
CHANGED
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
// Usage:
|
|
5
5
|
// plainscript run <file.ps> install missing dependencies, compile and execute
|
|
6
6
|
// plainscript build [file.ps] compile src/ (or one file) to dist/, names preserved
|
|
7
|
-
// plainscript check
|
|
7
|
+
// plainscript check [target] fully validate source(s): imports + generate + JS syntax
|
|
8
|
+
// (target: a .ps file, a directory, or none to scan the project)
|
|
8
9
|
// plainscript fmt <file.ps> format a PlainScript file in-place
|
|
9
10
|
// plainscript new [name] scaffold a new PlainScript project
|
|
10
11
|
// plainscript install install dependencies detected in the project's sources
|
|
@@ -18,6 +19,7 @@
|
|
|
18
19
|
|
|
19
20
|
const fs = require('fs');
|
|
20
21
|
const path = require('path');
|
|
22
|
+
const vm = require('vm');
|
|
21
23
|
const { execFileSync } = require('child_process');
|
|
22
24
|
const { tokenize } = require('./lexer');
|
|
23
25
|
const { parse } = require('./parser');
|
|
@@ -59,7 +61,9 @@ ${section('START')}
|
|
|
59
61
|
${section('BUILD & CHECK')}
|
|
60
62
|
plainscript build Compile every .ps under src/ into dist/
|
|
61
63
|
plainscript build <file.ps> Compile one file into dist/ (name preserved)
|
|
62
|
-
plainscript check
|
|
64
|
+
plainscript check [target] Validate imports + generate + JS output (no writes)
|
|
65
|
+
target: a .ps file, a directory, or none = project scan
|
|
66
|
+
--json emits deterministic machine-readable output
|
|
63
67
|
plainscript fmt <file.ps> Format a file in place
|
|
64
68
|
|
|
65
69
|
${section('PACKAGES')}
|
|
@@ -89,6 +93,8 @@ ${section('ALSO SHIPPED')}
|
|
|
89
93
|
WhatsApp bots (v2.1.1) ·
|
|
90
94
|
email · schedules · WebSocket · cache (v2.1) ·
|
|
91
95
|
sessions · uploads · cookies · rate limits · api keys · OAuth (v2.1.1)
|
|
96
|
+
JSON body · redirect · AI chat/embeddings · vector similarity ·
|
|
97
|
+
paginate · collection & string primitives (v2.2)
|
|
92
98
|
|
|
93
99
|
${section('FIRST RUN')}
|
|
94
100
|
plainscript new hello scaffolds hello/ with a live web app
|
|
@@ -546,7 +552,7 @@ done
|
|
|
546
552
|
// deployment only needs the generated dist/ output.
|
|
547
553
|
fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
|
|
548
554
|
name,
|
|
549
|
-
version: '1.0.0',
|
|
555
|
+
version: '1.0.0-latest',
|
|
550
556
|
description: `A PlainScript v${VERSION} application`,
|
|
551
557
|
main: 'dist/app.js',
|
|
552
558
|
scripts: {
|
|
@@ -745,25 +751,127 @@ function cmdUpdate() {
|
|
|
745
751
|
}
|
|
746
752
|
|
|
747
753
|
// Check syntax of a PlainScript file without generating JavaScript or executing.
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
const
|
|
754
|
-
if (!fs.existsSync(absPath)) {
|
|
755
|
-
console.error(`File not found: ${filePath}`);
|
|
756
|
-
process.exit(1);
|
|
757
|
-
}
|
|
754
|
+
// Full validation of a single .ps entry: resolve imports, parse+generate every
|
|
755
|
+
// file in dependency order, and verify the emitted JavaScript is syntactically
|
|
756
|
+
// valid — all without writing anything to disk. Returns a deterministic
|
|
757
|
+
// result record; `deps` are the npm packages the sources require.
|
|
758
|
+
function validateSource(absPath) {
|
|
759
|
+
const rel = path.relative(process.cwd(), absPath) || absPath;
|
|
758
760
|
const t0 = Date.now();
|
|
759
761
|
try {
|
|
760
|
-
resolveDependencies
|
|
761
|
-
|
|
762
|
-
|
|
762
|
+
// resolveDependencies parses each file too, so a parse error anywhere in
|
|
763
|
+
// the import graph surfaces here with a "file.ps — Line:Col" prefix.
|
|
764
|
+
const files = resolveDependencies(absPath);
|
|
765
|
+
const context = createGenerationContext();
|
|
766
|
+
let js = files.map(({ ast }) => generate(ast, context)).filter(s => s.trim()).join('\n');
|
|
767
|
+
if (context.needsAsync) js = wrapAsync(js);
|
|
768
|
+
|
|
769
|
+
// The compiler must never emit broken JavaScript. Parsing the output with
|
|
770
|
+
// the V8 compiler catches generator regressions at check time.
|
|
771
|
+
new vm.Script(js);
|
|
772
|
+
|
|
773
|
+
// Collect unique npm dependencies across the file and its imports.
|
|
774
|
+
const deps = [];
|
|
775
|
+
for (const { absPath: f } of files) {
|
|
776
|
+
let source;
|
|
777
|
+
try { source = fs.readFileSync(f, 'utf8'); } catch (_) { continue; }
|
|
778
|
+
for (const d of detectDependencies(source)) {
|
|
779
|
+
if (!deps.includes(d)) deps.push(d);
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
return { file: rel, ok: true, deps, ms: Date.now() - t0 };
|
|
763
783
|
} catch (err) {
|
|
764
|
-
|
|
784
|
+
return { file: rel, ok: false, error: err.message, ms: Date.now() - t0 };
|
|
785
|
+
}
|
|
786
|
+
}
|
|
787
|
+
|
|
788
|
+
// `plainscript check [target] [--json]`
|
|
789
|
+
//
|
|
790
|
+
// Fully validates one .ps file, every .ps under a directory, or (with no
|
|
791
|
+
// target) the project sources, deterministically and non-interactively:
|
|
792
|
+
// resolve imports, parse + generate, and confirm the JS output parses. Never
|
|
793
|
+
// prompts, never writes files, never installs packages.
|
|
794
|
+
//
|
|
795
|
+
// plainscript check validate every .ps in the project source root
|
|
796
|
+
// plainscript check app.ps validate one file (and its imports)
|
|
797
|
+
// plainscript check src/ validate every .ps under a directory
|
|
798
|
+
// plainscript check --json machine-readable JSON on stdout
|
|
799
|
+
function cmdCheck(target, json) {
|
|
800
|
+
const opts = readCompilerOptions();
|
|
801
|
+
const srcDir = resolveSrcDir(opts);
|
|
802
|
+
const outDir = resolveOutDir(opts);
|
|
803
|
+
const exclude = opts && opts.exclude;
|
|
804
|
+
|
|
805
|
+
let sources;
|
|
806
|
+
if (target) {
|
|
807
|
+
const abs = path.resolve(target);
|
|
808
|
+
if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
|
|
809
|
+
sources = discoverSources(abs, outDir, exclude).map(r => path.join(abs, r));
|
|
810
|
+
} else if (/\.ps$/.test(target) && !fs.existsSync(abs)) {
|
|
811
|
+
if (json) {
|
|
812
|
+
console.log(JSON.stringify({
|
|
813
|
+
plainscript: VERSION, ok: false,
|
|
814
|
+
sources: [], summary: { total: 0, passed: 0, failed: 1 },
|
|
815
|
+
errors: [{ file: target, error: `File not found: ${target}` }],
|
|
816
|
+
}));
|
|
817
|
+
} else {
|
|
818
|
+
console.error(`File not found: ${target}`);
|
|
819
|
+
}
|
|
820
|
+
process.exit(1);
|
|
821
|
+
} else {
|
|
822
|
+
sources = [abs];
|
|
823
|
+
}
|
|
824
|
+
} else {
|
|
825
|
+
const root = path.resolve(srcDir);
|
|
826
|
+
sources = discoverSources(srcDir, outDir, exclude).map(r => path.join(root, r));
|
|
827
|
+
if (sources.length === 0) {
|
|
828
|
+
const msg = `No .ps files found under "${srcDir}".`;
|
|
829
|
+
if (json) console.log(JSON.stringify({ plainscript: VERSION, ok: false, sources: [], summary: { total: 0, passed: 0, failed: 1 }, errors: [{ file: srcDir, error: msg }] }));
|
|
830
|
+
else console.error(msg);
|
|
831
|
+
process.exit(1);
|
|
832
|
+
}
|
|
833
|
+
}
|
|
834
|
+
|
|
835
|
+
sources.sort(); // deterministic regardless of filesystem order
|
|
836
|
+
const results = sources.map(validateSource);
|
|
837
|
+
const passed = results.filter(r => r.ok);
|
|
838
|
+
const failed = results.filter(r => !r.ok);
|
|
839
|
+
|
|
840
|
+
if (json) {
|
|
841
|
+
const dependencySummary = [];
|
|
842
|
+
const depIndex = new Map();
|
|
843
|
+
for (const r of passed) {
|
|
844
|
+
for (const d of r.deps) {
|
|
845
|
+
if (!depIndex.has(d)) { depIndex.set(d, []); dependencySummary.push(d); }
|
|
846
|
+
depIndex.get(d).push(r.file);
|
|
847
|
+
}
|
|
848
|
+
}
|
|
849
|
+
console.log(JSON.stringify({
|
|
850
|
+
plainscript: VERSION,
|
|
851
|
+
ok: failed.length === 0,
|
|
852
|
+
sources: results,
|
|
853
|
+
summary: { total: results.length, passed: passed.length, failed: failed.length },
|
|
854
|
+
dependencySummary: dependencySummary.map(d => ({ package: d, usedBy: depIndex.get(d) })),
|
|
855
|
+
}));
|
|
856
|
+
process.exit(failed.length ? 1 : 0);
|
|
857
|
+
}
|
|
858
|
+
|
|
859
|
+
for (const r of results) {
|
|
860
|
+
if (r.ok) {
|
|
861
|
+
console.log(`${clrGreen('✓')} ${r.file} — ok${clrDim(` (${r.ms}ms)`)}`);
|
|
862
|
+
} else {
|
|
863
|
+
console.log(`${clrRed('✗')} ${r.file}`);
|
|
864
|
+
console.error(r.error);
|
|
865
|
+
}
|
|
866
|
+
}
|
|
867
|
+
|
|
868
|
+
if (failed.length > 0) {
|
|
869
|
+
console.error(`\n${failed.length} of ${results.length} file(s) failed validation.`);
|
|
765
870
|
process.exit(1);
|
|
766
871
|
}
|
|
872
|
+
if (results.length > 0) {
|
|
873
|
+
console.log(clrGreen(`\n✓ ${results.length} file(s) validated.`));
|
|
874
|
+
}
|
|
767
875
|
}
|
|
768
876
|
|
|
769
877
|
// Format a PlainScript file in-place.
|
|
@@ -803,6 +911,7 @@ async function main() {
|
|
|
803
911
|
// Global flags — recognized anywhere in the argument list.
|
|
804
912
|
const quiet = args.includes('--quiet');
|
|
805
913
|
const verbose = args.includes('--verbose');
|
|
914
|
+
const json = args.includes('--json');
|
|
806
915
|
if (quiet) { stage = stageQuiet; QUIET_STAGES = true; }
|
|
807
916
|
if (verbose) { stage = stageVerbose; VERBOSE = true; }
|
|
808
917
|
|
|
@@ -815,7 +924,7 @@ async function main() {
|
|
|
815
924
|
switch (command) {
|
|
816
925
|
case 'run': await cmdRun(fileArg, positional.slice(2)); break;
|
|
817
926
|
case 'build': await cmdBuild(fileArg); break;
|
|
818
|
-
case 'check': cmdCheck(fileArg);
|
|
927
|
+
case 'check': cmdCheck(fileArg, json); break;
|
|
819
928
|
case 'fmt': cmdFmt(fileArg); break;
|
|
820
929
|
case 'new': cmdNew(fileArg); break;
|
|
821
930
|
case 'install': cmdInstall(); break;
|