strict-script strict-script

Tools

In a project

Nothing is published. A project installs the four packages from files made in a clone of this repository.

#Once, in the clone

corepack enable && pnpm install
pnpm run pack          # builds, then writes tarballs/strict-script-{std,self,compiler,cli}-0.0.0.tgz

#In the project

The command line depends on @strict-ts/std, which is on the npm registry of the Gitea. One line in .npmrc says so:

echo "@strict-ts:registry=https://git.cf.adserver.fr/api/packages/Alex/npm/" >> .npmrc
npm install <clone>/tarballs/strict-script-std-0.0.0.tgz
npm install -D <clone>/tarballs/strict-script-self-0.0.0.tgz <clone>/tarballs/strict-script-compiler-0.0.0.tgz <clone>/tarballs/strict-script-cli-0.0.0.tgz

@strict-script/std is a dependency of the project itself: the JavaScript that is written imports it.

npx strict-script check src                  # what is refused
npx strict-script build src --out dist       # dist/….js, ….d.ts, ….js.map
npx strict-script run src/main.sts one two   # calls main(["one", "two"])

In package.json, with the project as an ECMAScript module ("type": "module"):

{
  "scripts": {
    "check": "strict-script check src",
    "build": "strict-script build src --out dist"
  }
}

#One module of a TypeScript project

A .sts file built beside the TypeScript sources is imported as any module, with its types:

import { parseInvoice, total } from './invoice.js';

const read = parseInvoice(text);
if (read.ok) console.log(total(read.value));
else console.log(read.error.kind);

An Option is { some: true, value } | { some: false } and a Result is { ok: true, value } | { ok: false, error }; records and arrays are typed read-only. The types are named in @strict-script/std (Option, Result, Thrown, ParseError, JsonError).

What TypeScript gives to a function of the module is read against its type when the program runs: the .d.ts tells tsc the types, and a cast or an any on the TypeScript side still does not get a wrong value in. The call throws a TypeError in the caller, before the function runs:

TypeError: `total` was called with an argument that is not of its type: argument 1, at `lines`, expected an array

Reading costs about 20 nanoseconds for each property, at each call from TypeScript, and nothing between two files of the language. A function called often with a large value can take unknown, which is not looked into, and read it with Type.parse where it chooses. What a function gives back is frozen, or another Map; a function it gives back reads what it is called with. The language says what happens to each kind of value.

#In a project built by Vite

With the plugin, a .sts file is imported as it is and compiled by the build: no step is run by hand, in development or for production.

// vite.config.ts
import vue from '@vitejs/plugin-vue';
import strictScript from '@strict-script/vite';

export default { plugins: [vue(), strictScript()] };
<script setup lang="ts">
import { ref } from 'vue';
import { label, next, START } from './counter.sts';

const count = ref(START);
</script>

<template>
  <button @click="count = next(count)">{{ label(count) }}</button>
</template>
  • A .sts file that does not compile fails the build, with the message of the compiler and its place.
  • The source map goes back to the .sts file.
  • Types: the plugin writes counter.d.sts.ts beside counter.sts, which is where TypeScript, the editor and vue-tsc look for the types of ./counter.sts once "allowArbitraryExtensions": true is in tsconfig.json. These files are written by the build: add *.d.sts.ts to .gitignore. strictScript({ declarations: false }) writes none.
  • The project depends on @strict-script/std, which the compiled code imports.

#A component whose script is strict-script

<script lang="sts">
type Shown = { count: Cell<number>, more: () => void }

export function setup(): Shown {
  const count = Cell.of(0)
  { count, more: () => { count.set(count.get() + 1) } }
}
</script>

<template>
  <button @click="more">{{ count }}</button>
</template>
  • The script exports a function setup that gives a record: what the template names.

  • setup may take one record: what the parent wrote on the component. A value comes under its name, and a function to tell the parent something under on and the name of what the parent listens to:

    type Given = { start?: number, onChanged?: (clicks: number) => void }
    
    export function setup(given: Given): Shown { … }
    <Counter :start="5" @changed="told = $event" />

    It is read once, when the component is made. A script that exports update is told what the parent writes later, and one that exports leave is told when the component goes away:

    export function update(shown: Shown, given: Given) { … }
    export function leave(shown: Shown) { … }

    Write the names in the parent as they are in the record (:start, not :initial-count for initialCount). What the parent hands is read against the record, and a parent that hands something else is refused where the component is made: a property it may leave out is written with ?.

  • The state is in cells. A Cell that setup gives is shown to Vue as a ref: the page follows it when the program gives it another value, and what the template writes (v-model="name") is put in it. Nothing of Vue is declared in an extern, and nothing in the script gives a Result for being a component.

  • It is <script lang="sts">, not <script setup>: what the template may name is what setup gives, written with its type.

  • Not there yet: a setup that waits (async: it is refused where the component is built), computed and watch. A function that setup gives and that the template calls is called again when a cell it read changes, provided that cell is among what setup gives; that does for most of what computed is used for.

The template is checked by vue-tsc, and by Vue's tools in an editor, once this is in tsconfig.json:

{ "vueCompilerOptions": { "plugins": ["@strict-script/vite/volar"] } }

A name the script does not give, a function called without what it asks for, a number taken for a text: each is said where it is written in the template. The script itself is checked by the compiler, not by vue-tsc.

What is still taken on trust, since the template is Vue's and not the language's:

  • What vue-tsc accepts, TypeScript accepts: an any, a cast, $event of a type that was not written. A function of the script reads what it is called with, so such an expression is refused when the page runs it, and not before.
  • What the template writes into a cell (v-model) is read against the type of the cell: a cell of numbers bound to a field of text refuses the text, when the page runs.
  • A value read out of a cell is read-only for the language, and frozen when it is data: items.push(…) in a handler of the template is refused when the page runs. A Map or a Set is given as another one: what the template does to it, the script does not see.
  • A function the script gives is called by Vue with what the event carries, and by the template with what it writes there: it reads each of them against its type.

Keep in the template what a template is for, names and calls with the values the script gave, and the script's types hold.

#In a React application

A component is two functions written in strict-script, in a .sts file that the build compiles (the plugin for Vite above): setup, called once, which makes its state in cells; and view, which gives what to show from that state, as elements.

// Counter.sts
export type State = { count: Cell<number> }

export function setup(): State { { count: Cell.of(0) } }

export function view(state: State): Markup {
  <button onClick={() => { state.count.set(state.count.get() + 1) }}>
    {state.count.get()} clicks
  </button>
}
// main.ts
import { component } from '@strict-script/react';
import { setup, view } from './Counter.sts';

const Counter = component(setup, view);   // a component of React, used as any other
  • @strict-script/react makes React's elements from the language's, and shows the component again when a cell is given another value. Each place the component is used has its own state.

  • No hook is written. useState, useEffect and the rules that go with them have no word here: the state is what setup gives, and view is a function of it.

  • class and for are written as in HTML. A function given to an element is called with nothing, or with the text that was typed: it is not handed React's event.

  • setup may take one record: what the component is given where it is used, by a parent written in TypeScript too. It is read once; a component made with update (component(setup, view, { update })) is told, with what setup gave, each time its parent hands it other values. What a TypeScript parent hands is read against the record, and refused when it is something else.

  • A form that is sent does not leave the page: the function given to onSubmit says what sending it does.

  • A component that starts something ends it: setup is where a timer or a listener is started, and a third function says what to do when the component goes away, with what setup gave. Not when React throws a rendering away before it shows it (under Suspense): setup ran, and React tells nobody.

    export function leave(state: State) { … }      // stops what `setup` started
    const Clock = component(setup, view, { leave });
  • Not there yet: something to do each time a value changes, refs to the elements of the page, context.

What is taken on trust: the names of the page's elements and of their attributes, which nothing checks; and React itself.

#In a project built by webpack, or by Next

@strict-script/loader/webpack is a loader: a .sts file becomes its JavaScript where it is imported.

// webpack.config.js
module.exports = { module: { rules: [{ test: /\.sts$/, loader: '@strict-script/loader/webpack' }] } };
// next.config.js
module.exports = {
  webpack: (config) => {
    config.module.rules.push({ test: /\.sts$/, loader: '@strict-script/loader/webpack' });
    return config;
  },
  turbopack: { rules: { '*.sts': { loaders: ['@strict-script/loader/webpack'], as: '*.js' } } },
};

The loader is tested with webpack, and inside Next 16 with each of its two bundlers (next build --webpack, next build --turbopack): a page rendered on the server calls a function of a .sts file, a component whose state and view are strict-script is taken over in a browser and follows a click, and a file that is refused fails the build with the message of the compiler (packages/react/test/next.test.ts). next dev was not run.

#In a React Native application

// metro.config.js
const { getDefaultConfig } = require('@react-native/metro-config');

const config = getDefaultConfig(__dirname);
config.transformer.babelTransformerPath = require.resolve('@strict-script/loader/metro');
config.resolver.sourceExts.push('sts');
module.exports = config;
// jest.config.js: the tests read `.sts` files too
module.exports = {
  preset: 'react-native',
  moduleFileExtensions: ['js', 'json', 'sts', 'ts', 'tsx'],
  transform: { '\\.sts$': '@strict-script/loader/jest', '\\.[jt]sx?$': 'babel-jest' },
};

A component is written as for React, with React Native's components named without a capital, since a tag that starts with one is a function of the program:

export function view(state: State): Markup {
  <view>
    <pressable onPress={() => state.count.set(state.count.get() + 1)}>
      <text>{state.count.get()} presses</text>
    </pressable>
    <textinput value={state.name.get()} onChangeText={text => state.name.set(text)} />
  </view>
}
import * as native from 'react-native';
import { component, nativeTags } from '@strict-script/react';
import { setup, view } from './Counter.sts';

export const Counter = component(setup, view, { tags: nativeTags(native) });
  • Metro loads a transformer with require, and the compiler is a module: Node 22.12 or later.
  • A style is a record of texts, numbers and booleans, written in the view: <view style={{ padding: 8 }}>. An array of styles, or a style made with StyleSheet.create, is not given to an element here.
  • Not run on a phone, nor in a simulator. A test of React Native renders the component with React Native's own components (packages/react/test/native), and Metro builds it into the bundle of an application; what is native under the components is what React Native's test preset puts there.
  • Run on Hermes, the engine of React Native, and not the one of a given version of it. A program that uses each thing the language has is built by Metro with React Native's preset and run by Hermes 0.12 as a command (packages/react/test/hermes.test.ts): it prints what it prints on Node. The same engine compiles the bundle of the application to the bytecode a phone is given. That Hermes is a build of 2022, older than the one any React Native of today carries; the one React Native 0.79 carries comes as a compiler only, and compiles both to the bytecode of today, which nothing here runs. The build of 2022 lacks toSorted, toReversed and Object.hasOwn, which the runtime library called and no longer does; what the program does not use was not tried.

#In an Angular application

A component of Angular is a class with a decorator, read by Angular's compiler from TypeScript source. The language has no class: the class and the template stay Angular's, and what the component does is written in strict-script, its state in cells and its functions.

// counter.sts
export type State = { count: Cell<number>, more: () => void, label: (count: number) => string }

export function setup(): State {
  const count = Cell.of(0)
  { count, more: () => count.set(count.get() + 1), label: count => `${count} clicks` }
}
// counter.component.ts
import { Component } from '@angular/core';
import { shown } from '@strict-script/angular';
import { setup } from './counter.js';

@Component({ selector: 'app-counter', template: `<button (click)="s.more()">{{ s.label(s.count()) }}</button>` })
export class CounterComponent {
  readonly s = shown(setup());
}
  • shown gives what setup gave with each cell as a signal: the template reads it by calling it (s.count()) and writes it with set (s.name.set(…)). The page follows a cell when the program gives it another value.

  • Angular's command line takes no plugin: the .sts files are compiled first, beside themselves, and the class imports the .js with its .d.ts.

    { "scripts": { "prebuild": "strict-script build src", "build": "ng build" } }
  • Angular's compiler checks the template against the class, so against the types of what setup gives: strictTemplates sees s.count() as a number.

What is taken on trust: the template, which may hand a function of the script a value Angular's compiler accepted and the function did not ask for ($any(…)), and may change in place a value read out of a cell; Angular's compiler; and the few lines of the class.

The names and the shapes a TypeScript program sees are in The standard library; colours in an editor are in In the editor.

Esc

    Type a word of the language, a rule, a command: mut, extern, match-not-covered.