From d83ee292c85e9d217846c52e82670b33955bb0a0 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Tue, 25 Jun 2024 10:16:30 -0400 Subject: [PATCH 1/4] Add macro to publish alpha --- package.json | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index d40b83b..5f67314 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,10 @@ { "name": "@carto/api-client", - "private": true, + "version": "0.0.1-0", + "publishConfig": { + "access": "public", + "tag": "alpha" + }, "packageManager": "yarn@4.2.2", "author": "Don McCurdy ", "license": "UNLICENSED", @@ -31,7 +35,11 @@ "coverage": "vitest run --coverage", "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check", "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write", - "clean": "rimraf build/*" + "clean": "rimraf build/*", + "version": "git add -u", + "prepack": "yarn clean && yarn build", + "prepublish": "yarn lint && yarn test", + "postpublish": "git push && git push --tags" }, "files": [ "build", @@ -76,5 +84,6 @@ "vite": "^5.2.10", "vitest": "1.6.0", "vue": "^3.4.27" - } + }, + "stableVersion": "0.0.0" } From 8f229a246bf4f5d7eba6335d187df5f240141a62 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Tue, 25 Jun 2024 11:06:13 -0400 Subject: [PATCH 2/4] Update docs --- CHANGELOG.md | 7 +++++++ CONTRIBUTING.md | 40 +++++++++++++++++++++++++++++++++++++--- README.md | 27 +++++++++++++-------------- 3 files changed, 57 insertions(+), 17 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..10d6068 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# CHANGELOG + +## 0.0 + +### 0.0.1 (UNRELEASED) + +- Initial release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84436a0..de60fa0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,43 @@ # Contributing +## Local development requirements + +- Yarn v4+ +- Node.js v18+ + ## Quickstart -TODO +```bash +# install dependencies +yarn + +# build package once +yarn build + +# build package and watch for changes +yarn build --watch + +# build package, watch for changes, and start a local server for examples +yarn dev +``` + +After running `yarn dev`, a browser window will open with links to examples. Local URL will be `localhost:5173`, or may use another available port number. + +Tests, coverage, and other developmen-related scripts are defined in `package.json#scripts`. + +```bash +# run tests once +yarn test + +# run tests and watch for changes +yarn test:watch + +# run tests and gather code coverage +yarn coverage -## Dependencies +# lint for style and formatting errors +yarn lint -New `dependencies` are added to individual packages in `packages/*` as required. New `devDependencies` are added to the workspace root `package.json` only. The `devDependencies` for all `packages/*/package.json` should be empty. +# fix style and formatting errors +yarn format +``` diff --git a/README.md b/README.md index 3cf130f..900d289 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,23 @@ # `@carto/api-client` -## References +WORK IN PROGRESS. -- [Product feature brief](https://docs.google.com/document/d/1ZWiVB_rgXf1WAEF1TjJgEHxp92kREYQrWG3O8jYV0Zk/edit) -- [Architecture document](https://app.shortcut.com/cartoteam/write/IkRvYyI6I3V1aWQgIjY2MzE1NDU0LTIyZTAtNDI4YS04NzMzLTc3YzZjN2I2MjVjYSI=?commentId=e509d33c6cdedf90599a5d3a937336d8e&commentThreadId=e7dbf03c9bd7b0fd3de40ebacbea67ee9) +## Installation -## Quickstart +Install `@carto/api-client`: ```bash -# install dependencies -yarn +npm install --save @carto/api-client +``` -# build package once -yarn build +## Documentation -# build package and watch for changes -yarn build --watch +WORK IN PROGRESS. -# build package, watch for changes, and start a local server for examples -yarn dev -``` +## Versioning + +Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/). + +## License -After running `yarn dev`, a browser window should open with links to examples. Unless a different port number is required, the local URL will be `localhost:5173`. +UNLICENSED. WORK IN PROGRESS. From 435ff524ea9ce8c82f0957db00354f068d4d44c2 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Tue, 25 Jun 2024 11:23:05 -0400 Subject: [PATCH 3/4] Add release docs --- CONTRIBUTING.md | 23 +++++++++++++++++++++++ package.json | 11 ++++------- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de60fa0..01332d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,3 +41,26 @@ yarn lint # fix style and formatting errors yarn format ``` + +## Releases + +> **TODO:** Configure an automatic release process with GitHub actions. + +1. Create a new version + ```bash + yarn version [ major | minor | patch | prerelease ] + ``` +2. Update changelog and commit + ```bash + git add -u + git commit -m "vX.Y.Z" + git tag -a "vX.Y.Z" + ``` +3. Publish to npm + ```bash + yarn npm publish [ --tag alpha ] + ``` +4. Push to GitHub + ```bash + git push && git push --tags + ``` diff --git a/package.json b/package.json index 5f67314..831e65b 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,11 @@ { "name": "@carto/api-client", - "version": "0.0.1-0", + "version": "0.0.1-1", "publishConfig": { "access": "public", "tag": "alpha" }, - "packageManager": "yarn@4.2.2", + "packageManager": "yarn@4.3.1", "author": "Don McCurdy ", "license": "UNLICENSED", "type": "module", @@ -36,10 +36,8 @@ "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check", "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write", "clean": "rimraf build/*", - "version": "git add -u", "prepack": "yarn clean && yarn build", - "prepublish": "yarn lint && yarn test", - "postpublish": "git push && git push --tags" + "prepublish": "yarn lint && yarn test" }, "files": [ "build", @@ -84,6 +82,5 @@ "vite": "^5.2.10", "vitest": "1.6.0", "vue": "^3.4.27" - }, - "stableVersion": "0.0.0" + } } From 5e7b183800a9c95ce274153198e2fccc8128b875 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Tue, 25 Jun 2024 18:31:32 -0400 Subject: [PATCH 4/4] Add basic API docs to readme --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/README.md b/README.md index 900d289..2e6ef17 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,95 @@ npm install --save @carto/api-client WORK IN PROGRESS. +### Fetching data + +```javascript +import { vectorTableSource } from '@carto/api-client'; + +const data = vectorTableSource({ + accessToken: '••••', + connectionName: 'carto_dw', + tableName: 'carto-demo-data.demo_tables.retail_stores' +}); + +const { widgetSource } = await data; + +// → {name: string; value: number}[] +const categories = await widgetSource.getCategories({ + column: 'store_type', + operation: 'count', +}); + +// → {value: number} +const formula = await widgetSource.getFormula({operation: 'count'}); + +// → {totalCount: number; rows: Record[]} +const table = await widgetSource.getTable({ + columns: ['a', 'b', 'c'], + sortBy: ['a'], + rowsPerPage: 20 +}); + +... +``` + +### Column filter + +To filter the widget source by a non-geospatial column, pass a `filters` +property to the source factory function. + +```javascript +import { vectorTableSource } from '@carto/api-client'; + +const data = vectorTableSource({ + accessToken: '••••', + connectionName: 'carto_dw', + tableName: 'carto-demo-data.demo_tables.retail_stores', + filters: { + 'store_type': {owner: 'widget-id', values: ['retail']} + } +}); +``` + +By default, filters affect all layers and widgets using a given data source. To +exclude a particular widget from the filter, pass a `filterOwner` parameter +matching the filters from which it should be excluded. In some cases, a widget's +results should not be affected by a filter that the widget itself created. + +```javascript +// → {name: string; value: number}[] +const categories = await widgetSource.getCategories({ + filterOwner: 'widget-id', + column: 'store_type', + operation: 'count', +}); +``` + +### Spatial filter + +To filter the widget source by a geospatial column, including the map viewport, +pass a `spatialFilter` parameter (GeoJSON Polygon or MultiPolygon geometry) to any widget data fetching function. + +```javascript +// → {name: string; value: number}[] +const categories = await widgetSource.getCategories({ + column: 'store_type', + operation: 'count', + spatialFilter: { + type: "Polygon" + coordinates: [ + [ + [-74.0562, 40.8331], + [-74.0562, 40.6933], + [-73.8734, 40.6933], + [-73.8734, 40.8331], + [-74.0562, 40.8331] + ] + ], + } +}); +``` + ## Versioning Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/).