type¶

YanmaJS の埋め込み API (Context / value.md の各関数) が公開する型のリファレンスです。すべて @import("yanmajs") 経由で yanmajs.Xxx としてアクセスできます。

Value¶

JavaScript の値を表す NaN-boxed なオパーク値です。

pub const Value = u64;

内部的には IEEE754 double の NaN ビットパターンを利用して、数値以外(整数・真偽値・null・undefined・オブジェクトへのポインタなど)を 1 ワードに埋め込んでいます。フィールドへ直接アクセスしてはならず、必ず value.md に列挙する make* / to* / is* 系関数を介して生成・変換・判定します。オブジェクト系(文字列・配列・関数など)を指す Value は GC 管理下のヒープオブジェクトへの参照であり、ルート(後述の HandleScope / PersistentHandle)されない限り GC で回収され得ます。

HostFn / HostMethod¶

Zig 側で実装し、JavaScript から呼び出せる関数の型です。

pub const HostFn = *const fn (ctx: *Context, args: []const Value) anyerror!Value;

pub const HostMethod = *const fn (ctx: *Context, this: Value, args: []const Value) anyerror!Value;

HostMethod はメソッドとして呼ばれた場合の this をそのまま(プリミティブでもボクシングせず)受け取ります。グローバル関数として呼ばれた場合の this は undefined です。戻り値がエラーを返した場合の扱いは error を参照してください。

EvalError¶

eval / runScript / evalModule / callFunction が返すエラーセットです。

pub const EvalError = error{
    OutOfMemory,
    StackOverflow,
    ArityMismatch,
    CallStackOverflow,
    TryStackOverflow,
    UncaughtException,
    JumpTooLarge,
    NotCallable,
    RuntimeError,
};

各バリアントの発生条件は error を参照してください。

PropertyDescriptor¶

Context.defineProperty に渡すプロパティ記述子です。

pub const PropertyDescriptor = struct {
    value: ?Value = null,
    getter: ?Value = null,
    setter: ?Value = null,
    writable: ?bool = null,
    enumerable: ?bool = null,
    configurable: ?bool = null,
};

getter または setter のいずれかが非 null の場合はアクセサプロパティとして定義され、value/writable は無視されます。それ以外はデータプロパティとして定義されます。

CompiledScript¶

Context.compileScript / deserializeScript が返すコンパイル済みスクリプトです。

pub const CompiledScript = struct {
    function: *ObjFunction,
};

内部的にはトップレベル関数オブジェクト(*ObjFunction)を指します。ホストはフィールドを直接参照せず、Context.runScript / Context.serializeScript にそのまま渡します。コンパイル時に内部の永続値テーブルへ登録されるため、CompiledScript は対応する Context が生きている間は GC で回収されません。

HandleScope¶

短命なスコープ内でオブジェクト系 Value を GC からルートするためのヘルパーです。

pub const HandleScope = struct {
    pub fn pin(self: *HandleScope, val: Value) void;
    pub fn close(self: *HandleScope) void;
};

Context.handleScope() で生成し、defer scope.close() とセットで使うのが基本パターンです。ネストしたスコープを作ることもできます。

PersistentHandle¶

Context.protect が返す、明示的に解除するまで有効なルートハンドルです。

pub const PersistentHandle = struct {
    index: usize,
};

非オブジェクト値を protect した場合は index = std.math.maxInt(usize) を持つダミーハンドルが返り、unprotect は安全に無視されます。HandleScope と異なりスコープに縛られないため、コールバックを跨いで値を保持する場合(例: 保留中の Promise、非同期処理から後で参照するオブジェクト)に使います。

PromiseHandle¶

Context.makePromise が返す、resolve/reject 操作用のハンドルです。

pub const PromiseHandle = struct {
    promise_value: Value,
    persistent: PersistentHandle,
};

PromiseState¶

Promise の内部状態を表す列挙です。

pub const PromiseState = enum {
    pending,
    fulfilled,
    rejected,
};

value.md の promiseState で取得します。

GCMode¶

GC の起動方式を切り替える列挙です。

pub const GCMode = enum {
    auto,
    manual,
};

Context.setGCMode で切り替えます。

GCStats¶

GC の統計情報のスナップショットです。

pub const GCStats = struct {
    object_count: usize,
    threshold: usize,
    collection_count: usize,
    last_freed_count: usize,
};

Context.getGCStats で取得します。

GCConfig¶

GC のしきい値・成長係数を設定するための構造体です。

pub const GCConfig = struct {
    initial_threshold: usize = 256,
    growth_factor: usize = 2,
    min_threshold: usize = 256,
};

Context.setGCConfig で適用します。

ModuleLoader¶

ES Modules の import 解決をホスト側に委譲するためのフックです。

pub const ModuleLoader = struct {
    ptr: *anyopaque,
    // 省略可。specifier を referrer 基準で解決し、モジュールの正規キーを返す
    resolve_fn: ?*const fn (ptr: *anyopaque, specifier: []const u8, referrer: []const u8, allocator: std.mem.Allocator) anyerror!?[]u8 = null,
    // 解決済み specifier からソースコードを読み込む
    load_fn: *const fn (ptr: *anyopaque, specifier: []const u8) anyerror!?[]const u8,
};

Context.setModuleLoader で登録します。load_fn が返したソース文字列の所有権はホスト側に残ります(エンジンは内部でコピーします)。

互換性メモ: 以前の load_fn は第3引数に referrer を取っていましたが、referrer による解決は resolve_fn に分離されました。load_fn には解決済みの specifier のみが渡されます。

EventLoopHook¶

setTimeout / setInterval / clearTimeout / clearInterval をホストのイベントループへ委譲するためのフックです。

pub const EventLoopHook = struct {
    set_timer: *const fn (id: u32, delay_ms: u32, is_repeat: bool, userdata: ?*anyopaque) void,
    clear_timer: *const fn (id: u32, userdata: ?*anyopaque) void,
    userdata: ?*anyopaque = null,
};

Context.setEventLoopHook で登録します。フックが未設定の場合、setTimeout/setInterval は遅延を無視して即座に(同期的に)コールバックを実行します。ホストは set_timer で受け取った id を実際にタイマーが発火したタイミングで Context.fireTimer(id) に渡してコールバックを実行します。

ConsoleLevel / ConsoleHandler¶

console.log などの出力先をホストへリダイレクトするための型です。

pub const ConsoleLevel = enum { log, info, warn, err, debug };

pub const ConsoleHandler = struct {
    ptr: ?*anyopaque = null,
    write_fn: *const fn (ptr: ?*anyopaque, level: ConsoleLevel, text: []const u8) void,
};

err は Zig の予約語 error を避けたスペルで、console.error に対応します。text は呼び出し中のみ有効なので、保持する場合は write_fn 内で複製してください。Context.setConsoleHandler で登録し、null を渡すと標準出力へのデフォルト動作に戻ります。

UnhandledRejectionHandler¶

未処理の Promise reject をホストへ通知するための型です(HostPromiseRejectionTracker 相当)。

pub const UnhandledRejectionHandler = struct {
    ptr: ?*anyopaque = null,
    handler_fn: *const fn (ptr: ?*anyopaque, reason: value.Value) void,
};

drainMicrotasks 完了時点で reject ハンドラ(.then/.catch/.finally のいずれか)が一度も付いていない Promise について、reason(reject 理由の Value)を添えて handler_fn が呼ばれます。Context.setUnhandledRejectionHandler で登録し、null で通知を止めます。

Realm¶

グローバル変数やビルトインのプロトタイプ集合を保持する不透明な構造体です。

pub const Realm = vm.Realm;

フィールドはエンジン内部専用で、ホストからは *Realm を不透明ポインタとして扱います。Context.createRealm / setRealm / getRealm / destroyRealm を介して複数の独立したグローバル環境を切り替える用途に使います(詳細は context の Realms セクションを参照)。