sandstone 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/flow/loop.d.ts

@@ -1,10 +1,11 @@
-import type { SubCommand } from "../commands/index.js";
-import type { SandstoneCore } from "../core/index.js";
+import type { MCFunctionNode, SandstoneCore } from "../core/index.js";
 import { ContainerNode } from "../core/index.js";
+import type { ConditionNode } from "./conditions/index.js";
 export declare class LoopNode extends ContainerNode {
-    executeArgs: SubCommand[];
+    condition: ConditionNode;
     callback: () => void;
     loopback: () => void;
-    constructor(sandstoneCore: SandstoneCore, executeArgs: SubCommand[], callback: () => void, loopback: () => void);
+    parentMCFunction: MCFunctionNode;
+    constructor(sandstoneCore: SandstoneCore, condition: ConditionNode, callback: () => void, loopback: () => void);
     getValue: () => never;
 }

package/dist/flow/loops/for_i.d.ts

@@ -1,6 +1,6 @@
 import type { SandstoneCore } from "../../core/sandstoneCore.js";
 import type { Score } from "../../variables/index.js";
-import type { Condition } from '..';
+import { type Condition } from '..';
 import { LoopNode } from "../loop.js";
 export declare class ForINode extends LoopNode {
     constructor(sandstoneCore: SandstoneCore, initialValue: number | Score, endCondition: (iterator: Score) => Condition, iterate: (iterator: Score) => Score, callback: (iterator: number | Score, _continue: () => void) => any);

package/dist/flow/loops/for_of.d.ts

@@ -20,14 +20,15 @@ export type ForOfIterate<ITERATOR extends ForOfIterator> = ITERATOR extends 'ent
     never
 ];
 export declare class ForOfNode<ITERATOR extends ForOfIterator, ITERATE extends ForOfIterate<ForOfIterator>> extends LoopNode {
-    constructor(sandstoneCore: SandstoneCore, iteratorType: ITERATOR, iterable: IterableDataClass, callback: (...args: ITERATE) => any);
+    constructor(sandstoneCore: SandstoneCore, iteratorType: ITERATOR, direction: 'normal' | 'reverse', iterable: IterableDataClass<ITERATOR extends string[] ? ITERATOR[0] extends 'key' ? 'map' : ('list' | 'map') : ('list' | 'map')>, callback: (...args: ITERATE) => any);
 }
 export declare class ForOfStatement<ITERATOR extends ForOfIterator, ITERATE extends ForOfIterate<ForOfIterator>> {
     protected sandstoneCore: SandstoneCore;
     protected iteratorType: ITERATOR;
-    protected iterable: IterableDataClass;
+    protected direction: 'normal' | 'reverse';
+    protected iterable: IterableDataClass<ITERATOR extends string[] ? ITERATOR[0] extends 'key' ? 'map' : ('list' | 'map') : ('list' | 'map')>;
     protected callback: (...args: ITERATE) => any;
     protected node: ForOfNode<ITERATOR, ITERATE>;
-    constructor(sandstoneCore: SandstoneCore, iteratorType: ITERATOR, iterable: IterableDataClass, callback: (...args: ITERATE) => any);
+    constructor(sandstoneCore: SandstoneCore, iteratorType: ITERATOR, direction: 'normal' | 'reverse', iterable: IterableDataClass<ITERATOR extends string[] ? ITERATOR[0] extends 'key' ? 'map' : ('list' | 'map') : ('list' | 'map')>, callback: (...args: ITERATE) => any);
     protected getNode: () => ForOfNode<ITERATOR, ITERATE>;
 }

package/dist/flow/loops/staticAnalysis.d.ts

@@ -0,0 +1,26 @@
+import type { ConditionNode } from '..';
+import type { Score } from "../../variables/index.js";
+/**
+ * Result of static condition analysis.
+ * - `{ canAnalyze: false }` - condition references other variables or can't be analyzed
+ * - `{ canAnalyze: true, result: boolean }` - condition was evaluated statically
+ */
+export type AnalysisResult = {
+    canAnalyze: false;
+} | {
+    canAnalyze: true;
+    result: boolean;
+};
+/**
+ * Recursively analyzes a condition node to check if it only references the given score
+ * and evaluates to true/false for the given value.
+ */
+export declare function analyzeCondition(condition: ConditionNode, targetScore: Score, value: number, negated?: boolean): AnalysisResult;
+/**
+ * Gets a user-friendly location string from a stack trace, filtering out internal files.
+ */
+export declare function getDeclarationLocation(): string;
+/**
+ * Warns about a statically false loop condition.
+ */
+export declare function warnStaticallyFalseCondition(loopType: string, details: string): void;

package/dist/flow/loops/while.d.ts

@@ -1,5 +1,5 @@
 import type { SandstoneCore } from "../../core/index.js";
-import type { ConditionNode } from '..';
+import { type ConditionNode } from '..';
 import { LoopNode } from "../loop.js";
 export declare class WhileNode extends LoopNode {
     constructor(sandstoneCore: SandstoneCore, condition: ConditionNode, callback: () => void);

package/dist/flow/switch_case.d.ts

@@ -1,16 +1,98 @@
 import type { NBTObject } from "../arguments/index.js";
-export type DefaultType<ValueType extends number | NBTObject> = {
-    cases: CaseStatement<ValueType>[];
+import type { DataPointPickClass, MCFunctionNode, SandstoneCore } from "../core/index.js";
+import { ContainerNode } from "../core/index.js";
+import type { DataPointClass } from "../variables/index.js";
+import { Score } from "../variables/index.js";
+import type { Condition } from "./Flow.js";
+/** A condition callback that receives the switch value and returns a condition */
+export type ConditionCallback<ValueType> = (value: ValueType) => Condition;
+/** Widen literal types to their base types for better inference */
+type Widen<T> = T extends number ? number : T;
+/** Static value case */
+type StaticCaseEntry<CheckType> = {
+    type: 'static';
+    value: Widen<CheckType>;
+    callback: () => any;
+};
+/** Condition callback case */
+type ConditionCaseEntry<ValueType> = {
+    type: 'condition';
+    condition: ConditionCallback<ValueType>;
+    callback: () => any;
+};
+/** Either a static or condition case entry */
+type CaseEntry<ValueType, CheckType> = StaticCaseEntry<CheckType> | ConditionCaseEntry<ValueType>;
+/** Static value case tuple */
+export type StaticCase<CheckType> = readonly [
+    'case',
+    Widen<CheckType>,
+    () => any
+];
+/** Condition callback case tuple */
+export type ConditionCase<ValueType> = readonly [
+    'case',
+    ConditionCallback<ValueType>,
+    () => any
+];
+/** Either a static or condition case */
+export type SwitchCase<ValueType, CheckType> = StaticCase<CheckType> | ConditionCase<ValueType>;
+export type DefaultType<ValueType extends number | NBTObject, SwitchValueType = unknown> = {
+    entries: CaseEntry<SwitchValueType, ValueType>[];
     default: () => any;
 };
-export declare class CaseStatement<ValueType extends number | NBTObject> {
-    readonly value: ValueType;
-    readonly callback: () => any;
-    readonly previous?: CaseStatement<ValueType>[] | undefined;
-    constructor(value: ValueType, callback: () => any, previous?: CaseStatement<ValueType>[] | undefined);
-    case(value: ValueType, callback: () => any): CaseStatement<ValueType>;
-    default(callback: () => any): {
-        cases: CaseStatement<ValueType>[];
-        default: () => any;
-    };
+export declare class CaseStatement<ValueType extends number | NBTObject, SwitchValueType = unknown> {
+    readonly entries: CaseEntry<SwitchValueType, ValueType>[];
+    constructor(entries?: CaseEntry<SwitchValueType, ValueType>[]);
+    /** Add a static value case */
+    case(value: ValueType, callback: () => any): CaseStatement<ValueType, SwitchValueType>;
+    /** Add a condition case - checked after static cases fail. Use generic to specify switch value type on first condition: `.case<Score>(v => ...)` */
+    case<T = SwitchValueType>(condition: ConditionCallback<T>, callback: () => any): CaseStatement<ValueType, T>;
+    default(callback: () => any): DefaultType<ValueType, SwitchValueType>;
+}
+/**
+ * AST node representing a switch statement.
+ * Transformed into MCFunctions by SwitchTransformationVisitor during save().
+ */
+export declare class SwitchNode extends ContainerNode {
+    value: DataPointClass | DataPointPickClass | Score;
+    staticCases: StaticCaseNode[];
+    conditionCases: ConditionCaseNode[];
+    defaultCase: DefaultCaseNode | undefined;
+    parentMCFunction: MCFunctionNode;
+    constructor(sandstoneCore: SandstoneCore, value: DataPointClass | DataPointPickClass | Score, staticCases: StaticCaseNode[], conditionCases: ConditionCaseNode[], defaultCase: DefaultCaseNode | undefined);
+    getValue: () => never;
+}
+/**
+ * AST node representing a static value case in a switch statement.
+ */
+export declare class StaticCaseNode extends ContainerNode {
+    value: number | NBTObject;
+    callback: () => any;
+    constructor(sandstoneCore: SandstoneCore, value: number | NBTObject, callback: () => any);
+    getValue: () => null;
+}
+/**
+ * AST node representing a condition-based case in a switch statement.
+ */
+export declare class ConditionCaseNode extends ContainerNode {
+    condition: ConditionCallback<any>;
+    callback: () => any;
+    constructor(sandstoneCore: SandstoneCore, condition: ConditionCallback<any>, callback: () => any);
+    getValue: () => null;
+}
+/**
+ * AST node representing the default case in a switch statement.
+ */
+export declare class DefaultCaseNode extends ContainerNode {
+    callback: () => any;
+    constructor(sandstoneCore: SandstoneCore, callback: () => any);
+    getValue: () => null;
 }
+export declare function executeSwitch<ValueType extends DataPointClass | DataPointPickClass | Score, CheckType extends ValueType extends Score ? number : NBTObject>(sandstoneCore: SandstoneCore, value: ValueType, _cases: SwitchCase<ValueType, CheckType>[] | [
+    ...SwitchCase<ValueType, CheckType>[],
+    [
+        'default',
+        () => any
+    ]
+] | CaseStatement<CheckType, ValueType> | DefaultType<CheckType, ValueType>): void;
+export {};

package/dist/index.d.ts

@@ -1612,13 +1612,13 @@ export declare const RawResource: {
     (nbt: import(".").DataPointClass, scale?: number, name?: string): import(".").Score;
 }, flowVariable: import(".").Score, Trigger: (name: string, callback: import("./variables/index.js").TriggerHandler, pollingEvery?: number) => import("./variables/index.js").TriggerClass<import("./variables").TriggerHandler>, Label: (label: `${any}${string}` | `${string}:${string}`, description?: `${any}${string}`) => import("./utils.js").MakeInstanceCallable<import("./variables")._RawLabelClass>, Data: {
     <T extends import("./variables/index.js").DATA_TYPES>(type: T): import("./variables/index.js").TargetlessDataClass<T>;
-    <T extends "entity">(type: T, target: import(".").SingleEntityArgument<false>): import("./variables/index.js").DataClass<T>;
-    <T extends "storage">(type: T, target: import("./core/index.js").MacroArgument | string): import("./variables/index.js").DataClass<T>;
-    <T extends "block">(type: T, target: import(".").Coordinates<false>): import("./variables/index.js").DataClass<T>;
+    <T extends "entity", S extends string>(type: T, target: import("./variables/index.js").TargetFor<T, S>): import("./variables/index.js").DataClass<T>;
+    <T extends "storage">(type: T, target: import("./core/index.js").MacroArgument | import("./variables/index.js").TargetFor<T, string>): import("./variables/index.js").DataClass<T>;
+    <T extends "block">(type: T, target: import("./variables/index.js").TargetFor<T, string>): import("./variables/index.js").DataClass<T>;
     <T extends import("./variables/index.js").DATA_TYPES>(type: T, target: undefined, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import("./variables/index.js").TargetlessDataPointClass<T>;
-    <T extends "entity">(type: T, target: import(".").SingleEntityArgument<false>, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
-    <T extends "storage">(type: T, target: import("./core/index.js").MacroArgument | string, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
-    <T extends "block">(type: T, target: import(".").Coordinates<false>, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
+    <T extends "entity", S extends string>(type: T, target: import("./variables/index.js").TargetFor<T, S>, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
+    <T extends "storage">(type: T, target: import("./core/index.js").MacroArgument | import("./variables/index.js").TargetFor<T, string>, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
+    <T extends "block">(type: T, target: import("./variables/index.js").TargetFor<T, string>, path: import("./core/index.js").MacroArgument | import("./variables/index.js").DATA_PATH | import("./variables/index.js").DATA_PATH[]): import(".").DataPointClass<T>;
 }, DataVariable: {
     (initialValue?: import(".").NBTObject | import(".").DataPointClass<any> | import("./core/index.js").DataPointPickClass, name?: string): import(".").DataPointClass<"storage">;
     (score: import(".").Score, storeType?: import("./commands/index.js").StoreType, scale?: number, name?: string): import(".").DataPointClass<"storage">;