From ddcf322174225546c3601a2ba27395cc57c6f0e7 Mon Sep 17 00:00:00 2001 From: Ashton Eby Date: Fri, 25 Oct 2024 14:15:29 -0700 Subject: [PATCH] prettier everything --- .github/workflows/test.yml | 40 +++++----- DEV-README.md | 4 + README.md | 145 +++++++++++++++++++------------------ package.json | 2 +- sea/README.md | 4 + sea/build.cjs | 5 +- sea/config.json | 2 +- sea/import-meta-url.js | 2 +- 8 files changed, 108 insertions(+), 96 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a15e8783..cbd2d28b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,9 +6,9 @@ name: Test on: # temporarily "v3"; change to "main" after merge push: - branches: [ "v3" ] + branches: ["v3"] pull_request: - branches: [ "v3" ] + branches: ["v3"] jobs: build: @@ -20,21 +20,21 @@ jobs: # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - - uses: actions/checkout@v4 - - name: Test (nodeJS ${{ matrix.node-version }}) - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - cache: 'npm' - - run: npm ci - - run: npm test - env: - TERM: xterm-256color - # Set to the correct color level; 2 is 256 colors - # https://github.com/chalk/chalk?tab=readme-ov-file#supportscolor - FORCE_COLOR: 2 - - name: Publish Test Report - uses: mikepenz/action-junit-report@v4 - if: success() || failure() # always run even if the previous step fails - with: - report_paths: '**/test-results.xml' + - uses: actions/checkout@v4 + - name: Test (nodeJS ${{ matrix.node-version }}) + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: "npm" + - run: npm ci + - run: npm test + env: + TERM: xterm-256color + # Set to the correct color level; 2 is 256 colors + # https://github.com/chalk/chalk?tab=readme-ov-file#supportscolor + FORCE_COLOR: 2 + - name: Publish Test Report + uses: mikepenz/action-junit-report@v4 + if: success() || failure() # always run even if the previous step fails + with: + report_paths: "**/test-results.xml" diff --git a/DEV-README.md b/DEV-README.md index 3ba885a8..72c38bb4 100644 --- a/DEV-README.md +++ b/DEV-README.md @@ -1,16 +1,20 @@ ### Application versions + This project has 3 runnable entrypoints (a raw ESM one, a built CJS one, and an SEA one). You can read more about them [here](./sea/README.md). ### General style guidelines + - Prefer to throw errors instead of exiting the process. Exit is harder to mock well in tests, and the global error-handler in `src/cli.mjs` should already do verbosity-aware error-handling. You can request a specific exit code by attaching an `exitCode` property to your error before throwing it. The error-handling has a series of tests in `yargs-test/general-cli.mjs`; if you find a case where throwing results in bad output to the user, replicate that case in a test suite. - Prefer to re-throw an existing error after modifying its message over catching and throwing a newly-constructed error. The `exitCode` and `stack` properties on the existing error are worth keeping. #### Testing guidelines + - Prefer to mock the "far" edges of the application - methods on `fs`, complex async libraries (e.g., `http#Server`), `fetch`. This results in the test code traversing all of the CLI's business logic, but not interacting with error-prone external resources like disk, network, port availability, etc. `sinon` records all calls to a mock, and allows asserting against them. Use this if, e.g., your business logic calls `fetch` multiple times. - ~~Prefer to run local tests in watch mode with (e.g., with `yarn local-test`) while developing.~~ This is currently broken. - Use debug logs to output the shape of objects (especially network responses) to determine how to structure mocks. For instance, to get a quick mock for a network request caused by `fauna schema status ...`, set the situation up and run `fauna schema status ... --verbosity 5`. You can then use the logged objects as mocks. #### Debugging strategies + - Fetch is not particularly amenable to debugging, but if you need to see the raw requests being made, open a netcat server locally (`nc -l 8080`) and then change the code to call the netcat server, either by passing the flag `--url http://localhost:8080` or by editing the code. - This project has debug logging with a somewhat configurable logging strategy. To use it, provide either: - `--verbose-component foo`, which logs all debug info for the component `foo`. Because it's an array, you can specify it multiple times. To see the available components, look at the help or tab completion. diff --git a/README.md b/README.md index 3eccd26d..2702ba80 100644 --- a/README.md +++ b/README.md @@ -25,16 +25,17 @@ $ npm update -g fauna-shell ``` -* [Fauna CLI](#fauna-cli) -* [Usage](#usage) -* [Technical Requirements](#technical-requirements) -* [Shell](#shell) -* [Connecting to different endpoints](#connecting-to-different-endpoints) -* [Connecting to local endpoints](#connecting-to-local-endpoints) -* [Overriding Connection Parameters](#overriding-connection-parameters) -* [Executing queries from a file](#executing-queries-from-a-file) -* [List of Commands](#list-of-commands) -* [Development](#development) + +- [Fauna CLI](#fauna-cli) +- [Usage](#usage) +- [Technical Requirements](#technical-requirements) +- [Shell](#shell) +- [Connecting to different endpoints](#connecting-to-different-endpoints) +- [Connecting to local endpoints](#connecting-to-local-endpoints) +- [Overriding Connection Parameters](#overriding-connection-parameters) +- [Executing queries from a file](#executing-queries-from-a-file) +- [List of Commands](#list-of-commands) +- [Development](#development) # Usage @@ -224,31 +225,31 @@ my_app> Post.create({ title: "What I had for breakfast .." }) We can also insert items in bulk by using iterator functions on arrays. ```ts -my_app> [ - "My cat and other marvels", - "Pondering during a commute", - "Deep meanings in a latte" -].map(title => Post.create({ title: title })) -[ - { - id: "373143473418666496", - coll: Post, - ts: Time("2023-08-15T16:16:36.960Z"), - title: "My cat and other marvels" - }, - { - id: "373143473419715072", - coll: Post, - ts: Time("2023-08-15T16:16:36.960Z"), - title: "Pondering during a commute" - }, - { - id: "373143473420763648", - coll: Post, - ts: Time("2023-08-15T16:16:36.960Z"), - title: "Deep meanings in a latte" - } -] +my_app > + [ + "My cat and other marvels", + "Pondering during a commute", + "Deep meanings in a latte", + ].map((title) => Post.create({ title: title }))[ + ({ + id: "373143473418666496", + coll: Post, + ts: Time("2023-08-15T16:16:36.960Z"), + title: "My cat and other marvels", + }, + { + id: "373143473419715072", + coll: Post, + ts: Time("2023-08-15T16:16:36.960Z"), + title: "Pondering during a commute", + }, + { + id: "373143473420763648", + coll: Post, + ts: Time("2023-08-15T16:16:36.960Z"), + title: "Deep meanings in a latte", + }) + ]; ``` Now let's try to fetch our post about _latte_. We need to access it by _id_ like this: @@ -294,15 +295,15 @@ my_app> Post.byId("373143473418666496")!.replace({ title: "My dog and other marv Now let's try to delete our post about _latte_: ```ts -my_app> Post.byId("373143473420763648")!.delete() -Post.byId("373143473420763648") /* not found */ +my_app > Post.byId("373143473420763648")!.delete(); +Post.byId("373143473420763648"); /* not found */ ``` If we try to fetch it, we will receive a null document: ```ts -my_app> Post.byId("373143473420763648") -Post.byId("373143473420763648") /* not found */ +my_app > Post.byId("373143473420763648"); +Post.byId("373143473420763648"); /* not found */ ``` Finally you can exit the _shell_ by pressing `ctrl+d`. @@ -431,10 +432,10 @@ Collection.create({ name: "Post", indexes: { byTitle: { - terms: [{ field: ".title" }] - } - } -}) + terms: [{ field: ".title" }], + }, + }, +}); ``` Once the collection is created, you can execute queries against it in another @@ -473,34 +474,35 @@ the queries file on the default fauna shell endpoint. # List of Commands -* [`fauna add-endpoint [NAME]`](#fauna-add-endpoint-name) -* [`fauna cloud-login`](#fauna-cloud-login) -* [`fauna create-database DBNAME`](#fauna-create-database-dbname) -* [`fauna create-key DBNAME [ROLE]`](#fauna-create-key-dbname-role) -* [`fauna default-endpoint [NAME]`](#fauna-default-endpoint-name) -* [`fauna delete-database DBNAME`](#fauna-delete-database-dbname) -* [`fauna delete-endpoint NAME`](#fauna-delete-endpoint-name) -* [`fauna delete-key KEYNAME`](#fauna-delete-key-keyname) -* [`fauna endpoint add [NAME]`](#fauna-endpoint-add-name) -* [`fauna endpoint list`](#fauna-endpoint-list) -* [`fauna endpoint remove NAME`](#fauna-endpoint-remove-name) -* [`fauna endpoint select [NAME]`](#fauna-endpoint-select-name) -* [`fauna environment add`](#fauna-environment-add) -* [`fauna environment list`](#fauna-environment-list) -* [`fauna environment select ENVIRONMENT`](#fauna-environment-select-environment) -* [`fauna eval [DBNAME] [QUERY]`](#fauna-eval-dbname-query) -* [`fauna help [COMMANDS]`](#fauna-help-commands) -* [`fauna import`](#fauna-import) -* [`fauna list-databases`](#fauna-list-databases) -* [`fauna list-endpoints`](#fauna-list-endpoints) -* [`fauna list-keys`](#fauna-list-keys) -* [`fauna project init [PROJECTDIR]`](#fauna-project-init-projectdir) -* [`fauna run-queries [DBNAME] [QUERY]`](#fauna-run-queries-dbname-query) -* [`fauna schema diff`](#fauna-schema-diff) -* [`fauna schema pull`](#fauna-schema-pull) -* [`fauna schema push`](#fauna-schema-push) -* [`fauna shell [DB_PATH]`](#fauna-shell-db_path) -* [`fauna upload-graphql-schema GRAPHQLFILEPATH`](#fauna-upload-graphql-schema-graphqlfilepath) + +- [`fauna add-endpoint [NAME]`](#fauna-add-endpoint-name) +- [`fauna cloud-login`](#fauna-cloud-login) +- [`fauna create-database DBNAME`](#fauna-create-database-dbname) +- [`fauna create-key DBNAME [ROLE]`](#fauna-create-key-dbname-role) +- [`fauna default-endpoint [NAME]`](#fauna-default-endpoint-name) +- [`fauna delete-database DBNAME`](#fauna-delete-database-dbname) +- [`fauna delete-endpoint NAME`](#fauna-delete-endpoint-name) +- [`fauna delete-key KEYNAME`](#fauna-delete-key-keyname) +- [`fauna endpoint add [NAME]`](#fauna-endpoint-add-name) +- [`fauna endpoint list`](#fauna-endpoint-list) +- [`fauna endpoint remove NAME`](#fauna-endpoint-remove-name) +- [`fauna endpoint select [NAME]`](#fauna-endpoint-select-name) +- [`fauna environment add`](#fauna-environment-add) +- [`fauna environment list`](#fauna-environment-list) +- [`fauna environment select ENVIRONMENT`](#fauna-environment-select-environment) +- [`fauna eval [DBNAME] [QUERY]`](#fauna-eval-dbname-query) +- [`fauna help [COMMANDS]`](#fauna-help-commands) +- [`fauna import`](#fauna-import) +- [`fauna list-databases`](#fauna-list-databases) +- [`fauna list-endpoints`](#fauna-list-endpoints) +- [`fauna list-keys`](#fauna-list-keys) +- [`fauna project init [PROJECTDIR]`](#fauna-project-init-projectdir) +- [`fauna run-queries [DBNAME] [QUERY]`](#fauna-run-queries-dbname-query) +- [`fauna schema diff`](#fauna-schema-diff) +- [`fauna schema pull`](#fauna-schema-pull) +- [`fauna schema push`](#fauna-schema-push) +- [`fauna shell [DB_PATH]`](#fauna-shell-db_path) +- [`fauna upload-graphql-schema GRAPHQLFILEPATH`](#fauna-upload-graphql-schema-graphqlfilepath) ## `fauna add-endpoint [NAME]` @@ -1317,6 +1319,7 @@ EXAMPLES ``` _See code: [dist/commands/upload-graphql-schema.ts](https://github.com/fauna/fauna-shell/blob/v1.2.1/dist/commands/upload-graphql-schema.ts)_ + # Development diff --git a/package.json b/package.json index 1a7dbe79..bab51cc4 100644 --- a/package.json +++ b/package.json @@ -70,7 +70,7 @@ "build": "npm run build:app && npm run build:sea", "build:app": "esbuild --bundle ./src/user-entrypoint.mjs --platform=node --outfile=./dist/cli.cjs --format=cjs --inject:./sea/import-meta-url.js --define:import.meta.url=importMetaUrl", "build:sea": "node ./sea/build.cjs", - "format": "prettier -w src test package.json prettier.config.js eslint.config.mjs" + "format": "prettier -w ." }, "husky": { "hooks": { diff --git a/sea/README.md b/sea/README.md index 2413f9bb..0348a1dc 100644 --- a/sea/README.md +++ b/sea/README.md @@ -1,4 +1,5 @@ ### SEA (single executable application) + This directory contains the infrastructure for building `fauna-shell` as a single executable application. You can find the docs for SEA [here](https://nodejs.org/docs/latest-v22.x/api/single-executable-applications.html#single-executable-applications); since this feature is experimental, make sure you're looking at the same nodeJS version as the project uses; there will be breaking changes across nodeJS versions. The process generally looks like this: @@ -8,10 +9,13 @@ The process generally looks like this: 3. `build:sea` runs `./sea/build.cjs`. This nodeJS script detects the OS and builds an SEA for that OS. One of the inputs to this process is `./sea/config.json`, which specifies some paths and settings for the resulting build. We could optimize our builds here by enabling `useSnapshot` and `useCodeCache`, but that's likely not worth the effort until we have a (basic) perf benchmark in place. ### Versions of the CLI + 1. The raw (runnable!) ESM CLI can be invoked by `./src/user-entrypoint.mjs [subcommand] [args]`. 2. The built CJS CLI can be invoked by `./dist/cli.cjs [subcommand] [args]`. 3. The SEA CLI can be invoked by `./dist/fauna [subcommand] [args]`. ### Differences between versions + _All 3 versions should be runnable and behave the same, with these exceptions:_ + - Currently, no exceptions. diff --git a/sea/build.cjs b/sea/build.cjs index 123686a5..66416f62 100644 --- a/sea/build.cjs +++ b/sea/build.cjs @@ -3,7 +3,8 @@ const os = require("node:os"); const { execSync } = require("node:child_process"); const fs = require("node:fs"); -const run = (command, options) => execSync(command, { ...options, encoding: "utf-8" }); +const run = (command, options) => + execSync(command, { ...options, encoding: "utf-8" }); const platform = os.platform(); if (platform === "linux") { @@ -49,7 +50,7 @@ function buildSEAForWindows() { // run(`${signtool} remove /s /c /u .\\dist\\fauna.exe`); run( "npx postject .\\dist\\fauna.exe NODE_SEA_BLOB .\\dist\\sea.blob ^ \ - --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2" + --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2", ); // run(`${signtool} sign /fd SHA256 .\\dist\\fauna.exe`); run("chmod +x ./dist/fauna"); diff --git a/sea/config.json b/sea/config.json index 858e6b90..c07386a4 100644 --- a/sea/config.json +++ b/sea/config.json @@ -3,5 +3,5 @@ "output": "./dist/sea.blob", "disableExperimentalSEAWarning": true, "useSnapshot": false, - "useCodeCache": false, + "useCodeCache": false } diff --git a/sea/import-meta-url.js b/sea/import-meta-url.js index 1da9d92f..c94ee6a3 100644 --- a/sea/import-meta-url.js +++ b/sea/import-meta-url.js @@ -1,4 +1,4 @@ // this is being used as an eslint plugin to map from CJS' __filename/__dirname // to ESM's meta.import.url. this lets us write statements using meta.import.url // in our source code that actually use CJS primitives after build. -export let importMetaUrl = require('url').pathToFileURL(__filename); +export let importMetaUrl = require("url").pathToFileURL(__filename);