functionalscript 0.43.1 → 0.45.0

package/fjs/dev/update/module.f.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
+ */
+import type { Effect } from '../../effects/types.ts';
+import type { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts';
+/**
+ * Regenerates VS Code's local MCP configuration from the canonical Copilot configuration.
+ *
+ * @type {() => Effect<Mkdir | ReadFile | WriteFile, void>}
+ */
+export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void>;
+/**
+ * Runs all local development configuration generators.
+ *
+ * @type {NodeProgram}
+ */
+export declare const main: NodeProgram;

package/fjs/dev/update/module.f.mjs

@@ -0,0 +1,37 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
+ */
+
+import { history, historyStep, mapStep, step } from '../../effects/module.f.mjs'
+import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { unwrap } from '../../types/result/module.f.mjs'
+
+const source = /** @type {const} */ ('.copilot/mcp.json')
+const targetDirectory = /** @type {const} */ ('.vscode')
+const target = /** @type {const} */ ('.vscode/mcp.json')
+
+/**
+ * Regenerates VS Code's local MCP configuration from the canonical Copilot configuration.
+ *
+ * @type {() => Effect<Mkdir | ReadFile | WriteFile, void>}
+ */
+export const syncMcp = () => {
+    const sourceText = history(mapStep(readUtf8File(source), unwrap))
+    const targetDirectoryReady = historyStep(
+        sourceText,
+        () => mapStep(mkdir(targetDirectory, { recursive: true }), unwrap))
+    const targetWritten = step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text))
+    return mapStep(targetWritten, unwrap)
+}
+
+/**
+ * Runs all local development configuration generators.
+ *
+ * @type {NodeProgram}
+ */
+export const main = () => mapStep(syncMcp(), () => 0)

package/fjs/dev/update/proof.f.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Proofs for local development configuration generation.
+ */
+export declare const proof: {
+    syncMcp: () => void;
+    main: () => void;
+    throw: {
+        missingSource: () => readonly [import("../../effects/node/virtual/types.ts").State, void];
+    };
+};

package/fjs/dev/update/proof.f.mjs

@@ -0,0 +1,35 @@
+/**
+ * Proofs for local development configuration generation.
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { utf8 } from '../../text/module.f.mjs'
+import { readUtf8File } from '../../effects/node/module.f.mjs'
+import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.mjs'
+import { main, syncMcp } from './module.f.mjs'
+import { step } from '../../effects/module.f.mjs'
+
+const mcp = /** @type {const} */ ('{"servers":{}}')
+const initial = /** @type {const} */ ({
+    ...emptyState,
+    root: {
+        '.copilot': {
+            'mcp.json': [utf8(mcp)],
+        },
+    },
+})
+export const proof = {
+    syncMcp: () => {
+        const generatedMcp = step(syncMcp(), () => readUtf8File('.vscode/mcp.json'))
+        const [, [tag, result]] = virtual(initial)(generatedMcp)
+        assert(tag === 'ok', result)
+        assertEq(result, mcp)
+    },
+    main: () => {
+        const [, result] = virtual(initial)(main(defaultNodeProgramOptions))
+        assertEq(result, 0)
+    },
+    throw: {
+        missingSource: () => virtual(emptyState)(syncMcp()),
+    },
+}

package/fjs/djs/ast/module.f.d.mts

@@ -0,0 +1,35 @@
+/**
+ * AST types and helpers for the DJS representation.
+ *
+ * @module
+ *
+ * @import { Array, Unknown } from '../types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Entry } from '../../types/ordered_map/types.ts'
+ * @import { AstConst, AstBody } from './types.ts'
+ */
+import type { Array, Unknown } from '../types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { Entry } from '../../types/ordered_map/types.ts';
+import type { AstBody } from './types.ts';
+export type _RunState = {
+    readonly body: AstBody;
+    readonly args: Array;
+    readonly consts: List<Unknown>;
+};
+export type _FoldObjectState = {
+    readonly runState: _RunState;
+    readonly entries: List<Entry<Unknown>>;
+};
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ *
+ * @type {(body: AstBody) => (args: Array) => Unknown}
+ */
+export declare const run: (body: AstBody) => (args: Array) => Unknown;

package/fjs/djs/ast/module.f.mjs

@@ -0,0 +1,82 @@
+/**
+ * AST types and helpers for the DJS representation.
+ *
+ * @module
+ *
+ * @import { Array, Unknown } from '../types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Entry } from '../../types/ordered_map/types.ts'
+ * @import { AstConst, AstBody } from './types.ts'
+ */
+
+import { concat, fold, last, map, take, toArray } from '../../types/list/module.f.mjs'
+import { fromEntries } from '../../types/object/module.f.mjs'
+
+const { entries } = Object
+
+/** @typedef {{
+ *   readonly body: AstBody
+ *   readonly args: Array
+ *   readonly consts: List<Unknown>
+ * }} _RunState */
+
+/** @typedef {{
+ *   readonly runState: _RunState,
+ *   readonly entries: List<Entry<Unknown>>
+ * }} _FoldObjectState */
+
+/** @type {(ast: AstConst) => (state: _RunState) => _RunState} */
+const foldOp = ast => state => {
+    const djs = toDjs(state)(ast)
+    return { ...state, consts: concat(state.consts)([djs]) }
+}
+
+/** @type {(entry: [string, AstConst]) => (state: _FoldObjectState) => _FoldObjectState} */
+const foldAstObjectOp = entry => state => {
+    const e = concat(state.entries)([[entry[0], (toDjs(state.runState)(entry[1]))]])
+    return { ...state, entries: e }
+}
+
+/** @type {(state: _RunState) => (ast: AstConst) => Unknown} */
+const toDjs = state => ast => {
+    switch (typeof ast) {
+        case 'boolean':
+        case 'number':
+        case 'string':
+        case 'bigint': { return ast }
+        default: {
+            if (ast === null) { return ast }
+            if (ast === undefined) { return ast }
+            if (ast instanceof Array) {
+                switch (ast[0]) {
+                    case 'aref': { return state.args[ast[1]] }
+                    case 'cref': { return last(null)(take(ast[1] + 1)(state.consts)) }
+                    case 'array': { return toArray(map(toDjs(state))(ast[1])) }
+                }
+            }
+            const e = fold(foldAstObjectOp)({ runState: state, entries: null })(entries(ast)).entries
+            return fromEntries(e)
+        }
+    }
+}
+
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ *
+ * @type {(body: AstBody) => (args: Array) => Unknown}
+ */
+export const run = body => args => {
+    const state = fold(foldOp)({ body, args, consts: null })(body)
+    return last(null)(state.consts)
+}
+
+// for functions
+// export const astBodyToAstConst
+//     :(body: AstBody) => (args: AstArray) => AstConst
+//     = body => args => todo()

package/fjs/djs/ast/proof.f.mjs

@@ -0,0 +1,48 @@
+import { sort } from '../../types/object/module.f.mjs'
+import { run } from './module.f.mjs'
+import { stringifyAsTree } from '../serializer/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    test: () => {
+        const djs = run([1])([])
+        const result = stringifyAsTree(sort)(djs)
+        assertEq(result, '1')
+    },
+    testCref: () => {
+        const djs = run([1, 2, 3, 4, 5, ['cref', 3]])([11, 12, 13, 14, 15])
+        const result = stringifyAsTree(sort)(djs)
+        assertEq(result, '4')
+    },
+    testAref: () => {
+        const djs = run([1, 2, 3, 4, 5, ['aref', 3]])([11, 12, 13, 14, 15])
+        const result = stringifyAsTree(sort)(djs)
+        assertEq(result, '14')
+    },
+    testArray: () => {
+        const djs = run([1, 2, 3, 4, 5, ['array', [['aref', 3], ['cref', 3]]]])([11, 12, 13, 14, 15])
+        const result = stringifyAsTree(sort)(djs)
+        assertEq(result, '[14,4]')
+    },
+    testObj: () => {
+        const djs = run([1, 2, 3, 4, 5, {"key": { "key2": ['array', [['aref', 3], ['cref', 3]]]}}])([11, 12, 13, 14, 15])
+        const result = stringifyAsTree(sort)(djs)
+        if (result !== '{"key":{"key2":[14,4]}}') { throw result }
+    },
+    testBool: () => {
+        assertEq(stringifyAsTree(sort)(run([true])([])), 'true')
+        assertEq(stringifyAsTree(sort)(run([false])([])), 'false')
+    },
+    testStr: () => {
+        assertEq(stringifyAsTree(sort)(run(['hello'])([])), '"hello"')
+    },
+    testNull: () => {
+        assertEq(stringifyAsTree(sort)(run([null])([])), 'null')
+    },
+    testBigint: () => {
+        assertEq(stringifyAsTree(sort)(run([42n])([])), '42n')
+    },
+    testUndefined: () => {
+        assertEq(stringifyAsTree(sort)(run([undefined])([])), 'undefined')
+    },
+}

package/fjs/djs/ast/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Type-level API for `fjs/djs/ast/module.f.mjs`: the AST shape `run`
+ * evaluates — `AstModule`, `AstConst`, `AstModuleRef`, `AstArray`,
+ * `AstObject`, and `AstBody`.
+ *
+ * @module
+ */
+import type { Primitive } from '../types.ts';
+/**
+ * A parsed DJS module: its imported module specifiers, in source order, and
+ * its body.
+ *
+ * The specifier list indexes `['aref', i]`.
+ */
+export type AstModule = [readonly string[], AstBody];
+/** A value in a module body: a primitive, a reference, an array, or an object. */
+export type AstConst = Primitive | AstModuleRef | AstArray | AstObject;
+/**
+ * A reference to a value defined outside this `AstConst`.
+ *
+ * - `['aref', i]` — the `i`-th argument of the body, i.e. the `i`-th imported
+ *   module of the enclosing `AstModule`.
+ * - `['cref', i]` — the `i`-th entry of the enclosing `AstBody`.
+ *
+ * Both indices are absolute and zero-based, **not** offsets from the
+ * referencing entry: in the body `[a, b, ['cref', 0]]` the reference resolves
+ * to `a`, not to the nearest preceding entry `b`.
+ *
+ * A `cref` index must be smaller than the index of the entry holding it —
+ * `run` evaluates a body left to right, so a reference to the current or a
+ * later entry is unsatisfiable. It is not rejected: it resolves to the most
+ * recently evaluated entry instead.
+ */
+export type AstModuleRef = ['aref' | 'cref', number];
+/** An array value; its elements are evaluated in order. */
+export type AstArray = ['array', readonly AstConst[]];
+/** An object value, keyed by property name. */
+export type AstObject = {
+    readonly [k in string]?: AstConst;
+};
+/**
+ * The constants of a module body, in declaration order. The **last** entry is
+ * the value the module yields; the preceding entries exist to be named by
+ * `['cref', i]`.
+ *
+ * A body describes the function
+ *
+ * ```js
+ * (...args) => { const c0 = ...; const c1 = ...; return <last> }
+ * ```
+ *
+ * where `args` are the imported modules.
+ */
+export type AstBody = readonly AstConst[];

package/fjs/djs/examples/input.f.mjs

@@ -0,0 +1,4 @@
+import c from "./m.f.mjs"
+const a = 1
+const b = 2
+export default [a, a, b, c, c]

package/fjs/djs/examples/m.f.mjs

@@ -0,0 +1 @@
+export default "text"

package/fjs/djs/module.f.d.mts

@@ -0,0 +1,17 @@
+/**
+ * High-level DJS API for parsing, transpiling, and serializing modules.
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { WriteFile, ReadFile, Write } from '../effects/node/types.ts'
+ * @import { Result } from '../types/result/types.ts'
+ * @import { Unknown } from './types.ts'
+ * @import { ParseError } from './parser/types.ts'
+ */
+import type { Effect } from '../effects/types.ts';
+import type { WriteFile, ReadFile, Write } from '../effects/node/types.ts';
+export type _CompileOp = ReadFile | WriteFile | Write;
+/** @typedef {ReadFile | WriteFile | Write} _CompileOp */
+/** @type {(args: readonly string[]) => Effect<_CompileOp, number>} */
+export declare const compile: (args: readonly string[]) => Effect<_CompileOp, number>;

package/fjs/djs/module.f.mjs

@@ -0,0 +1,47 @@
+/**
+ * High-level DJS API for parsing, transpiling, and serializing modules.
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { WriteFile, ReadFile, Write } from '../effects/node/types.ts'
+ * @import { Result } from '../types/result/types.ts'
+ * @import { Unknown } from './types.ts'
+ * @import { ParseError } from './parser/types.ts'
+ */
+
+import { transpile } from './transpiler/module.f.mjs'
+import { stringify, stringifyAsTree } from './serializer/module.f.mjs'
+import { sort } from '../types/object/module.f.mjs'
+import { pure, step } from '../effects/module.f.mjs'
+import { writeUtf8File, error } from '../effects/node/module.f.mjs'
+
+/** @typedef {ReadFile | WriteFile | Write} _CompileOp */
+
+/** @type {(args: readonly string[]) => Effect<_CompileOp, number>} */
+export const compile = args => {
+    if (args.length < 2) {
+        return step(
+            error('Error: Requires 2 or more arguments'),
+            () => pure(1))
+    }
+    const inputFileName = args[0]
+    const outputFileName = args[1]
+    return step(
+        transpile(inputFileName),
+        /** @type {(result: Result<Unknown, ParseError>) => Effect<_CompileOp, number>} */
+        (result) => {
+            if (result[0] === 'error') {
+                const metadata = result[1].metadata
+                return step(
+                    error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`),
+                    () => pure(0))
+            }
+            const content = outputFileName.endsWith('.json')
+                ? stringifyAsTree(sort)(result[1])
+                : stringify(sort)(result[1])
+            return step(
+                writeUtf8File(outputFileName, content),
+                () => pure(0))
+        })
+}

package/fjs/djs/parser/module.f.d.mts

@@ -0,0 +1,78 @@
+/**
+ * DJS parser that builds structured trees from DJS tokens.
+ *
+ * @module
+ *
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Fold } from '../../types/function/operator/types.ts'
+ * @import { DjsToken, DjsTokenWithMetadata } from '../tokenizer/types.ts'
+ * @import { OrderedMap } from '../../types/ordered_map/types.ts'
+ * @import { AstArray, AstConst, AstModule, AstModuleRef } from '../ast/types.ts'
+ * @import { TokenMetadata } from '../../js/tokenizer/types.ts'
+ * @import { ParseError } from './types.ts'
+ */
+import type { Result } from '../../types/result/types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { DjsTokenWithMetadata } from '../tokenizer/types.ts';
+import type { OrderedMap } from '../../types/ordered_map/types.ts';
+import type { AstConst, AstModule, AstModuleRef } from '../ast/types.ts';
+import type { ParseError } from './types.ts';
+export type _DjsStackArray = ['array', List<AstConst>];
+export type _DjsStackObject = ['object', OrderedMap<AstConst>, string];
+export type _DjsStackElement = _DjsStackArray | _DjsStackObject;
+export type _DjsStack = List<_DjsStackElement>;
+export type _ParserState = _InitialState | _NewLineRequiredState | _ImportState | _ConstState | _ExportState | _ParseValueState | _ResultState | _ErrorState;
+export type _ModuleState = {
+    readonly refs: OrderedMap<AstModuleRef>;
+    readonly modules: List<string>;
+    readonly consts: List<AstConst>;
+};
+export type _InitialState = {
+    readonly state: '';
+    readonly module: _ModuleState;
+};
+export type _NewLineRequiredState = {
+    readonly state: 'nl';
+    readonly module: _ModuleState;
+};
+export type _ImportState = {
+    readonly state: 'import' | 'import+name' | 'import+from';
+    readonly module: _ModuleState;
+};
+export type _ConstState = {
+    readonly state: 'const' | 'const+name';
+    readonly module: _ModuleState;
+};
+export type _ExportState = {
+    readonly state: 'export';
+    readonly module: _ModuleState;
+};
+export type _ParseValueState = {
+    readonly state: 'constValue' | 'exportValue';
+    readonly module: _ModuleState;
+    readonly valueState: '' | '[' | '[v' | '[,' | '{' | '{k' | '{:' | '{v' | '{,';
+    readonly top: _DjsStackElement | null;
+    readonly stack: _DjsStack;
+};
+export type _ResultState = {
+    readonly state: 'result';
+    readonly module: _ModuleState;
+};
+export type _ErrorState = {
+    readonly state: 'error';
+    readonly error: ParseError;
+};
+/** @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>} */
+export declare const parseFromTokens: (tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>;
+export declare const proof: {
+    pushKey: {
+        nonObjectTop: () => void;
+    };
+    endArray: {
+        nonArrayTop: () => void;
+    };
+    endObject: {
+        nonObjectTop: () => void;
+    };
+};