@tsplc/compiler 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  analyze,
+  typeCheckOnly,
+  checkHostConfig,
+  type FrontendOptions,
+  type FrontendResult,
+} from "./frontend/typescript.ts";

package/stdlib/clock.ts

@@ -0,0 +1,2 @@
+/** Milliseconds since the process started, as the PLC's `now()` counts them; used when a program runs under Bun. */
+export const now = (): number => Math.floor(performance.now());

package/stdlib/math.ts

@@ -0,0 +1,19 @@
+// PLC implementation source: the frontend specializes these helpers for each
+// concrete scalar domain. The release includes this source for that analysis.
+export function min<T extends number | bigint>(left: T, right: T): T {
+  return left < right ? left : right;
+}
+
+export function max<T extends number | bigint>(left: T, right: T): T {
+  return left > right ? left : right;
+}
+
+export function clamp<T extends number | bigint>(value: T, lower: T, upper: T): T {
+  if (value < lower) {
+    return lower;
+  }
+  if (value > upper) {
+    return upper;
+  }
+  return value;
+}

package/types/async.d.ts

@@ -0,0 +1,81 @@
+import type { BOOL, TIME, UDINT } from "./index.d.ts";
+
+export interface BackgroundSnapshot<T> {
+  valid: BOOL;
+  busy: BOOL;
+  done: BOOL;
+  cancelRequested: BOOL;
+  error: UDINT;
+  result: T;
+}
+export interface BackgroundTask<A extends unknown[], R> {
+  (...arguments_: A): Promise<R>;
+  start(...arguments_: A): BOOL;
+  snapshot(): BackgroundSnapshot<R>;
+  cancel(): BOOL;
+  reset(): BOOL;
+}
+export declare const backgroundTasks: {
+  define<A extends unknown[], R>(
+    work: (...arguments_: A) => Promise<R>,
+    options: { interval: TIME; priority: number },
+  ): BackgroundTask<A, R>;
+};
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface FetchOptions<Request> {
+  method?: HttpMethod;
+  json?: Request;
+}
+/** Fetch a bounded JSON response. URL and method must be compile-time values. */
+export declare function fetch<Response, Request = unknown>(
+  url: string,
+  options?: FetchOptions<Request>,
+): Promise<Response>;
+export declare function sleep(duration: TIME): Promise<void>;
+
+/** The PLC's view of a tRPC router: each procedure is an async call. */
+export type ServiceClient<Procedures> = {
+  [Key in keyof Procedures]: Procedures[Key] extends {
+    _def: { $types: { input: infer Input; output: infer Output } };
+  }
+    ? (input: Input) => Promise<Output>
+    : ServiceClient<Procedures[Key]>;
+};
+/**
+ * Calls the server router's `meta({ plc: true })` procedures, like a tRPC client. Import the
+ * router's type with `import type`; tsPLC reads each call's wire layout from it.
+ */
+export declare function createServiceClient<
+  Router extends { _def: { record: object } },
+>(): ServiceClient<Router["_def"]["record"]>;
+
+/** Cancel pending continuations in a controller or the current module. */
+export declare function cancelAsync(owner?: object): void;
+export declare function asyncDiagnostics(): { valid: BOOL; count: UDINT; lastError: UDINT };
+export declare function errorCode(reason: unknown): UDINT;
+export interface Task<A extends unknown[], R> {
+  /** Starts the work. False while the task is busy or holds an unread result. */
+  start(...arguments_: A): BOOL;
+  /** The current state. After `cancel` it completes with error 1 and no result. */
+  snapshot(): BackgroundSnapshot<R>;
+  /** Discards the work or its unread result. False when the task is idle. */
+  cancel(): BOOL;
+  /** Clears a finished task so it can start again. False while it is busy. */
+  reset(): BOOL;
+}
+/** One named, cancellable invocation of async work, advanced in the owner's scan task. */
+export declare const tasks: {
+  define<A extends unknown[], R>(work: (...arguments_: A) => Promise<R>): Task<A, R>;
+};
+/** @internal Compiler-owned, bounded continuation slots. */
+export declare const cooperativeTasks: {
+  define<A extends unknown[], R>(
+    work: (...arguments_: A) => Promise<R>,
+  ): { start(...arguments_: A): void; cancel(): void };
+};
+
+/** @internal Generated OPC UA service calls use the same async continuation model. */
+export declare function opcuaCall<Response, Request>(
+  path: string,
+  request: Request,
+): Promise<Response>;

package/types/clock.d.ts

@@ -0,0 +1,4 @@
+import type { DINT } from "./index.d.ts";
+
+/** Milliseconds since the PLC runtime started. It wraps after 24.8 days, so compare times by subtracting: `now() - since >= 500`. */
+export declare function now(): DINT;

package/types/config.d.ts

@@ -0,0 +1,2 @@
+/** Resolve a required string environment value when compiling module configuration. */
+export declare const env: <T extends string>(name: string) => T;

package/types/data-types.d.ts

@@ -0,0 +1,31 @@
+export {};
+
+// The IEC data types alone, for host code that reads PLC declarations but must not see names that exist only in PLC programs.
+declare global {
+  type BOOL = import("./index").BOOL;
+  type SINT = import("./index").SINT;
+  type USINT = import("./index").USINT;
+  type INT = import("./index").INT;
+  type UINT = import("./index").UINT;
+  type DINT = import("./index").DINT;
+  type UDINT = import("./index").UDINT;
+  type LINT = import("./index").LINT;
+  type ULINT = import("./index").ULINT;
+  type BYTE = import("./index").BYTE;
+  type WORD = import("./index").WORD;
+  type DWORD = import("./index").DWORD;
+  type LWORD = import("./index").LWORD;
+  type REAL = import("./index").REAL;
+  type LREAL = import("./index").LREAL;
+  type TIME = import("./index").TIME;
+  type DATE = import("./index").DATE;
+  type TIME_OF_DAY = import("./index").TIME_OF_DAY;
+  type DATE_AND_TIME = import("./index").DATE_AND_TIME;
+  type FixedArray<T, N extends number, Lower extends number = 0> = import("./index").FixedArray<
+    T,
+    N,
+    Lower
+  >;
+  type STRING<N extends number> = import("./index").STRING<N>;
+  type WSTRING<N extends number> = import("./index").WSTRING<N>;
+}

package/types/globals.d.ts

@@ -0,0 +1,40 @@
+import "./data-types";
+
+// Ambient spellings point to the canonical SDK types; the frontend checks this
+// declaration identity rather than trusting a same-named user alias.
+declare global {
+  interface VoidFunction {
+    (): void;
+  }
+  type Input<T> = import("./index").Input<T>;
+  type Output<T> = import("./index").Output<T>;
+
+  type InOut<T> = import("./index").InOut<T>;
+  type FunctionBlock<I, O = Record<never, never>> = import("./index").FunctionBlock<I, O>;
+  const FunctionBlock: typeof import("./index").FunctionBlock;
+  type Blinker = import("./index").Blinker;
+  const Blinker: typeof import("./index").Blinker;
+  type OnDelayTimer = import("./index").OnDelayTimer;
+  const OnDelayTimer: typeof import("./index").OnDelayTimer;
+  type OffDelayTimer = import("./index").OffDelayTimer;
+  const OffDelayTimer: typeof import("./index").OffDelayTimer;
+  type PulseTimer = import("./index").PulseTimer;
+  const PulseTimer: typeof import("./index").PulseTimer;
+  type RisingEdge = import("./index").RisingEdge;
+  const RisingEdge: typeof import("./index").RisingEdge;
+  type FallingEdge = import("./index").FallingEdge;
+  const FallingEdge: typeof import("./index").FallingEdge;
+  const ref: typeof import("./index").ref;
+  const retain: typeof import("./index").retain;
+  const ms: typeof import("./index").ms;
+  const seconds: typeof import("./index").seconds;
+  const minutes: typeof import("./index").minutes;
+  const timeToMilliseconds: typeof import("./index").timeToMilliseconds;
+  const date: typeof import("./index").date;
+  const timeOfDay: typeof import("./index").timeOfDay;
+  const dateAndTime: typeof import("./index").dateAndTime;
+
+  const defaultValue: typeof import("./index").defaultValue;
+  const copy: typeof import("./index").copy;
+  const entries: typeof import("./index").entries;
+}

package/types/index.d.ts

@@ -0,0 +1,111 @@
+// Canonical PLC declarations: TypeScript supplies editor/checker compatibility;
+// the compiler preserves scalar domains and lowers intrinsics without JS execution.
+export type BOOL = boolean;
+export type SINT = number;
+export type USINT = number;
+export type INT = number;
+export type UINT = number;
+export type DINT = number;
+export type UDINT = number;
+export type LINT = bigint;
+export type ULINT = bigint;
+export type BYTE = number;
+export type WORD = number;
+export type DWORD = number;
+export type LWORD = bigint;
+export type REAL = number;
+export type LREAL = number;
+export type Input<T> = T;
+export type Output<T> = T;
+
+// Conversions and arithmetic state their overflow policy explicitly.
+export declare function exact<T extends number | bigint>(value: number | bigint): T;
+export declare function wrap<T extends number | bigint>(value: number | bigint): T;
+// Float-to-float saturation clips to finite target endpoints, then rounds to its width.
+export declare function saturate<T extends number | bigint>(value: number | bigint): T;
+export declare function wrapAdd<T extends number | bigint>(left: T, right: T): T;
+export declare function wrapSubtract<T extends number | bigint>(left: T, right: T): T;
+export declare function wrapMultiply<T extends number | bigint>(left: T, right: T): T;
+export declare function saturatingAdd<T extends number | bigint>(left: T, right: T): T;
+export declare function saturatingSubtract<T extends number | bigint>(left: T, right: T): T;
+export declare function saturatingMultiply<T extends number | bigint>(left: T, right: T): T;
+export declare function div<T extends number | bigint>(left: T, right: T): T;
+
+// Capacity and bounds are compiler metadata, erased by the TypeScript checker.
+export type FixedArray<T, _N extends number, _Lower extends number = 0> = T[];
+export type STRING<_N extends number> = string;
+export type WSTRING<_N extends number> = string;
+export declare function defaultValue<T>(): T;
+export declare function copy<T>(value: T): T;
+// `for (const [key, element] of entries(record))` iterates an enum-keyed Record by key.
+export declare function entries<K extends number, T>(record: Record<K, T>): [K, T][];
+
+declare const timeBrand: unique symbol;
+declare const calendarBrand: unique symbol;
+export type TIME = number & { readonly [timeBrand]: "TIME" };
+export type DATE = string & { readonly [calendarBrand]: "DATE" };
+export type TIME_OF_DAY = string & { readonly [calendarBrand]: "TIME_OF_DAY" };
+export type DATE_AND_TIME = string & { readonly [calendarBrand]: "DATE_AND_TIME" };
+
+// Borrowing and retained storage are checked by the compiler, not JS wrappers.
+export type InOut<T> = T;
+export declare function ref<T>(value: T): InOut<T>;
+export declare function retain<T>(value: T): T;
+
+export declare function ms(value: number): TIME;
+export declare function seconds(value: number): TIME;
+export declare function minutes(value: number): TIME;
+// TIME stores unsigned 32-bit milliseconds; this preserves that complete range.
+export declare function timeToMilliseconds(value: TIME): UDINT;
+export declare function date(value: string): DATE;
+export declare function timeOfDay(value: string): TIME_OF_DAY;
+export declare function dateAndTime(value: string): DATE_AND_TIME;
+
+// The empty output schema makes execute return void for outputless blocks.
+export declare abstract class FunctionBlock<I, O = Record<never, never>> {
+  readonly out: Readonly<O>;
+  update(input: I): void;
+  protected abstract execute(input: I): keyof O extends never ? void : O;
+}
+
+/** Alternates `on` while enabled: off for `offTime`, then on for `onTime`. Keeps its last `on` when disabled. CODESYS Util.BLINK. */
+export declare class Blinker extends FunctionBlock<
+  { enabled: BOOL; offTime: TIME; onTime: TIME },
+  { on: BOOL }
+> {
+  protected execute(input: { enabled: BOOL; offTime: TIME; onTime: TIME }): { on: BOOL };
+}
+
+/** `done` once `enabled` has held for `duration`; resets when `enabled` drops. `elapsed` stops at `duration`. IEC TON. */
+export declare class OnDelayTimer extends FunctionBlock<
+  { enabled: BOOL; duration: TIME },
+  { done: BOOL; elapsed: TIME }
+> {
+  protected execute(input: { enabled: BOOL; duration: TIME }): { done: BOOL; elapsed: TIME };
+}
+
+/** `active` while `enabled`, and for `duration` after it drops. IEC TOF. */
+export declare class OffDelayTimer extends FunctionBlock<
+  { enabled: BOOL; duration: TIME },
+  { active: BOOL; elapsed: TIME }
+> {
+  protected execute(input: { enabled: BOOL; duration: TIME }): { active: BOOL; elapsed: TIME };
+}
+
+/** `active` for `duration` from a rising `start`; `start` is ignored while active. IEC TP. */
+export declare class PulseTimer extends FunctionBlock<
+  { start: BOOL; duration: TIME },
+  { active: BOOL; elapsed: TIME }
+> {
+  protected execute(input: { start: BOOL; duration: TIME }): { active: BOOL; elapsed: TIME };
+}
+
+/** `rose` for the one update where `signal` goes from false to true. IEC R_TRIG. */
+export declare class RisingEdge extends FunctionBlock<{ signal: BOOL }, { rose: BOOL }> {
+  protected execute(input: { signal: BOOL }): { rose: BOOL };
+}
+
+/** `fell` for the one update where `signal` goes from true to false. IEC F_TRIG. */
+export declare class FallingEdge extends FunctionBlock<{ signal: BOOL }, { fell: BOOL }> {
+  protected execute(input: { signal: BOOL }): { fell: BOOL };
+}

package/types/plc.d.ts

@@ -0,0 +1,5 @@
+/** Sample an explicitly named, read-only telemetry record from the cyclic caller task. */
+export declare function expose<const T extends Record<string, boolean | number | string>>(
+  name: string,
+  telemetry: T,
+): void;