{"id":13991806,"url":"https://github.com/hoytech/valence","last_synced_at":"2026-03-03T15:02:44.673Z","repository":{"id":31044743,"uuid":"34603395","full_name":"hoytech/valence","owner":"hoytech","description":"RPC interface for electron GUI toolkit","archived":false,"fork":false,"pushed_at":"2016-09-22T16:01:47.000Z","size":15,"stargazers_count":69,"open_issues_count":0,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-11T20:41:27.430Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoytech.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}},"created_at":"2015-04-26T08:13:38.000Z","updated_at":"2024-08-13T18:06:45.000Z","dependencies_parsed_at":"2022-09-08T16:23:35.530Z","dependency_job_id":null,"html_url":"https://github.com/hoytech/valence","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hoytech/valence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoytech%2Fvalence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoytech%2Fvalence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoytech%2Fvalence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoytech%2Fvalence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoytech","download_url":"https://codeload.github.com/hoytech/valence/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoytech%2Fvalence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30050222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T14:38:37.398Z","status":"ssl_error","status_checked_at":"2026-03-03T14:38:06.721Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-08-09T14:01:36.276Z","updated_at":"2026-03-03T15:02:44.641Z","avatar_url":"https://github.com/hoytech.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Valence Logo](https://hoytech.github.io/valence/logo.svg)](https://github.com/hoytech/valence)\n\n## Description\n\n`valence.js` is an interface for controlling github's [electron](https://github.com/atom/electron) GUI toolkit from another process. It is inspired by the [Thrust](https://github.com/breach/thrust) project.\n\nEssentially, electron is a node.js process connected to a chromium process. The idea is that you write node.js javascript code to control a chromium process in order to build applications that look and feel like native applications.\n\nValence is a protocol for communicating between this node.js process and another controller process, and `valence.js` is the node.js component of the implementation. `valence.js` runs in the electron main process as depicted in this diagram:\n\n    |------------|    stdio |--------------| IPC |----------------|\n    |  Your app  |---------\u003e| electron     |----\u003e| electron       |\n    |            |\u003c---------| main process |\u003c----| render process |\n    |------------|          |--------------|     |----------------|\n     perl/whatever             valence.js            chromium\n\n`valence.js` is compatible with electron versions 0.25.1 through 1.4.1 (and probably later).\n\n\n## Rationale\n\nWhy have a separate controller process at all? Why not just write the controller logic in javascript and run it in the electron main process?\n\nFirst of all, the obvious reason is that not everybody wants to write substantial controller logic in javascript. Different languages have different strengths and libraries that may not be available in javascript/node.js. For example, when communicating with SQL databases it's hard to beat perl's [DBI](https://metacpan.org/pod/DBI) module (see [AnyEvent::DBI](https://metacpan.org/pod/AnyEvent::DBI) or [AnyEvent::Task](https://metacpan.org/pod/AnyEvent::Task) for how to use DBI in an async program).\n\nSecondly, sometimes we already have significant existing programs written in another language that we would like to add a GUI front-end to. Rather than re-write such apps in javascript, `valence.js` provides a \"glue\" option for other environments to use electron.\n\nFinally, even if your app is written in javascript, in order to use electron directly, your app needs to support the exact version of `node` that electron is currently compiled with. This can especially be an issue with native modules that depend on older `node` APIs. With `valence.js` you can use any `node` environment that is applicable to your application -- well, once we have a javascript driver that is :).\n\n\n## Drivers\n\n### Perl\n\nThe reference implementation of the app-side of the valence protocol is written in perl 5.\n\nIt can be installed with the following cpan minus command (use `--sudo` if you with to install it for all users on your machine):\n\n    $ cpanm Valence --sudo\n\nAfter it is installed, see the [Valence](https://metacpan.org/pod/Valence) documentation for how to use it. To work on the code itself, please fork it on [github](https://github.com/hoytech/Valence-p5).\n\n\n\n## Protocol\n\n`valence.js` is an electron app and you can run it as you would any other:\n\n    /path/to/electron /path/to/valence/app/\n\nAfter this, the app will wait until it receives messages on standard input, and will subsequently emit messages over its standard output. All of your app's communication with `valence.js` is done over electron's stdio pipes.\n\nAll messages (both input and output) are minified JSON, followed by a new-line. This means there is exactly one message per line.\n\nEvery method has a `cmd` parameter which indicates the \"command\" to be invoked by the message. The other parameters depend on which command was sent.\n\n### Commands\n\n#### call\n\nAPP -\u003e VALENCE\n\nIndicates that valence should call a method on a particular object.\n\nParameters:\n\n- `obj`: The object id (see `save` below) corresponding to the object that the method should be called on. Optional. If omitted, assumed to be `node.js`'s `module` object.\n\n- `method`: The name of the method to be invoked. Required.\n\n- `save`: The object id to assign to whatever is returned from the method call. Typically this is a counter that is maintained by the app which is incremented for every method call. Optional. If omitted, the return result is discarded.\n\n- `args`: An array of arguments that should be passed to the method. Required (but can be empty).\n\n- `args_cb`: An array of arrays. Each array represents a callback insertion that should be applied to `args` above. The first element in each sub-array is the offset in args where a callback should be inserted, and the second element is the callback id (see the `cb` command). Optional.\n\n#### destroy\n\nAPP -\u003e VALENCE\n\nIndicates that the app is finished with an object and valence can discard its reference to it.\n\nParameters:\n\n- `obj`: The object id of the object to be destroyed. This should have been passed in via a previous `save` parameter. Required.\n\n#### attr\n\nAPP -\u003e VALENCE\n\nUsed to lookup an attribute from an object and save it in a new object.\n\nParameters:\n\n- `obj`: The object id of which to lookup an attribute from. Required.\n\n- `attr`: The name of the attribute. Required.\n\n- `save`: The object id to assign to the result. Optional (but pointless without).\n\n#### get\n\nAPP -\u003e VALENCE\n\nRetrieves a value stored in an object id by having it passed to a callback.\n\nParameters:\n\n- `obj`: The object id of the object to retrieve. Required.\n\n- `cb`: The callback id (see the `cb` command) to invoke with the result. Required.\n\n#### cb\n\nVALENCE -\u003e APP\n\nSent by `valence.js` when it wishes to invoke a callback in your application.\n\nParameters:\n\n- `cb`: The callback id to be invoked. This was passed in from a `call` or `get` command. Required.\n\n- `args`: An array of arguments to be passed to the callback. Required (but may be empty).\n\n\n### Examples\n\nHere is the detailed description of a few selected messages.\n\nNote that the JSON in these examples has been \"prettified\" and in the actual valence protocol they **must** be minified and one-per-line.\n\nWhen experimenting, if you are using the perl module you can set the `VALENCE_DEBUG` environment variable to sniff the traffic between a perl app and `valence.js` (see the [Valence](https://metacpan.org/pod/Valence) docs).\n\n#### Example 1\n\nThis example is of an app calling a method which contains a callback. It is roughly equivalent to executing this code:\n\n    get_object(3).on('closed', function() {\n        notify_callback(4);\n    });\n\nHere is what the message might look like:\n\n    {\n       \"args\" : [\n          \"closed\",\n          null\n       ],\n       \"args_cb\" : [\n          [\n             1,\n             4\n          ]\n       ],\n       \"cmd\" : \"call\",\n       \"method\" : \"on\",\n       \"obj\" : \"3\"\n    }\n\nThe `obj` above is `3` which presumably was the object resulting from the creation of a [BrowserWindow](https://github.com/atom/electron/blob/master/docs/api/browser-window.md) object. We are attaching a callback to listen for `closed` events. The callback id is `4`, and its location in the args array is `1`. Note that the callback has been stubbed out with a `null` value and will be replaced by an actual javascript function by `valence.js`, and how there is no `save` parameter because we aren't interested in the returned result of the `on` method.\n\n#### Example 2\n\nThis is what `valence.js` might send when the `closed` event was triggered:\n\n    {\n       \"args\" : [\n                  {}\n                ],\n       \"cb\" : 4,\n       \"cmd\" : \"cb\"\n    }\n\nThe callback id is `4` (see the previous example). There is an empty hash in the `args` list. This corresponds to the javascript event, but has been converted into an empty hash because the `node.js` `JSON.stringify()` method could not serialize this value.\n\n\n## TODO\n\n- Currently the `args_cb` values can only reference the first level of the arguments and cannot replace a callback inside a nested structure like an object or array. Eventually the protocol should support location specifiers such as `[1][3]['field']`\n\n- It needs to spec out behaviour for what happens when exceptions are thrown.\n\n- The protocol should expose a way to eval raw javascript in the main process (you can already do it in the render process with `WebContents.executeJavaScript()`).\n\n- The special `new` method can currently only support 1 parameter because of a limitation in javascript.\n\n- `valence.js` currently doesn't know when a callback it has installed has been garbage collected. If it did then it could send a \"callback destroy\" command to the app. This may be possible with the npm [weak](https://www.npmjs.com/package/weak) module.\n\n\n## See Also\n\nThe [Valence perl module](https://metacpan.org/pod/Valence)\n\nSome examples that use Valence: [DB-Browser](https://github.com/hoytech/db-browser), [HackRF-RCCar](https://github.com/hoytech/Radio-HackRF-RCCar)\n\n[Presentation for Perl Mongers](https://www.youtube.com/watch?v=u3S2vhN0S1M\u0026t=2m23s)\n\n\n\n## Author\n\nDoug Hoyte, doug@hcsw.org\n\n## COPYRIGHT \u0026 LICENSE\n\nCopyright 2015-2016 Doug Hoyte.\n\nThis project is licensed under the 2-clause BSD license.\n\nElectron itself is Copyright (c) 2014-2016 GitHub Inc. and is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoytech%2Fvalence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoytech%2Fvalence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoytech%2Fvalence/lists"}