npm.io
1.0.0 • Published yesterdayCLI

@raarion/prompt-js

Licence
MIT
Version
1.0.0
Deps
0
Size
949 kB
Vulns
0
Weekly
0
Stars
2
SummaryDependencyVersions
PromptJS Logo
PromptJS Logo

License Version Zero Dependencies Tests Coverage Live Showcase

DSL deklaratif dwibahasa. Tulis layaknya prompt — hasilkan vanilla JavaScript production-ready.

Reaktivitas • Komponen • Routing • Auth • Plugin • CSP • Hardened • Zero Deps

Tulis dengan Bahasa yang Kamu Pahami, Hasilkan Kode yang Dunia Mengerti.

[ Coding ] ⊷ [ Vibe Coding ] ⊷ [ Prompting ]
dan PromptJS adalah jembatan antara ketiganya.

Apa itu PromptJS?

PromptJS adalah sebuah DSL (domain-specific language) — bahasa deklaratif berbasis indentasi yang dikompilasi menjadi JavaScript vanilla. Ia bukan framework. Ia tidak membungkus runtime. Ia adalah compiler: kamu menulis dengan kata-kata yang mengalir seperti prompt, dan PromptJS menerjemahkannya menjadi kode bersih tanpa dependensi.

PromptJS lahir dari sebuah pertanyaan sederhana: di era di mana semua orang sudah nyaman menulis prompt ke AI, kenapa menulis kode masih terasa seperti bahasa asing?

Jawabannya adalah menjembatani tiga dunia yang selama ini terpisah:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace'}}}%%

graph TD
    A["✦ CODING ✦<br/>disiplin, ketat, penuh simbol"] --> P
    B["✦ VIBE CODING ✦<br/>semi-bebas, AI-assisted, eksploratif"] --> P
    C["✦ PROMPTING ✦<br/>bebas, natural, seperti ngomong"] --> P

    P[/"<b>P R O M P T J S</b>"/]

    P --> D["jembatan<br/>antara ketiganya"]

    style A fill:#fff0f3,stroke:#ff8fa3,stroke-width:2px,color:#590d22
    style B fill:#e0f4f8,stroke:#48cae4,stroke-width:2px,color:#023e8a
    style C fill:#e9f5db,stroke:#70e000,stroke-width:2px,color:#1a4301
    style P fill:#ff006e,stroke:#ff99c8,stroke-width:3px,color:#fff
    style D fill:#f8f9fa,stroke:#adb5bd,stroke-width:2px,color:#212529

PromptJS dirancang dengan kata kunci bilingual (Indonesia & Inggris) yang bisa dicampur dalam satu file, pipeline kompilasi 5 tahap, dan output zero runtime dependency. Ia sengaja ketat pada aturan — indentasi, struktur blok, pipeline — agar tetap terasa seperti coding yang sesungguhnya. Tapi permukaannya didesain sedemikian rupa agar mengalir seperti menulis prompt: tanpa {}, tanpa </>, hampir tanpa simbol — hanya rangkaian kata yang dirangkai sesuai pola.

Hasilnya: sebuah antarmuka baru antara manusia dan kode. Disiplin seorang programmer. Kenyamanan seorang prompter. Kekuatan vanilla JavaScript.

DNA PromptJS — Prinsip yang Kami Pegang

Ini bukan sekadar fitur. Ini adalah keyakinan desain yang menjadi tulang punggung setiap keputusan di PromptJS:

Prinsip Artinya
Bahasa adalah akses Bilingual bukan fitur tambahan — ia adalah DNA. Kamu bisa menulis Buat atau Create, Jika atau If, dalam satu file yang sama. Bahasa ibumu adalah bahasa pemrograman yang valid.
Menulis kode = menulis prompt PromptJS menghilangkan hampir semua simbol sintaks. Tidak ada {}, </>, atau () => {}. Yang tersisa hanya rangkaian kata dalam struktur yang masuk akal — seperti prompt, tapi dengan aturan yang jelas.
Disiplin dalam kenyamanan Indentasi ketat. Blok terstruktur. Pipeline 5 tahap. PromptJS tidak mengorbankan kedisiplinan coding demi kemudahan — ia membungkusnya dalam permukaan yang manusiawi.
Compile, don't wrap PromptJS bukan framework yang membungkus runtime. Ia adalah compiler yang menerjemahkan DSL → vanilla JS. Output bersih, zero dependency, tanpa overhead.
Keamanan dari awal, bukan setelahnya Zero eval(), zero new Function(). Sanitizer allowlist. CSP built-in. Setiap fitur keamanan dikunci oleh regression test.
Dokumentasi adalah fitur, bukan utang Setiap keyword, setiap error code, setiap adapter — terdokumentasi. Bilingual. Dengan contoh nyata.
Terukur, bukan klaim 880 tests. 84.8% coverage. Mutation testing. CI gate ketat. Tidak ada "seharusnya aman" — semua dibuktikan.
Dibangun dari Indonesia, untuk dunia Bilingual ID/EN. Modul ajar siap pakai. Dirancang agar siapa pun — dari pelajar hingga profesional — bisa mulai coding dengan bahasa yang mereka pahami.

Kenapa Harus PromptJS?

PromptJS adalah compiler, bukan framework. Kamu menulis dalam bahasa Indonesia (atau Inggris) — dengan struktur yang terasa alami seperti menulis prompt — dan PromptJS mengkompilasinya menjadi JavaScript vanilla yang siap production.

Tanpa React. Tanpa Vue. Tanpa runtime overhead. Tanpa virtual DOM.

---
judul: "Halo Dunia"
---

Halaman Utama:
    data hitung = 0

    Buat h1: $judul
    Buat tombol: "Klik aku"
        Ketika diklik:
            tambahkan 1 ke hitung
    Buat paragraf:
        "Diklik: " + hitung + " kali"

→ compile → vanilla JS. No node_modules di output. No virtual DOM. Just clean, auditable code yang bisa kamu baca dan pahami.

PromptJS tidak memintamu belajar sintaks baru — ia memintamu merangkai kata dalam pola yang sudah kamu mengerti. Hasilnya? JavaScript. Production-ready. Zero dependencies.

Mulai sekarang → docs/user/getting-started.md

Quick Start

npm install @raarion/prompt-js            # install
pjs init -t counter              # bikin proyek baru
pjs serve --port 3000            # jalanin dev server
pjs build --adapter static       # build production 🚀

Requirements: Node.js ≥ 22.0.0 (selaras dengan CI; Node 20 sudah EOL sejak 2025-10)

Lingkup v1.0.0 (Capability Lock)

v1.0.0 bukan sekadar label versi — ini batas kemampuan yang dikunci sebagai permukaan stabil PromptJS. Kemampuan berikut adalah identitas resmi rilis 1.0.0 dan dijamin stabil di seluruh lini 1.0.x (perubahan yang merusak hanya pada major berikutnya):

  • Compiler DSL bilingual — pipeline penuh lexer → parser → resolver → analyzer → compiler/emitters, dengan keyword dwibahasa (Buat/Create, Jika/If, Ulangi/Loop) dan 70+ kode error/warning bilingual.
  • Reaktivitas — data berbasis Proxy, computed turunan, dan watcher Saat.
  • Komponen — Komponen Nama(props): yang composeable & reusable.
  • Sistem modul — kirim / terima dengan resolusi & deteksi siklus.
  • CSS scoping — gaya ber-scope per komponen (Gaya: / Style:) + alias tag.
  • Router SPA — router: benar (pushState, segmen dinamis, lifecycle).
  • Auth guard — butuhAuth: benar + peran (client guard berbasis redirect).
  • Adapter deployment — static · node · vercel, dengan path-traversal guard terpusat (src/utils/path-guard.js) yang dipakai konsisten lintas adapter dan CLI serve.
  • Target QA tinggi (terukur, bukan klaim) — gerbang CI menegakkan: Prettier, typecheck (JSDoc/checkJs), ESLint --max-warnings=0, 880 test / 43 file, ambang coverage per-modul (saat ini ~84.8% lines / 75.23% branch), mutation testing Stryker pada inti semantik, plus npm audit & CodeQL untuk rantai pasok.

Di luar lingkup 1.0.0 (post-1.0): SSR/hydration, state management lintas rute bawaan, dan plugin runtime pihak ketiga. Hal-hal ini dapat ditambah di minor/major berikutnya tanpa melanggar kontrak 1.0.x di atas.

Penggunaan CLI

pjs init -t counter          # Scaffold proyek baru (6 template)
pjs compile halaman.pjs      # Kompilasi file tunggal
pjs serve --port 3000        # Dev server dengan live-reload
pjs build --adapter static   # Build produksi (static | node | vercel)

Fitur

Fitur Deskripsi
Sintaks Indentasi Python-style — tanpa {}, tanpa </tutup>. Blok dari indentasi
Bilingual Keyword dwibahasa: Buat/Create, Jika/If, Ulangi/Loop
AST-based Full Abstract Syntax Tree — recursive-descent parser + structured node types
Reaktivitas Proxy-based data, computed turunan, Saat watcher
Komponen Komponen Nama(props): — composeable, reusable
SPA Routing router: benar — pushState, dynamic segments, lifecycle
Auth Guard butuhAuth: benar + peran — redirect-based client guard
Plugin System 4 transform hooks: source → JS → CSS → HTML
Adapters static · node · vercel — pilih target deployment
CSP Ready --csp flag — nonce injection buat production hardening
Tree Shaking Runtime helpers cuma di-emit kalo dipake — output minimal
Safe Output Zero eval(), zero new Function(), no dynamic code execution
Hardened Codegen Sanitizer allowlist (Sanitizer API/DOM), __safeAttr filter on* & URL javascript:, escape front-matter — lihat Keamanan

Benchmark Ringkasan (Summary)

TL;DR: PromptJS vs kompetitor lain dalam satu tabel. Data lengkap & sumber ada di BENCHMARK.md.

Dimensi PromptJS Svelte 5 SolidJS Vue 3 React 19 Alpine.js
Output Size (counter app) 3.5 KB 3–6 KB 22 KB + app 46 KB + app 42 KB + app 45 KB + app
Compile Time 9.8 ms ~20 ms ~5 ms ~15 ms ~50 ms 0 (no compile)
Runtime Deps 0 0 3 5 2 1
node_modules (install) 28 MB 32 MB 18 MB 48 MB 52 MB 12 MB
No eval() / new Function()
CSP Built-in (--csp flag) manual manual manual manual manual
Keyword Bilingual (ID + EN)
Docs Bilingual parsial banyak
Test Suite 880 tests (43 file) 3,000+ — 4,000+ 10,000+ —
Modul Ajar / Edukasi Academy
Mekanisme Compile → vanilla JS Compile → vanilla JS Fine-grained reactive Virtual DOM Virtual DOM Runtime reactive

= unik / leading di kategori tersebut.
Data lengkap, metodologi, dan sumber → BENCHMARK.md

Kematangan Test, Coverage & Mutation (v5)

Semua angka di bawah terverifikasi dari run nyata pada fresh install (npm ci), bukan klaim. Lihat detail metodologi di BENCHMARK.md.

Sinyal Nilai (v5) Gate CI
Test 880 lulus / 880 (43 file, vitest) wajib hijau
Determinisme 880/880 pada 3 run berturut-turut — nol flaky —
Coverage — lines 84.8% gate ≥ 80% (gagal saat regresi)
Coverage — branches 75.2% gate ≥ 71%
Coverage — functions 84.0% gate ≥ 82%
Mutation score (Stryker, scoped resolver+analyzer, ignoreStatic) 63.91% (v5, naik dari baseline 49.72%) break = 45 (gagal hanya saat regresi)
Lint ESLint --max-warnings=0 bersih wajib
Typecheck tsc --noEmit (JSDoc/checkJs) 0 error wajib
Format Prettier --check bersih wajib

CI — GitHub Actions (.github/workflows/ci.yml), 3 job:

  1. build-and-test — matrix Node 22.x & 24.x: format:check → typecheck → lint → test → smoke compile CLI → compile semua contoh (examples, multi-page, todo-app, dashboard-app).
  2. coverage — npm run coverage sebagai hard gate ≥ 80% lines (threshold di vitest.config.js; CI gagal saat coverage regresi) + upload lcov/html.
  3. mutation — Stryker scoped resolver + analyzer (npm run mutation), break threshold 45 (di bawah baseline 49.72% → gagal hanya saat assertion dilemahkan/dihapus) + upload report html/json.

Jujur soal mutation score: v5 menaikkan skor dari baseline 49.72% → 63.91% (+14.19 poin, terverifikasi dari mutation.json) lewat 63 test baru. Target internal 65% belum tercapai (kurang ~1.09 poin); mayoritas mutant tersisa (ConditionalExpression + StringLiteral teks diagnostik + NoCoverage) menunggu assertion diperketat. break=45 tetap di bawah baseline supaya CI hanya gagal saat regresi.

Pipeline Kompilasi

Source (.pjs) → Lexer → Parser → Resolver → Analyzer → Compiler → JS Vanilla
Tahap File Tanggung Jawab
Lexer promptjs-lexer.js Tokenisasi, keyword bilingual, indentasi → INDENT/DEDENT
Parser promptjs-parser.js Recursive-descent AST builder, event/tag alias resolution
Resolver promptjs-resolver.js Scope resolution, identifier validation, write tracking
Analyzer promptjs-analyzer.js Semantic analysis, type hints, dependency graph, usage warnings
Compiler promptjs-compiler.js Emit vanilla JS + tree-shaken runtime + source maps

Live Showcase

Lihat contoh langsung di browser: https://raarion.github.io/promptjs/

Setiap file examples/*.pjs di-compile menjadi halaman HTML dengan source code di kiri dan live preview di kanan.

Editor Support

Syntax highlighting untuk VS Code tersedia di folder editors/vscode/ — lihat editors/vscode/README.md.

Repo Map

Klik setiap section buat expand/collapse. Semua file bisa diklik langsung ke source-nya. No cap.

Engine — Compiler & Runtime
Click to expand — Engine (Compiler & Runtime)
Dokumentasi
Click to expand — Dokumentasi
Contoh & Demo
Click to expand — Contoh & Demo
  • examples/
    • counter.pjs ← Counter interaktif
    • todo.pjs ← Todo list sederhana
    • gallery.pjs ← Galeri gambar
    • todo-app/ ← Todo app lengkap (reactive + localStorage)
    • dashboard-app/ ← Dashboard SPA (auth, routing, role-based)
    • multi-page/ ← Multi-page site
Testing & CI
Click to expand — Testing & CI

Suite ketahanan v2–v4 (edge-case, error-path & branch coverage):

Suite mutation-hardening v5 (penguatan assertion untuk membunuh mutant Stryker):

Suite edge/branch v6 + guard path tersentralisasi (S-12/S-15/S-21/S-24):

Config & Infra
Click to expand — Config & Infra

Keamanan / Security Hardening

PromptJS v1.0.0 telah melalui audit keamanan mendalam dan tiga gelombang perbaikan yang ter-merge ke main. Semua temuan HIGH & MEDIUM ditutup dan dikunci oleh regression test ber-PoC.

Temuan Severity Status Ringkasan perbaikan
S-1 Code-injection front-matter auth HIGH Fixed Whitelist storage + escapeString() pada nilai input
S-2 Sanitizer regex bypass HIGH Fixed Allowlist berbasis Sanitizer API / parsing DOM (safe-by-default)
S-3 html: tak tersanitasi (element-creation) HIGH Fixed Satu jalur emit HTML tunggal melewati sanitizer
S-4 Injeksi atribut/event-handler MED Fixed Helper __safeAttr tolak on* & URL berbahaya (4 sink)
S-5 Peran auth mudah dipalsukan MED Fixed Seam __pjs_verifyPeran + warning jujur (client-side advisory)
S-6 Dev-server path traversal MED Fixed path.relative() + decodeURIComponent anti-%2e%2e
S-15 / S-21 Guard path traversal tersebar di adapter MED Fixed Guard disentralisasi ke util bersama src/utils/path-guard.js (isInsideRoot/safeResolve), diterapkan ke serve/static/vercel (100% test-covered)
T-1 CLI coverage 0% Test Fixed Suite integrasi CLI (spawn binary + serve e2e)
T-2 Coverage cabang adapter/emitter (S-12/S-21/S-24) Test Fixed Suite edge/branch v6 untuk static/vercel/statements (+70 test)

Verifikasi akhir di main: ESLint 0 warning · tsc 0 error · Prettier clean · 880/880 test lulus (43 file) · coverage lines 84.8% / branch 75.23% · npm audit 0 kerentanan · versi tetap v1.0.0.

Catatan jujur: auth guard PromptJS bersifat client-side/advisory — bukan kontrol keamanan server. Untuk otorisasi sesungguhnya, verifikasi peran wajib dilakukan di server (gunakan seam window.__pjs_verifyPeran).

Audit Follow-ups & DX Hardening

Setelah tiga gelombang keamanan, satu PR lanjutan menutup temuan audit & DX yang terverifikasi — tetap v1.0.0, keamanan fail-closed terjaga, nol regresi:

# Perbaikan Dampak
1 Scoped CSS translate tag-alias (css.js) tombol[data-pjs-x] → button[data-pjs-x] — komponen scoped + tag Indonesia kini ter-style benar
2 Router regex escape (router-runtime.js) Bagian literal route di-escape sebelum RegExp — guard ReDoS
3 Kanal warning terstruktur (Lapis 2) console.warn ad-hoc → format berkode [PromptJS] PJS-Wxxxx: pesan (saran); atribut bahaya tetap diblokir
4 Konsolidasi findPjsFiles() 3 salinan → 1 sumber kebenaran di cli/utils.js dengan opsi {ignoreDirs, sort}
5 Hapus @ts-nocheck (builder.js, css.js) Blanket-suppress dihapus; typecheck tetap 0 error
6 Normalisasi version banner Banner identitas v0.x → v1.0.0 (marker historis dipertahankan)

QA gate: 880/880 test (43 file) · ESLint --max-warnings=0 · tsc 0 error · Prettier clean · coverage gate ≥80% lines (lines 84.8% / branch 75.23%) · Stryker mutation 63.91% (naik dari baseline 49.72%) · v1.0.0.

PromptJS Academy

Pre-release — modul sedang disiapkan.

PromptJS dirancang bukan cuma buat developer — tapi juga buat siapa pun yang baru mulai belajar ngoding. Ke depan, PromptJS Academy akan menyediakan modul ajar siap pakai:

Click to expand — PromptJS Academy (Coming Soon)
  • modul-ajar/ ← Coming soon
    • dasar/
      • 01-kenalan.md ← Apa itu coding & PromptJS
      • 02-variabel.md ← data, tetap, ubah
      • 03-elemen.md ← Buat h1, p, tombol, gambar
      • 04-event.md ← Ketika diklik, diketik
      • 05-kondisi.md ← Jika/Lainnya
      • 06-perulangan.md ← Ulangi/Untuk
      • 07-proyek-akhir.md ← Bikin app pertama
    • menengah/
      • 08-komponen.md ← Komponen & props
      • 09-reaktivitas.md ← data, turunan, Saat
      • 10-routing.md ← Multi-page SPA
      • 11-auth.md ← Login & guard
      • 12-api.md ← Ambil data dari API
    • mahir/
      • 13-plugin.md ← Bikin plugin sendiri
      • 14-deploy.md ← Build + deploy production
      • 15-csp.md ← Security hardening
      • 16-proyek-final.md ← Full-stack capstone
    • guru/
      • rpp/ ← Rencana Pelaksanaan Pembelajaran
      • slide/ ← Slide presentasi per-materi
      • evaluasi/ ← Soal latihan & kunci jawaban
    • bootcamp/
      • jadwal.md ← Kurikulum 4/8/12 minggu
      • proyek.md ← Final project specs
      • sertifikat.md ← Template sertifikat

Target: Sekolah, Bootcamp Coding, Kursus Online/Offline, Self-taught.

Mau ikut berkontribusi? Buka CONTRIBUTING.md atau langsung buka issue!

Quality Assurance

npm test          # 880 tests, 43 test files
npm run coverage  # gate ≥80% lines (84.8% measured)
npm run mutation  # Stryker (scoped resolver+analyzer) — 63.91% (baseline 49.72%)
npm run lint      # ESLint — zero warnings
npm run typecheck # tsc — zero errors
npm run format    # Prettier

Kontribusi

PromptJS terbuka buat siapa aja — dari bug fix, feature request, sampai modul ajar. Cek CONTRIBUTING.md buat panduan lengkap.

Lisensi

MIT raarion

Dibangun dengan di Indonesia • Built with in Indonesia

Keywords

dsltemplatecompilerindonesianpromptjsbilingualfrontendvanilla-jsreactivedom