{"id":13895312,"url":"https://github.com/fengari-lua/fengari-interop","last_synced_at":"2025-04-04T21:07:33.741Z","repository":{"id":20835918,"uuid":"91039868","full_name":"fengari-lua/fengari-interop","owner":"fengari-lua","description":"Fengari \u003c=\u003e JS Interop","archived":false,"fork":false,"pushed_at":"2024-03-02T13:21:50.000Z","size":624,"stargazers_count":102,"open_issues_count":15,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T20:06:14.990Z","etag":null,"topics":["fengari","javascript","js","lua"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fengari-lua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-05-12T01:50:52.000Z","updated_at":"2025-02-20T19:44:36.000Z","dependencies_parsed_at":"2024-04-16T01:43:26.023Z","dependency_job_id":"aa1948ba-65a8-44b7-8f48-b1648de90b9e","html_url":"https://github.com/fengari-lua/fengari-interop","commit_stats":{"total_commits":154,"total_committers":5,"mean_commits":30.8,"dds":"0.038961038961038974","last_synced_commit":"92fd93757f3f93a46b59a24f88ff1c03b1071f84"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fengari-lua%2Ffengari-interop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fengari-lua%2Ffengari-interop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fengari-lua%2Ffengari-interop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fengari-lua%2Ffengari-interop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fengari-lua","download_url":"https://codeload.github.com/fengari-lua/fengari-interop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fengari","javascript","js","lua"],"created_at":"2024-08-06T18:02:07.699Z","updated_at":"2025-04-04T21:07:33.725Z","avatar_url":"https://github.com/fengari-lua.png","language":"JavaScript","readme":"[![Build Status](https://github.com/fengari-lua/fengari-interop/actions/workflows/ci.yaml/badge.svg)](https://github.com/fengari-lua/fengari-interop/actions/workflows/ci.yaml?query=event%3Apush)\n[![npm](https://img.shields.io/npm/v/fengari-interop.svg)](https://npmjs.com/package/fengari-interop)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![#fengari on libera.chat](https://img.shields.io/badge/chat-%23fengari-brightgreen)](https://web.libera.chat/?channels=#fengari)\n\n\n# JS library for Fengari\n\n[Fengari](https://github.com/fengari-lua/fengari) is a lua VM written in Javascript.\nIts implementation makes use of the JS garbage collector, which means it is fully capable of cross language interop.\n\n## Features\n\n  - Call any JS function from Lua\n  - Give Lua tables/functions/userdata to Javascript\n\n\n## `js` library\n\n```lua\njs = require \"js\"\n```\n\n### `null`\n\nA userdata representing JavaScript [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)\n\n\n### `global`\n\nA reference to the JavaScript global context. In the browser, this is usually equivalent to the `window` object. In node.js it's equal to [`global`](https://nodejs.org/api/globals.html#globals_global).\n\n\n### `new(constructor, ...)`\n\nInvokes the JavaScript [`new` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new) on `constructor` passing the arguments specified.\n\nReturns the created object.\n\n\n### `of(iterable)`\n\nReturns a iterating function and an iterator state that behave like a JavaScript [for...of](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loop.\nSuitable for use as a lua iterator. e.g.\n\n```lua\nfor f in js.of(js.global:Array(10,20,30)) do\n\tprint(f)\nend\n```\n\n*Note: this function only exists if the JavaScript runtime supports [Symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)*\n\n\n### `createproxy(x[, type])`\n\n*Note: Only available if your JS environment has the `Proxy` constructor*\n\nCreates a JavaScript [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object. The proxy supports configuring traps by setting them as metamethods on your object.\n\n`type` may be `\"function\"` (the default) `\"arrow_function\"` or `\"object\"`:\n\n  - `\"function\"`:\n      - `typeof p === \"function\"`\n      - Can be used as a constructor\n  - `\"arrow_function\"`:\n      - `typeof p === \"function\"`\n      - Can **not** be used as a constructor\n  - `\"object\"`:\n      - `typeof p === \"object\"`\n      - Can **not** be used as a constructor\n\nNote that JavaScript coerces all types except Symbols to strings before using them as a key in an indexing operation.\n\n\n### `tonumber(x)`\n\nCoerces the value `x` to a number using JavaScript coercion rules.\n\n\n### `tostring(x)`\n\nCoerces the value `x` to a string using JavaScript coercion rules.\n\n\n### `instanceof(x, y)`\n\nReturns if the value `x` is an instance of the class `y` via use of the JavaScript [`instanceof` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof)\n\n\n### `typeof(x)`\n\nReturns what JavaScript sees as the type of `x`. Uses the JavaScript [`typeof` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof)\n\n\n## JavaScript API\n\n### `push(L, value)`\n\nPushes an arbitrary JavaScript object `value` as the most suitable lua type onto the lua stack `L`.\nPerforms deduplication so that the same JavaScript objects are pushed as the same lua objects.\n\n\n### `pushjs(L, value)`\n\nPushes an arbitrary JavaScript object `value` as a userdata onto the lua stack `L`.\nRarely used; see `push(L, value)` instead.\n\n\n### `checkjs(L, idx)`\n\nIf the value on the lua stack `L` at index `idx` is a JavaScript userdata object (as pushed by `push` or `pushjs`) then return it.\nOtherwise throw an error.\n\n\n### `testjs(L, idx)`\n\nIf the value on the lua stack `L` at index `idx` is a JavaScript userdata object (as pushed by `push` or `pushjs`) then return it.\nOtherwise returns `undefined`.\n\n\n### `tojs(L, idx)`\n\nReturns the object on the lua stack `L` at index `idx` as the most suitable javascript type.\n\n  - `nil` is returned as `undefined`\n  - booleans are returned as booleans\n  - numbers are returned as numbers\n  - strings are returned as JavaScript strings\n    (Note: this *can* throw an error if the lua string is not represenable as a JavaScript string)\n  - JavaScript userdata object (as pushed by `push` or `pushjs`) returns the pushed JavaScript object\n  - Other objects are returned wrapped in a JavaScript function object with methods:\n      - `apply(this, [args...])`: calls the lua object. Returns only the first return value\n      - `invoke(this, [args...])`: calls the lua object. Returns results as an array\n      - `get(key)`: indexes the lua object\n      - `has(key)`: checks if indexing the lua object results in `nil`\n      - `set(key, value)`\n      - `delete(key)`: sets the key to `nil`\n      - `toString()`\n    JavaScript arguments to these methods are passed in via `push()` and results are returned via `tojs()`.\n    Calling the function is equivalent to calling the lua function wrapped.\n\n\n### `luaopen_js`\n\nThe entrypoint for loading the [js library](#js-library) into a fengari `lua_State`.\nUsually passed to `luaL_requiref`.\n\n\n## Symbols\n\nIf the JavaScript environment supports [Symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), then some runtime-wide symbols can be used to customise behaviour:\n\n### `__pairs`\n\nThe `__pairs` Symbol can be used to describe how to iterate over a JavaScript object. Use `Symbol.for(\"__pairs\")` to get the symbol. It should be used as a key on your objects, where the value is a function returning an object with three properties: `\"iter\"`, `\"state\"` and `\"first\"`.\n\n`\"iter\"` should be a function that follows the standard [Lua generic for protocol](http://www.lua.org/manual/5.3/manual.html#3.3.5), that is, it gets called with your *state* (as `this`) and the previous value produced; it should return an array of values or `undefined` if done.\n\ne.g. to make `pairs` on a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) return entries in the map via the [iterator symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/@@iterator):\n\n```js\nMap.prototype[Symbol.for(\"__pairs\")] = function() {\n\treturn {\n\t\titer: function(last) {\n\t\t\tvar v = this.next();\n\t\t\tif (v.done) return;\n\t\t\treturn v.value;\n\t\t},\n\t\tstate: this[Symbol.iterator]()\n\t};\n};\n```\n\nIf there is no `__pairs` Symbol attached to an object, an iterator over [`Object.keys`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys) is returned.\n\n\n### `__len`\n\nThe `__len` Symbol can be used to describe how to get the length (used by the lua `#` operator) of a JavaScript object.\nUse `Symbol.for(\"__len\")` to get the symbol. It should be used as a key on your objects, where the value is a function returning the length of your objects (passed as `this`).\n\ne.g. to have the lua `#` operator applied to a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) return the [`size`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/size) field:\n\n```js\nMap.prototype[Symbol.for(\"__len\")] = function() {\n\treturn this.size;\n};\n```\n\nIf there is no `__len` Symbol attached to an object, the value of the `.length` property is returned.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffengari-lua%2Ffengari-interop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffengari-lua%2Ffengari-interop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffengari-lua%2Ffengari-interop/lists"}