@mica-js/ddl 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalEcho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @mica-js/ddl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-compatible TypeScript ESM frontend for self-contained Mica DDL devices. The Langium grammar and generated AST/services implement the language syntax. The compiler lowers that AST directly to canonical structured `DeviceIR`, retaining one-based UTF-16 source ranges, then calls `@mica-js/device-model`'s shared validator for type, scope, effect, dependency, and control-flow checks. Invalid input throws `BuildError`; no partial IR is returned.
+
+```typescript
+import { compileDDL, generateDeviceTypeScript } from '@mica-js/ddl';
+
+const model = await compileDDL('device Counter { state count: number = 0; }', {
+  uri: 'file:///devices/counter.ddl',
+});
+const types = generateDeviceTypeScript(model);
+```
+
+`compileDDL(source, { uri? })` returns `Promise<DeviceIR>` and rejects with `BuildError` for invalid input. `generateDeviceTypeScript(model, { deviceModule?, name? })` produces a type-only ESM module exporting device-specific props, property inputs, channels, notifications, public memory, context, batches, adapter, and factory types. `generateDeviceTypes` is an alias. The generated imports default to `@mica-js/simulator/device`; `deviceModule` may select another SDK facade. Bytes inputs use `Uint8Array`, while snapshots and public memory use the SDK's `ReadonlyBytes` and `BorrowedBytes`.
+
+Compilation reuses one Langium parser. A source-and-URI-keyed LRU retains at most 32 validated immutable models and 256 Ki UTF-16 code units of keys; individual keys above 64 Ki code units bypass caching. Repeated successful calls may share the same frozen IR snapshot. Failures are never cached, and distinct URIs retain independent source locations and diagnostics.
+
+`createDDLServices()` exposes the generated Langium core services without a Node filesystem or language-server dependency. Grammar changes require `pnpm generate`; generated files in `src/generated` are tracked. Run `pnpm typecheck` and `pnpm build` after regeneration. Build the shared device-model dependency first.

package/dist/compiler.d.ts

@@ -0,0 +1,57 @@
+import type { AstNode } from 'langium';
+import { type DeviceIR, type SourceInfo } from '@mica-js/device-model';
+import type * as AST from './generated/ast.js';
+/** Lowers Langium's structured AST directly into the canonical operation regions. */
+export declare class DDLCompiler {
+    private readonly device;
+    private readonly uri;
+    private readonly symbols;
+    private readonly types;
+    private readonly resolving;
+    private readonly sources;
+    private readonly valueTypes;
+    constructor(device: AST.Device, uri: string);
+    source(node: AstNode): SourceInfo;
+    private fail;
+    private checkName;
+    private type;
+    private parameterType;
+    private context;
+    private child;
+    private emit;
+    private value;
+    private constant;
+    private expect;
+    private describe;
+    private symbolType;
+    private bind;
+    private resource;
+    private resourceKind;
+    private read;
+    private number;
+    private string;
+    private fieldType;
+    private expression;
+    private infer;
+    private binary;
+    private select;
+    private args;
+    private call;
+    private factKey;
+    private facts;
+    private initializer;
+    private await;
+    private markValue;
+    private block;
+    private statement;
+    private ifStatement;
+    private pattern;
+    private match;
+    private loop;
+    private computation;
+    private options;
+    private staticNumber;
+    private sourceType;
+    compile(): DeviceIR;
+}
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAQL,KAAK,QAAQ,EASb,KAAK,UAAU,EAGhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,KAAK,GAAG,MAAM,oBAAoB,CAAC;AAyK/C,qFAAqF;AACrF,qBAAa,WAAW;IAQpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6C;gBAGrD,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,GAAG,EAAE,MAAM;IAW9B,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU;IAiBjC,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,IAAI;IA8BZ,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,UAAU;IA6BlB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,IAAI;IAwCZ,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,UAAU;IAwKlB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,MAAM;IA8Gd,OAAO,CAAC,MAAM;IAgCd,OAAO,CAAC,IAAI;IA0BZ,OAAO,CAAC,IAAI;IAyHZ,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,KAAK;IAsBb,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,KAAK;IAgBb,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,SAAS;IAwIjB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,KAAK;IAoCb,OAAO,CAAC,IAAI;IAoCZ,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,UAAU;IAgBlB,OAAO,IAAI,QAAQ;CA0PpB"}