Merge branch 'master' into fix-limits

.npmrc

@@ -0,0 +1,2 @@
+no-lockfile=true
+ignore-workspace-root-check=true

CONTRIBUTING.md

@@ -20,6 +20,54 @@ cd socket
 .\bin\install.ps1
 ```
 
+## Building `ssc` and other useful commands
+
+`ssc` (short for Socket Supply Compiler) is a command-line tool that is used to build Socket Runtime applications.
+It is a wrapper around the native build tools for each platform and provides a unified interface for building Socket Runtime applications. You don't have to use Xcode, MSAndroid Studio, or Visual Studio to build Socket Runtime applications, but you can if you want to.
+
+### `./bin/install.sh` (macOS and Linux) or `.\bin\install.ps1` (Windows)
+
+This command installs the dependencies for Socket Runtime and builds `ssc` for your platform.
+- `ssc` on macOS can cross-compile for iOS, iOS Simulator, Android, and Android Emulator.
+- `ssc` on Linux can cross-compile for Android and Android Emulator.
+- `ssc` on Windows can cross-compile for Android and Android Emulator.
+
+Additional flags on macOS and Linux:
+- `VERBOSE=1` - prints useful information about the build process. Please use this flag if you are reporting a bug.
+- `DEBUG=1` - builds `ssc` in debug mode. This is useful if you are developing `ssc` and want to debug it.
+- `NO_ANDROID=1` - skips the `ssc`'s Android support. This is useful if you are not developing for Android and don't want to install the Android SDK.
+- `NO_IOS=1` - skips the `ssc`'s iOS support. This is useful if you are not developing for iOS and don't want to install the iOS SDK. It's only useful on macOS.
+- `CPU_CORES={number}` - sets the number of CPU cores to use for the build. This is useful if you want to speed up the build process. The default value is the number of CPU cores on your machine.
+<!--
+TODO(@chicoxyzzy):
+- `SOCKET_HOME={path}` - sets the path to the Socket Runtime build directory. This is useful if you want to build Socket Runtime in a different directory than the default one.
+
+what else?
+-->
+
+Additional flags on Windows:
+- `-debug` - builds `ssc` in debug mode. This is useful if you are developing `ssc` and want to debug it.
+- `-verbose` - prints useful information about the build process. Please use this flag if you are reporting a bug.
+- `-yesdeps` - automatically installs the dependencies for Socket Runtime.
+
+If you make any changes to the Socket Runtime JavaScript API source code, you should run `npm run gen` after running `./bin/install.sh` or `.\bin\install.ps1` to update the TypeScript type definitions for Socket Runtime and the API documentation.
+
+### `./bin/publish-npm-modules.sh` (macOS and Linux)
+
+This command runs `./bin/install.sh`, builds `ssc` npm packages and does [`npm link`](https://docs.npmjs.com/cli/v10/commands/npm-link) for the `@socketsupply/socket` package and platform-specific packages  (if `--link` flag is provided, see description below).
+This allows you to use the latest version of Socket Runtime in your Socket Runtime applications without publishing the npm packages to npmjs.com registry. Just run `npm link @socketsupply/socket` in your Socket Runtime application directory and you are good to go and use your local version of Socket Runtime.
+
+Useful flags:
+- `--only-platforms` - builds only the platform-specific npm packages.
+- `--only-top-level` - builds only the top-level npm package.
+- `--link` - runs `npm link` for the `@socketsupply/socket` package and platform-specific packages.
+
+You don't have to run `npm run gen` after running `./bin/publish-npm-modules.sh` because it runs `npm run gen` automatically.
+
+### `./bin/clean.sh` (macOS and Linux)
+
+Sometimes you need to clean the build artifacts and start from scratch. This command removes the build artifacts for `ssc` and the Socket Runtime libraries.
+
 ## Project directory structure
 
 The project is structured as follows:
@@ -29,27 +77,51 @@ It consists of the built-in modules that are available in the runtime and the `s
 These modules have native bindings to the underlying C++/Objective-C/Kotlin code and libuv to expose the platform
 capabilities to the JavaScript code.
 
-2. [`bin`](https://github.com/socketsupply/socket/tree/master/bin): This directory contains useful scripts for building the project on different platforms, managing versions, generating documentation, publishing npm packages, etc.
-
-3. [`npm`](https://github.com/socketsupply/socket/tree/master/npm): This directory consists of the JavaScrip wrappers for the native code, build scripts and package directories.
+1. [`bin`](https://github.com/socketsupply/socket/tree/master/bin): This directory contains useful scripts for building the project on different platforms, managing versions, generating documentation, publishing npm packages, etc.
+1. [`npm`](https://github.com/socketsupply/socket/tree/master/npm): This directory consists of the JavaScrip wrappers for the native code, build scripts and package directories.
 This directory consists of the JavaScrip wrappers for the native code, build scripts and package directories.
 You can also find the official Socket Runtime Node.js backend in the
 [`npm/packages/@socketsupply/socket-node`](https://github.com/socketsupply/socket/tree/master/npm/packages/%40socketsupply/socket-node) directory.
+1. [`src`](https://github.com/socketsupply/socket/tree/master/src): This directory contains the native code for the Socket Runtime:
+   - [`android`](https://github.com/socketsupply/socket/tree/master/src/android): contains the source code for the Socket Runtime library for Android
+   - [`app`](https://github.com/socketsupply/socket/tree/master/src/app): contains the source code related to the Socket Runtime application instance
+   - [`cli`](https://github.com/socketsupply/socket/tree/master/src/cli): contains the source code for the Socket Runtime CLI
+   - [`core`](https://github.com/socketsupply/socket/tree/master/src/core): contains the source code for the Socket Runtime core, such as Bluetooth support, File System, UDP, Peer-to-Peer capabilities, JavaScript bindings, etc.
+   - [`desktop`](https://github.com/socketsupply/socket/tree/master/src/desktop): contains the source code for the Socket Runtime library for desktop platforms
+   - [`extension`](https://github.com/socketsupply/socket/tree/master/src/extension): contains the source code for the Socket Runtime extensions ABI
+   - [`ios`](https://github.com/socketsupply/socket/tree/master/src/ios): contains the source code for the Socket Runtime library for iOS
+   - [`ipc`](https://github.com/socketsupply/socket/tree/master/src/ipc): contains the source code for the Socket Runtime IPC library
+   - [`process`](https://github.com/socketsupply/socket/tree/master/src/process): contains the source code for the process management
+   - [`window`](https://github.com/socketsupply/socket/tree/master/src/window): contains the source code for the window management on desktop platforms
+1. [`test`](https://github.com/socketsupply/socket/tree/master/src/test): This directory contains the actual Socket Runtime application that is used for testing the native code and the JavaScript API.
+
+## Building Socket Runtime applications
+
+Once you have built `ssc`, you can use it to build Socket Runtime applications.
+`ssc -h` command prints the help message for `ssc` and lists all the available commands.
+
+Check out the [Guides](https://socketsupply.co/guides/) for more information on how to build Socket Runtime applications.
 
-4. [`src`](https://github.com/socketsupply/socket/tree/master/src): This directory contains the native code for the Socket Runtime:
-- [`android`](https://github.com/socketsupply/socket/tree/master/src/android): contains the source code for the Socket Runtime library for Android
-- [`app`](https://github.com/socketsupply/socket/tree/master/src/app): contains the source code related to the Socket Runtime application instance
-- [`cli`](https://github.com/socketsupply/socket/tree/master/src/cli): contains the source code for the Socket Runtime CLI
-- [`core`](https://github.com/socketsupply/socket/tree/master/src/core): contains the source code for the Socket Runtime core, such as Bluetooth support, File System, UDP, Peer-to-Peer capabilities, JavaScript bindings, etc.
-- [`desktop`](https://github.com/socketsupply/socket/tree/master/src/desktop): contains the source code for the Socket Runtime library for desktop platforms
-- [`extension`](https://github.com/socketsupply/socket/tree/master/src/extension): contains the source code for the Socket Runtime extensions ABI
-- [`ios`](https://github.com/socketsupply/socket/tree/master/src/ios): contains the source code for the Socket Runtime library for iOS
-- [`ipc`](https://github.com/socketsupply/socket/tree/master/src/ipc): contains the source code for the Socket Runtime IPC library
-- [`process`](https://github.com/socketsupply/socket/tree/master/src/process): contains the source code for the process management
-- [`window`](https://github.com/socketsupply/socket/tree/master/src/window): contains the source code for the window management on desktop platforms
+## Adding tests
 
-5. [`test`](https://github.com/socketsupply/socket/tree/master/src/test): This directory contains the actual Socket Runtime application that is used for testing the native code and the JavaScript API.
+We run Socket Runtime E2E tests from the actual Socket Runtime application located in the [`test`](https://github.com/socketsupply/socket/tree/master/src/test) directory. This allows us to test the Socket Runtime API from the perspective of the Socket Runtime application developer. The tests are written in JavaScript and use the built-in `socket:test` module to test the Socket Runtime API. `socket:test` is a port of the [`tapzero`](https://github.com/socketsupply/tapzero) testing framework.
 
+To run the tests, use the following command:
+
+```bash
+npm run test
+```
+You can also run specific tests against specific module by using the `--test` flag:
+
+```bash
+ssc run --test=application.js ./test
+```
+Be sure to build `ssc` before running the tests if you have made any changes to the Socket Runtime source code.
+You can also rebuild and run `ssc` with a single command:
+
+```bash
+ssc build -r --test=application.js ./test
+```
 
 ## Other repositories
 - [Socket-Examples](https://github.com/socketsupply/socket-examples): This repository contains example projects powered by Socket which helps you build cross-platform apps for desktop and mobile.

README.md

@@ -1,48 +1,44 @@
-
-<p align="center">
-  <a href="https://github.com/socketsupply/socket"><img src="https://user-images.githubusercontent.com/136109/230840267-7b7334b5-fee3-494b-aa4c-145e071f8471.png"/>
-</p>
+![image](https://github.com/socketsupply/socket/assets/136109/93abfcbe-e880-4548-b3e0-dc7e09292ca6)
 
 ### Description
 
-Web Developers use `Socket Runtime` to create apps for any OS, desktop, or mobile. You can use plain old HTML, CSS, and JavaScript, as well as your favorite front-end libraries for example React, Svelte, and Vue.
-
-`Socket Runtime` exposes primitives needed for building peer-to-peer and local-first applications, such as Bluetooth, UDP, and robust file system access. Our P2P component can help you connect your app's users, and let them communicate directly, without the cloud or any servers at all.  
+Web Developers use `Socket runtime` to create apps for any OS, desktop, and mobile. You can use plain old HTML, CSS, and JavaScript, as well as your favorite front-end libraries like Next.js, React, Svelte, or Vue.  
 
-`The Socket Runtime CLI` compiles applications into hybrid-native applications &mbasp; meaning, a combination of web code running in a platform's "WebView" along with platform-native code: Kotlin/Java on Android, Swift/Objective-C on iOS, C++ on Windows or Linux, etc.
+The `Socket runtime CLI` outputs hybrid native-web apps that combine your code with the runtime. Your code is rendered using the OS's native "WebView" component. Platform features are implemented natively and made available to the JavaScript environment in a way that is secure and fully sandboxed on every platform. Native APIs like Bluetooth and UDP make local-first and peer-to-peer software design patterns as first class considerations.
 
-### 💡 Features
+### Features
 
-* Local First, a full-featured File system API & Bluetooth.
-* P2P & Cloud, built to support a new generation of apps that can connect directly to each other by providing a high-performance UDP API.
-* Use any backend, business logic can be written in any language, Python, Rust, Node.js, etc. The backend is even completely optional.
-* Use any frontend, you can use your favorite frontend framework to create your UIs: React, Svelte, Vue, and more.
-* Maintainable, zero dependencies, and a smaller code base than any other competing project.
-* Lean & Fast, uses a smaller memory footprint and creates smaller binaries than any other competing project.
+* Any backend &mdash; Business logic can be written in any language, Python, Rust, Node.js, etc. The backend is even completely optional.
+* Any frontend &mdash; Use your favorite frontend framework to create your UIs: React, Svelte, Vue, and more.
+* Batteries Included &mdash; Native Add-ons are supported, but we ship everything you need for the majority of use cases.
+* Local-first &mdash; A full-featured, familiar File system API, native add-ons and full cross platform support for Bluetooth.
+* Not just Cloud &mdash; P2P helps you reliably move work out of the cloud, beyond the edge, and onto the devices that can communicate directly with each other.
+* Maintainable &mdash; Socket runtime has Zero external dependencies, and a smaller code base than any other competing project.
+* Lean & Fast &mdash; Socket runtime has a smaller memory footprint and creates smaller binaries than any other competing project.
 
-### 🔑 FAQ
+### FAQ
 
-Check the FAQs on our [Website](https://socketsupply.co/) to learn more.
+Check the FAQs on our [Website](https://socketsupply.co/guides/#faq) to learn more.
 
-### 🧱 Building your first Socket app!
+### Building your first Socket app!
 
 `Create Socket App` is similar to React's `Create React App`, we provide a few basic boilerplates and some strong opinions so you can get coding on a production-quality app as quickly as possible.  
 Please check [create-socket-app Repo](https://github.com/socketsupply/create-socket-app) to get started and to learn more.  
 You can also check our `Examples` in the [Examples Repo](https://github.com/socketsupply/socket-examples).  
 
 
-### 📚 Documentation
+### Documentation
 
 The full documentation can be found on the [Socket Runtime](https://socketsupply.co/) website.  
 The `Socket Runtime` documentation covers Socket APIs, includes examples, multiple guides (`Apple`, `Desktop`, and `Mobile`), `P2P` documentation, and more.
 
 
-### 🧪 Testing
+### Testing
 
 `Socket` provides a built-in `test runner` similar to `node:test` which outputs the test results in [TAP](https://testanything.org/) format.
  You can also check [`test/`](test/) for the unit and integration test suite.
 
-### 🙏 Contributing
+### Contributing
 
 We welcome contributions from everyone! Please check our [Contribution Guide](CONTRIBUTING.md) to learn more.
 Don't hesitate to stop by [Discord](https://discord.com/invite/YPV32gKCsH) and ask the team about your issue and if someone is already working on it.