add TextIndexExtensions.zero() utility (#1440)

add `TextIndexExtensions.zero()` utility to create an index at offset
zero, which is useful for creating cursors from child nodes where parent
offset is not needed.

The API already exists in Rust, so this just exposes it to TypeScript.

See the discussion in #1439 for more information.

Author: OmarTawfik

.changeset/many-rivers-attack.md

@@ -0,0 +1,5 @@
+---
+"@nomicfoundation/slang": minor
+---
+
+add `TextIndexExtensions.zero()` utility to create an index at offset zero, which is useful for creating cursors from child nodes where parent offset is not needed.

crates/metaslang/cst/src/text_index.rs

@@ -28,7 +28,7 @@ pub struct TextIndex {
 }
 
 impl TextIndex {
-    /// Shorthand for `TextIndex { utf8: 0, utf16: 0, line: 0, char: 0 }`.
+    /// Creates a text index with zero offsets.
     pub const ZERO: TextIndex = TextIndex {
         utf8: 0,
         utf16: 0,

crates/solidity/outputs/cargo/wasm/src/wasm_crate/interface/cst.generated.wit

@@ -278,6 +278,12 @@ interface cst {
         column: u32,
     }
 
+    //// Useful extension methods for working with text indices.
+    resource text-index-extensions {
+        /// Creates a text index with zero offsets.
+        zero: static func() -> text-index;
+    }
+
     /// Represents a range in the source text.
     record text-range {
         /// Starting (inclusive) position of the range.

crates/solidity/outputs/cargo/wasm/src/wasm_crate/interface/cst.wit.jinja2

@@ -9,10 +9,10 @@ mod ffi {
         AncestorsIterator, AncestorsIteratorBorrow, Cursor, CursorBorrow, CursorIterator,
         CursorIteratorBorrow, Edge, EdgeBorrow, EdgeLabel, Guest, GuestAncestorsIterator,
         GuestCursor, GuestCursorIterator, GuestEdge, GuestNonterminalNode, GuestQuery,
-        GuestQueryMatchIterator, GuestTerminalKindExtensions, GuestTerminalNode, Node,
-        NonterminalKind, NonterminalNode, NonterminalNodeBorrow, Query, QueryBorrow, QueryError,
-        QueryMatch, QueryMatchIterator, QueryMatchIteratorBorrow, TerminalKind, TerminalNode,
-        TerminalNodeBorrow, TextIndex, TextRange,
+        GuestQueryMatchIterator, GuestTerminalKindExtensions, GuestTerminalNode,
+        GuestTextIndexExtensions, Node, NonterminalKind, NonterminalNode, NonterminalNodeBorrow,
+        Query, QueryBorrow, QueryError, QueryMatch, QueryMatchIterator, QueryMatchIteratorBorrow,
+        TerminalKind, TerminalNode, TerminalNodeBorrow, TextIndex, TextRange,
     };
 }
 
@@ -38,6 +38,8 @@ impl ffi::Guest for crate::wasm_crate::World {
 
     type Query = QueryWrapper;
     type QueryMatchIterator = QueryMatchIteratorWrapper;
+
+    type TextIndexExtensions = TextIndexExtensionsWrapper;
 }
 
 //================================================
@@ -478,6 +480,20 @@ impl FromFFI<rust::TextIndex> for &ffi::TextIndex {
     }
 }
 
+//================================================
+//
+// resource text-index-extensions
+//
+//================================================
+
+pub struct TextIndexExtensionsWrapper;
+
+impl ffi::GuestTextIndexExtensions for TextIndexExtensionsWrapper {
+    fn zero() -> ffi::TextIndex {
+        crate::rust_crate::cst::TextIndex::ZERO._into_ffi()
+    }
+}
+
 //================================================
 //
 // record text-range

crates/solidity/outputs/cargo/wasm/src/wasm_crate/wrappers/cst/mod.rs

@@ -81,5 +81,10 @@ export type QueryMatchIterator = wasm.cst.QueryMatchIterator;
 /** {@inheritDoc wasm.cst.TextIndex} */
 export type TextIndex = wasm.cst.TextIndex;
 
+/** {@inheritDoc wasm.cst.TextIndexExtensions} */
+export const TextIndexExtensions = wasm.cst.TextIndexExtensions;
+/** {@inheritDoc wasm.cst.TextIndexExtensions} */
+export type TextIndexExtensions = wasm.cst.TextIndexExtensions;
+
 /** {@inheritDoc wasm.cst.TextRange} */
 export type TextRange = wasm.cst.TextRange;

crates/solidity/outputs/npm/package/src/cst/index.mts

@@ -0,0 +1,12 @@
+import { TextIndexExtensions } from "@nomicfoundation/slang/cst";
+
+it("zero()", () => {
+  const zero = TextIndexExtensions.zero();
+
+  expect(zero).toEqual({
+    utf8: 0,
+    utf16: 0,
+    line: 0,
+    column: 0,
+  });
+});