diff --git a/.env.sample b/.env.sample index 4c85800..8a921e4 100644 --- a/.env.sample +++ b/.env.sample @@ -1,27 +1,12 @@ -# next-leaflet - config version 0.1.0 +# next-leaflet - config version 0.2.0 # ━━ An optimized tech stack for efficiency. ━━ # Need help? mail@thijmenheuvelink.nl +# Instruct Docker to execute the runtime in either production or developer mode. +# ┗━ Accepts: Boolean ━━ Default: "true" +PRODUCTION= "true" -# ━━ Docker ━━ - -# Docker deploy modifier, either puts the stack in development or production mode. -# ┗━ Options: "dev" or "prod" ━━ default: "dev" -COMPOSE_PROFILES= "dev" - -# Docker application port, which port the web app will listen on. -# ┗━ Options: "number" ━━ default: "3000" -NEXT_PORT= "3000" - -# Docker pocketbase port, this is the port the backend listens on. -# ┗━ Options: "number" ━━ default: "8090" -POCKETBASE_PORT= "8090" - - -# ━━ Next ━━ - -# Pocketbase Endpoint, public address to the backend. -# ┗━ Options: "number" ━━ default: "http://localhost:8090" ━ example: "https://pb.leaflet.app" -NEXT_PUBLIC_POCKETBASE_URL = "http://localhost:8090" - +# Port to listen and serve your web app on. +# ┗━ Accepts: Integer ━━ Default: "3000" +PORT= "3000" diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 63e88b6..82c7fa2 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -2,6 +2,8 @@ name: Deploy on: push: + # Branch on which to automatically run the deploy-action. + # ┗━ Options: branch.name ━━ example: "main" branches: main jobs: @@ -20,8 +22,9 @@ jobs: sudo git clone https://github.com/${{github.repository}} . sudo git clean -f + sudo git checkout -f sudo git pull - + echo '${{ secrets.APP_ENV }}' > .env sudo docker-compose pull @@ -39,4 +42,4 @@ jobs: cd ~/env/${{github.event.repository.name}} sudo docker-compose down - sudo docker-compose up -d + sudo docker-compose up -d --remove-orphans diff --git a/.gitignore b/.gitignore index 3c22ea4..add25e3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ # Environment -.env -.env*.local +.env* +!.env.sample # Next.JS diff --git a/.vscode/settings.json b/.vscode/settings.json index 4ee0c14..cda4553 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,12 +1,13 @@ { "files.exclude": { + "src/backend/routes/nginx.conf": true, "src/locales/i18n.ts": true, "package-lock.json": true, "postcss.config.js": true, ".eslintrc.json": true, - "middleware.ts": true, "next-env.d.ts": true, "node_modules": true, + "**/.gitkeep": true, "LICENSE.md": true, "debug.log": true, ".vscode": true, diff --git a/README.md b/README.md index cb23b70..5874c8b 100644 --- a/README.md +++ b/README.md @@ -1,142 +1,186 @@ -# Wiki +# next-leaflet + +An optimized tech stack for efficiency, an all-in-one solution to quickly build modern web apps. + +![preview](https://i.imgur.com/oulW1VO.png) -An open-source wiki built with Pocketbase as backend, based on [next-leaflet](https://github.com/ThijmenGThN/next-leaflet) (a template), easily deploy this yourself via the instructions below. -![preview](https://i.imgur.com/9tsGgDn.png) ### Powered by - [NextJS](https://nextjs.org) - [Pocketbase](https://pocketbase.io) -## Development -
Instructions -1. Install the required dependencies: - - [NodeJS](https://nodejs.org) - - [Docker](https://docker.com/get-started/) +### Features + +- [Realtime Database](https://pocketbase.io) +- [Authentication](https://pocketbase.io/docs/authentication/) +- [File Storage](https://pocketbase.io/docs/files-handling/) +- [Localization](https://next-intl-docs.vercel.app) + + + +### Includes -2. Clone the repository to your system. +- [Tailwind](https://tailwindcss.com) +- [Gravatar](https://gravatar.com) +- [Heroicons](https://heroicons.com) +- [HeadlessUI](https://headlessui.com) - 1. - ```sh - git clone https://github.com/ThijmenGThN/Wiki - ``` - 2. - ```sh - cd Wiki - ``` -3. Preparing the environment, it is recommend to use the sample file. +## Getting Started - 1. - ```sh - cp sample.env .env - ``` +
Development - 2. - ```sh - nano .env - ``` +### Dependencies -4. Install the required packages, by default we do this with npm. +- Install docker and docker compose. + + - Windows: [Docker Desktop](https://www.docker.com/get-started/) + - Linux: [Guide from Digital Ocean](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04) + - Ubuntu >20.04: [Guide from Thijmen Heuvelink](https://wiki.thijmenheuvelink.nl/linux/install-docker) - ``` - npm install - ``` +### Development -5. Running Next.js for development. +> Ensure that you've [cloned](https://git-scm.com/docs/git-clone) the repository and are on the correct path. - ```sh - npm run dev - ``` +#### Start -6. Starting pocketbase via docker. +``` docker compose up ``` - ```sh - docker-compose up - ``` - > Pocketbase can later be closed via `CTRL + C` +The stack is now accessible on your preferred browser at http://localhost:3000, the pocketbase interface can be found at http://localhost:3000/pb/_/ + +#### Stop + +To stop the stack from running simply execute the ` CTRL + C ` shortcut.
-## Deployment -
Instructions -1. Install the required dependencies: - - [Docker](https://docker.com/get-started/) +
Production + +### Preparation + +1. Create a ` .env ` file: + - Locate the ` .env.sample ` file in your project directory. + - Duplicate or copy the contents of this file. + - Rename the duplicate or copied file to ` .env `. + +2. Configure the environment variable: + - Open the ` .env ` file in a text editor. + - Locate the line that defines the ` PRODUCTION ` variable. + - Set the value of ` PRODUCTION ` to ` "true" ` (include the quotes). -2. Clone the repository to your system. +### Production - 1. - ```sh - git clone https://github.com/ThijmenGThN/Wiki - ``` +#### Start - 2. - ```sh - cd Wiki - ``` +> Unlike in the development steps we now add the ` -d ` flag which makes the service run in the background. -3. Preparing the environment, it is recommend to use the sample file. +``` docker compose up -d ``` - 1. - ```sh - cp sample.env .env - ``` +The stack is now accessible on your preferred browser at http://localhost:3000 or on a differently defined port as stated in the `.env` file, the pocketbase interface can be found at http://localhost:3000/pb/_/ - 2. - ```sh - nano .env - ``` -4. Deploying your app with docker. - ```sh - docker-compose up -d - ``` - > To stop your app from running, execute the following: `docker compose down` +#### Stop + +``` docker compose down ```
-### Deployment - GitHub Actions -
Instructions +## Fundamentals + +
Install Node Packages + +#### Install + +``` docker compose exec next npm i -D ``` + +#### Remove -> **IMPORTANT** The CI/CD workflow for next-leaflet has been setup in a way where it'll connect to any VPS via SSH as defined in the Repository Secrets. +``` docker compose exec next npm r ``` -1. Prepare your VPS. +
- 1. Install the required dependencies: +> ` NPM ` ` MODULES ` - - [Docker](https://docker.com/get-started/) -2. Configure your runner. +
Next Navigation API - 1. Within Github navigate to - - ` Settings > Secrets and variables > Actions ` +Instead of using `next/navigation` you should opt for the helper at ` @helpers/navigation `, this is a replacement required by ` next-intl ` it offers the same functionality. - 2. Create the following repository secrets: +
- Name|Expects|Description - -|-|- - SSH_KEY|Private Key|Generate a new ssh key without a password. - SSH_HOST|IP Address|The address of your server with an Actions (runner) active. - SSH_USER|Username|Host system user where next-leaflet should be deploy on. - SSH_PORT|Port Number|This usually refers to the default ssh port 22. - APP_ENV|Environment|A copy of .env.sample with adjusted values for deployment. +> ` Link ` ` useRouter ` ` Redirect ` ` usePathname ` -3. Enable the workflow. - 1. Designate a trigger branch within the ` .github/deploy.yml ` file. +
Accessing Pocketbase - > Any change pushed to the targeted branch should now trigger a request to deploy next-leaflet via docker-compose on the designated VPS. +Pocketbase has a client executable, below is an example that outputs all available commands. You can learn more on how to use it [here](https://pocketbase.io/docs). +``` docker compose exec pocketbase pocketbase --help ```
+ +> ` CLI ` + + +
Schema Snapshots + +Executing the following will generate a schema snapshot in ` src/backend/migrations `, note that this process does not save any collection data. + +``` docker compose exec pocketbase pocketbase migrate collections ``` + +
+ +> ` Pocketbase ` ` Migrations ` + + + +## Extras + +
Continuous Integration + +### Preparation + +> The workflow has been set up to connect to any VPS via SSH as defined in the Repository Secrets. + +1. Install docker and docker compose on your VPS. + + - Windows: [Docker Desktop](https://www.docker.com/get-started/) + - Linux: [Guide from Digital Ocean](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04) + - Ubuntu >20.04: [Guide from Thijmen Heuvelink](https://wiki.thijmenheuvelink.nl/linux/install-docker) + +2. Setup a Runner on GitHub + + 1. Create a new Runner + + - Navigate to ` Settings > Actions > Runners ` + + > To set up a new self-hosted runner, follow the instructions provided by GitHub to configure the runner to listen for jobs. It is advisable to install it as a service. + + 2. Define environment variables + + - Navigate and create new secrets in `Settings > Secrets and variables > Actions` + + Name|Expects|Description + -|-|- + SSH_KEY|Private Key|Generated private ssh-key which will beused to access the VPS. + SSH_HOST|IP Address|The address of your VPS that runs theGitHub Actions Runner. + SSH_USER|Username|System user which should be utilized for deployments. + SSH_PORT|Port Number|The port that will be used to connectwith the VPS, default is 22. + APP_ENV|Environment|Contents of the ` .env ` file withadjusted values for deployment. + +### Activation + +Define the branch in `.github/deploy.yml` and modify it from being ` disabled ` to an existing branch. Any modifications made to that particular branch will automatically trigger the Action, deploying your stack to your VPS. + +
\ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 33d9f97..bf7bbb3 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,31 +5,43 @@ services: # ┏━ NextJS | A framework to build web apps. next: image: node:20-alpine - command: sh -c "npm ci && npm run build && npm start" + command: > + sh -c 'npm ci && if [ "$PRODUCTION" == "true" ]; + then npm run build && npm start + else npm run dev + fi' + container_name: next restart: unless-stopped - profiles: ["prod"] - env_file: .env working_dir: /app - ports: [$NEXT_PORT:3000] - depends_on: [pocketbase] - volumes: + depends_on: [ pocketbase ] + volumes: - next_build:/app/.next - - next_modules:/app/node_modules + - ./node_modules:/app/node_modules - ./:/app - # ┏━ Pocketbase | This'll provide our backend. + # ┏━ Pocketbase | An inclusive BAAS database provider. pocketbase: - image: ghcr.io/muchobien/pocketbase:latest + image: ghcr.io/muchobien/pocketbase:0.20 + container_name: pocketbase restart: unless-stopped - ports: ["$POCKETBASE_PORT:8090"] - env_file: .env - volumes: + attach: false + volumes: - pocketbase_data:/pb_data - ./src/backend/types.d.ts:/pb_data/types.d.ts - ./src/backend/migrations:/pb_migrations - ./src/backend/hooks:/pb_hooks - -volumes: + + # ┏━ Nginx | Ensures same origin for both services. + nginx: + image: nginx:1.25 + depends_on: [ next, pocketbase ] + container_name: router + restart: unless-stopped + volumes: [ "./src/backend/routes:/etc/nginx/conf.d" ] + ports: [ "${PORT:-3000}:3000" ] + attach: false + +volumes: next_build: next_modules: pocketbase_data: diff --git a/package-lock.json b/package-lock.json index 3297a79..0205876 100644 --- a/package-lock.json +++ b/package-lock.json @@ -23,7 +23,7 @@ "autoprefixer": "^10.0.1", "eslint": "^8", "eslint-config-next": "14.0.4", - "pocketbase": "^0.20.0", + "pocketbase": "^0.20", "postcss": "^8", "react-markdown": "^9.0.1", "remark-gfm": "^4.0.0", @@ -3914,9 +3914,9 @@ } }, "node_modules/mdast-util-to-hast": { - "version": "13.0.2", - "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.0.2.tgz", - "integrity": "sha512-U5I+500EOOw9e3ZrclN3Is3fRpw8c19SMyNZlZ2IS+7vLsNzb2Om11VpIVOR+/0137GhZsFEF6YiKD5+0Hr2Og==", + "version": "13.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.1.0.tgz", + "integrity": "sha512-/e2l/6+OdGp/FB+ctrJ9Avz71AN/GRH3oi/3KAx/kMnoUsD6q0woXlDT8lLEeViVKE7oZxE7RXzvO3T8kF2/sA==", "dev": true, "dependencies": { "@types/hast": "^3.0.0", @@ -3926,7 +3926,8 @@ "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", - "unist-util-visit": "^5.0.0" + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" }, "funding": { "type": "opencollective", @@ -5381,9 +5382,9 @@ } }, "node_modules/remark-rehype": { - "version": "11.0.0", - "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.0.0.tgz", - "integrity": "sha512-vx8x2MDMcxuE4lBmQ46zYUDfcFMmvg80WYX+UNLeG6ixjdCCLcw1lrgAukwBTuOFsS78eoAedHGn9sNM0w7TPw==", + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.0.tgz", + "integrity": "sha512-z3tJrAs2kIs1AqIIy6pzHmAHlF1hWQ+OdY4/hv+Wxe35EhyLKcajL33iUEn3ScxtFox9nUvRufR/Zre8Q08H/g==", "dev": true, "dependencies": { "@types/hast": "^3.0.0", diff --git a/package.json b/package.json index b51a03a..624a365 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,6 @@ { "name": "next-leaflet", "version": "0.1.0", - "private": true, "scripts": { "dev": "next dev", "build": "next build", @@ -24,7 +23,7 @@ "autoprefixer": "^10.0.1", "eslint": "^8", "eslint-config-next": "14.0.4", - "pocketbase": "^0.20.0", + "pocketbase": "^0.20", "postcss": "^8", "react-markdown": "^9.0.1", "remark-gfm": "^4.0.0", diff --git a/public/.gitkeep b/public/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/public/appicon.webp b/public/appicon.webp new file mode 100644 index 0000000..4e91ceb Binary files /dev/null and b/public/appicon.webp differ diff --git a/public/favicon.ico b/public/favicon.ico index 718d6fe..ff318da 100644 Binary files a/public/favicon.ico and b/public/favicon.ico differ diff --git a/public/manifest.json b/public/manifest.json new file mode 100644 index 0000000..b65c6ad --- /dev/null +++ b/public/manifest.json @@ -0,0 +1,21 @@ +{ + "name": "Wiki • Thijmen Heuvelink", + "short_name": "Wiki", + "description": "A catalogue of saved knowledge served via a web-based app.", + "start_url": "/", + "display": "standalone", + "theme_color": "#11999e", + "background_color": "#ffffff", + "icons": [ + { + "src": "appicon.webp", + "type": "image/webp", + "sizes": "512x512" + } + ], + "ios": { + "apple-mobile-web-app-capable": true, + "apple-mobile-web-app-title": "Wiki", + "apple-mobile-web-app-status-bar-style": "white" + } +} \ No newline at end of file diff --git a/src/assets/.gitkeep b/src/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/assets/logo.webp b/src/assets/logo.webp index 883d456..d0584bd 100644 Binary files a/src/assets/logo.webp and b/src/assets/logo.webp differ diff --git a/src/backend/hooks/.gitkeep b/src/backend/hooks/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/backend/migrations/.gitkeep b/src/backend/migrations/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/backend/migrations/0_collections_snapshot.js b/src/backend/migrations/0_collections_snapshot.js new file mode 100644 index 0000000..1e4437f --- /dev/null +++ b/src/backend/migrations/0_collections_snapshot.js @@ -0,0 +1,135 @@ +/// +migrate((db) => { + const snapshot = [ + { + "id": "s8zi1h26nbn31g7", + "created": "2023-12-15 15:12:10.679Z", + "updated": "2024-01-12 15:29:23.052Z", + "name": "notifications", + "type": "base", + "system": false, + "schema": [ + { + "system": false, + "id": "ljdfrp8l", + "name": "user", + "type": "relation", + "required": true, + "presentable": false, + "unique": false, + "options": { + "collectionId": "_pb_users_auth_", + "cascadeDelete": true, + "minSelect": null, + "maxSelect": 1, + "displayFields": null + } + }, + { + "system": false, + "id": "qo8kovua", + "name": "title", + "type": "text", + "required": true, + "presentable": false, + "unique": false, + "options": { + "min": null, + "max": null, + "pattern": "" + } + }, + { + "system": false, + "id": "4q4cvndf", + "name": "message", + "type": "text", + "required": true, + "presentable": false, + "unique": false, + "options": { + "min": null, + "max": null, + "pattern": "" + } + } + ], + "indexes": [], + "listRule": "@request.auth.id = user.id", + "viewRule": "@request.auth.id = user.id", + "createRule": "@request.auth.id != ''", + "updateRule": null, + "deleteRule": "@request.auth.id = user.id", + "options": {} + }, + { + "id": "_pb_users_auth_", + "created": "2023-12-21 10:23:07.968Z", + "updated": "2023-12-21 10:23:07.972Z", + "name": "users", + "type": "auth", + "system": false, + "schema": [ + { + "system": false, + "id": "users_name", + "name": "name", + "type": "text", + "required": false, + "presentable": false, + "unique": false, + "options": { + "min": null, + "max": null, + "pattern": "" + } + }, + { + "system": false, + "id": "users_avatar", + "name": "avatar", + "type": "file", + "required": false, + "presentable": false, + "unique": false, + "options": { + "mimeTypes": [ + "image/jpeg", + "image/png", + "image/svg+xml", + "image/gif", + "image/webp" + ], + "thumbs": null, + "maxSelect": 1, + "maxSize": 5242880, + "protected": false + } + } + ], + "indexes": [], + "listRule": "id = @request.auth.id", + "viewRule": "id = @request.auth.id", + "createRule": "", + "updateRule": "id = @request.auth.id", + "deleteRule": "id = @request.auth.id", + "options": { + "allowEmailAuth": true, + "allowOAuth2Auth": true, + "allowUsernameAuth": true, + "exceptEmailDomains": null, + "manageRule": null, + "minPasswordLength": 8, + "onlyEmailDomains": null, + "onlyVerified": false, + "requireEmail": false + } + } + ]; + + const collections = snapshot.map((item) => new Collection(item)); + + return Dao(db).importCollections(collections, true, null); +}, (db) => { + return null; +}) diff --git a/src/backend/migrations/1702690089_collections_snapshot.js b/src/backend/migrations/1702690089_collections_snapshot.js index 1d35f54..872cf4c 100644 --- a/src/backend/migrations/1702690089_collections_snapshot.js +++ b/src/backend/migrations/1702690089_collections_snapshot.js @@ -1,4 +1,4 @@ -/// +/// migrate((db) => { const snapshot = [ { diff --git a/src/backend/migrations/1702754278_updated_users.js b/src/backend/migrations/1702754278_updated_users.js index 950463a..38d3474 100644 --- a/src/backend/migrations/1702754278_updated_users.js +++ b/src/backend/migrations/1702754278_updated_users.js @@ -1,4 +1,4 @@ -/// +/// migrate((db) => { const dao = new Dao(db) const collection = dao.findCollectionByNameOrId("_pb_users_auth_") diff --git a/src/backend/migrations/1702755267_created_media.js b/src/backend/migrations/1702755267_created_media.js index f4833d7..4fb2f5c 100644 --- a/src/backend/migrations/1702755267_created_media.js +++ b/src/backend/migrations/1702755267_created_media.js @@ -1,4 +1,4 @@ -/// +/// migrate((db) => { const collection = new Collection({ "id": "kblyx6ommv2lhn8", diff --git a/src/backend/migrations/1702772852_updated_posts.js b/src/backend/migrations/1702772852_updated_posts.js index 41f0be1..63bb6f6 100644 --- a/src/backend/migrations/1702772852_updated_posts.js +++ b/src/backend/migrations/1702772852_updated_posts.js @@ -1,4 +1,4 @@ -/// +/// migrate((db) => { const dao = new Dao(db) const collection = dao.findCollectionByNameOrId("5fzd8cy613bgmuo") diff --git a/src/backend/routes/nginx.conf b/src/backend/routes/nginx.conf new file mode 100644 index 0000000..e547b56 --- /dev/null +++ b/src/backend/routes/nginx.conf @@ -0,0 +1,30 @@ +server { + listen 3000; + + proxy_http_version 1.1; + proxy_read_timeout 180s; + + proxy_set_header Host $host; + proxy_set_header Connection "upgrade"; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-By $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + location /pb { + rewrite /pb/(.*) /$1 break; + proxy_pass http://pocketbase:8090; + } + + location / { + rewrite /(.*) /$1 break; + proxy_pass http://next:3000; + } + + error_page 502 /nginx.html; + location = /nginx.html { + root /etc/nginx/conf.d; + internal; + } +} \ No newline at end of file diff --git a/src/backend/routes/nginx.html b/src/backend/routes/nginx.html new file mode 100644 index 0000000..d1c397e --- /dev/null +++ b/src/backend/routes/nginx.html @@ -0,0 +1,26 @@ + + + + + + One moment, we'll be back soon! + + + +
+

We’ll be back soon!

+

The server is currently in the process of starting up. Rest assured, it won’t take long until we are fully up and running.

+
+ + + \ No newline at end of file diff --git a/src/backend/types.d.ts b/src/backend/types.d.ts index b8ddab1..68e0ae2 100644 --- a/src/backend/types.d.ts +++ b/src/backend/types.d.ts @@ -1,3 +1,4 @@ +// 1704272575 // GENERATED CODE - DO NOT MODIFY BY HAND // ------------------------------------------------------------------- @@ -194,6 +195,20 @@ declare var $template: template.Registry */ declare function readerToString(reader: any, maxBytes?: number): string; +/** + * sleep pauses the current goroutine for at least the specified user duration (in ms). + * A zero or negative duration returns immediately. + * + * Example: + * + * ```js + * sleep(250) // sleeps for 250ms + * ``` + * + * @group PocketBase + */ +declare function sleep(milliseconds: number): void; + /** * arrayOf creates a placeholder array of the specified models. * Usually used to populate DB result into an array of models. @@ -1627,8 +1642,8 @@ namespace os { * than ReadFrom. This is used to permit ReadFrom to call io.Copy * without leading to a recursive call to ReadFrom. */ - type _subSGceb = File - interface fileWithoutReadFrom extends _subSGceb { + type _subgUszO = File + interface fileWithoutReadFrom extends _subgUszO { } interface fileWithoutReadFrom { /** @@ -2285,8 +2300,8 @@ namespace os { /** * File represents an open file descriptor. */ - type _subzrZng = file - interface File extends _subzrZng { + type _subGXkEd = file + interface File extends _subGXkEd { } /** * A FileInfo describes a file and is returned by Stat and Lstat. @@ -2687,6 +2702,156 @@ namespace filepath { } } +namespace security { + interface s256Challenge { + /** + * S256Challenge creates base64 encoded sha256 challenge string derived from code. + * The padding of the result base64 string is stripped per [RFC 7636]. + * + * [RFC 7636]: https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 + */ + (code: string): string + } + interface md5 { + /** + * MD5 creates md5 hash from the provided plain text. + */ + (text: string): string + } + interface sha256 { + /** + * SHA256 creates sha256 hash as defined in FIPS 180-4 from the provided text. + */ + (text: string): string + } + interface sha512 { + /** + * SHA512 creates sha512 hash as defined in FIPS 180-4 from the provided text. + */ + (text: string): string + } + interface hs256 { + /** + * HS256 creates a HMAC hash with sha256 digest algorithm. + */ + (text: string, secret: string): string + } + interface hs512 { + /** + * HS512 creates a HMAC hash with sha512 digest algorithm. + */ + (text: string, secret: string): string + } + interface equal { + /** + * Equal compares two hash strings for equality without leaking timing information. + */ + (hash1: string, hash2: string): boolean + } + // @ts-ignore + import crand = rand + interface encrypt { + /** + * Encrypt encrypts data with key (must be valid 32 char aes key). + */ + (data: string|Array, key: string): string + } + interface decrypt { + /** + * Decrypt decrypts encrypted text with key (must be valid 32 chars aes key). + */ + (cipherText: string, key: string): string|Array + } + interface parseUnverifiedJWT { + /** + * ParseUnverifiedJWT parses JWT and returns its claims + * but DOES NOT verify the signature. + * + * It verifies only the exp, iat and nbf claims. + */ + (token: string): jwt.MapClaims + } + interface parseJWT { + /** + * ParseJWT verifies and parses JWT and returns its claims. + */ + (token: string, verificationKey: string): jwt.MapClaims + } + interface newJWT { + /** + * NewJWT generates and returns new HS256 signed JWT. + */ + (payload: jwt.MapClaims, signingKey: string, secondsDuration: number): string + } + interface newToken { + /** + * Deprecated: + * Consider replacing with NewJWT(). + * + * NewToken is a legacy alias for NewJWT that generates a HS256 signed JWT. + */ + (payload: jwt.MapClaims, signingKey: string, secondsDuration: number): string + } + // @ts-ignore + import cryptoRand = rand + // @ts-ignore + import mathRand = rand + interface randomString { + /** + * RandomString generates a cryptographically random string with the specified length. + * + * The generated string matches [A-Za-z0-9]+ and it's transparent to URL-encoding. + */ + (length: number): string + } + interface randomStringWithAlphabet { + /** + * RandomStringWithAlphabet generates a cryptographically random string + * with the specified length and characters set. + * + * It panics if for some reason rand.Int returns a non-nil error. + */ + (length: number, alphabet: string): string + } + interface pseudorandomString { + /** + * PseudorandomString generates a pseudorandom string with the specified length. + * + * The generated string matches [A-Za-z0-9]+ and it's transparent to URL-encoding. + * + * For a cryptographically random string (but a little bit slower) use RandomString instead. + */ + (length: number): string + } + interface pseudorandomStringWithAlphabet { + /** + * PseudorandomStringWithAlphabet generates a pseudorandom string + * with the specified length and characters set. + * + * For a cryptographically random (but a little bit slower) use RandomStringWithAlphabet instead. + */ + (length: number, alphabet: string): string + } +} + +/** + * Package validation provides configurable and extensible rules for validating data of various types. + */ +namespace ozzo_validation { + /** + * Error interface represents an validation error + */ + interface Error { + [key:string]: any; + error(): string + code(): string + message(): string + setMessage(_arg0: string): Error + params(): _TygojaDict + setParams(_arg0: _TygojaDict): Error + } +} + /** * Package dbx provides a set of DB-agnostic and easy-to-use query building methods for relational databases. */ @@ -3023,14 +3188,14 @@ namespace dbx { /** * MssqlBuilder is the builder for SQL Server databases. */ - type _subKqIKr = BaseBuilder - interface MssqlBuilder extends _subKqIKr { + type _subeOzgU = BaseBuilder + interface MssqlBuilder extends _subeOzgU { } /** * MssqlQueryBuilder is the query builder for SQL Server databases. */ - type _subPIWQx = BaseQueryBuilder - interface MssqlQueryBuilder extends _subPIWQx { + type _subPYpyy = BaseQueryBuilder + interface MssqlQueryBuilder extends _subPYpyy { } interface newMssqlBuilder { /** @@ -3101,8 +3266,8 @@ namespace dbx { /** * MysqlBuilder is the builder for MySQL databases. */ - type _subtNrxE = BaseBuilder - interface MysqlBuilder extends _subtNrxE { + type _subshvgw = BaseBuilder + interface MysqlBuilder extends _subshvgw { } interface newMysqlBuilder { /** @@ -3177,14 +3342,14 @@ namespace dbx { /** * OciBuilder is the builder for Oracle databases. */ - type _subQvUWw = BaseBuilder - interface OciBuilder extends _subQvUWw { + type _subTukdT = BaseBuilder + interface OciBuilder extends _subTukdT { } /** * OciQueryBuilder is the query builder for Oracle databases. */ - type _subwnsWb = BaseQueryBuilder - interface OciQueryBuilder extends _subwnsWb { + type _suboNUbJ = BaseQueryBuilder + interface OciQueryBuilder extends _suboNUbJ { } interface newOciBuilder { /** @@ -3247,8 +3412,8 @@ namespace dbx { /** * PgsqlBuilder is the builder for PostgreSQL databases. */ - type _subGugrU = BaseBuilder - interface PgsqlBuilder extends _subGugrU { + type _subKWcqA = BaseBuilder + interface PgsqlBuilder extends _subKWcqA { } interface newPgsqlBuilder { /** @@ -3315,8 +3480,8 @@ namespace dbx { /** * SqliteBuilder is the builder for SQLite databases. */ - type _subJBzSP = BaseBuilder - interface SqliteBuilder extends _subJBzSP { + type _subsoHkv = BaseBuilder + interface SqliteBuilder extends _subsoHkv { } interface newSqliteBuilder { /** @@ -3415,8 +3580,8 @@ namespace dbx { /** * StandardBuilder is the builder that is used by DB for an unknown driver. */ - type _subFGyOQ = BaseBuilder - interface StandardBuilder extends _subFGyOQ { + type _subZtxuI = BaseBuilder + interface StandardBuilder extends _subZtxuI { } interface newStandardBuilder { /** @@ -3482,8 +3647,8 @@ namespace dbx { * DB enhances sql.DB by providing a set of DB-agnostic query building methods. * DB allows easier query building and population of data into Go variables. */ - type _subtJfhr = Builder - interface DB extends _subtJfhr { + type _subwSDJJ = Builder + interface DB extends _subwSDJJ { /** * FieldMapper maps struct fields to DB columns. Defaults to DefaultFieldMapFunc. */ @@ -4285,8 +4450,8 @@ namespace dbx { * Rows enhances sql.Rows by providing additional data query methods. * Rows can be obtained by calling Query.Rows(). It is mainly used to populate data row by row. */ - type _subWpZWm = sql.Rows - interface Rows extends _subWpZWm { + type _subkUEGQ = sql.Rows + interface Rows extends _subkUEGQ { } interface Rows { /** @@ -4643,8 +4808,8 @@ namespace dbx { }): string } interface structInfo { } - type _subrffRJ = structInfo - interface structValue extends _subrffRJ { + type _subtaShB = structInfo + interface structValue extends _subtaShB { } interface fieldInfo { } @@ -4683,8 +4848,8 @@ namespace dbx { /** * Tx enhances sql.Tx with additional querying methods. */ - type _subiGQlH = Builder - interface Tx extends _subiGQlH { + type _subgTasg = Builder + interface Tx extends _subgTasg { } interface Tx { /** @@ -4700,24 +4865,6 @@ namespace dbx { } } -/** - * Package validation provides configurable and extensible rules for validating data of various types. - */ -namespace ozzo_validation { - /** - * Error interface represents an validation error - */ - interface Error { - [key:string]: any; - error(): string - code(): string - message(): string - setMessage(_arg0: string): Error - params(): _TygojaDict - setParams(_arg0: _TygojaDict): Error - } -} - /** * Package exec runs external commands. It wraps os.StartProcess to make it * easier to remap stdin and stdout, connect I/O with pipes, and do other @@ -4844,214 +4991,82 @@ namespace exec { } } -namespace security { - interface s256Challenge { +namespace filesystem { + /** + * FileReader defines an interface for a file resource reader. + */ + interface FileReader { + [key:string]: any; + open(): io.ReadSeekCloser + } + /** + * File defines a single file [io.ReadSeekCloser] resource. + * + * The file could be from a local path, multipipart/formdata header, etc. + */ + interface File { + reader: FileReader + name: string + originalName: string + size: number + } + interface newFileFromPath { /** - * S256Challenge creates base64 encoded sha256 challenge string derived from code. - * The padding of the result base64 string is stripped per [RFC 7636]. - * - * [RFC 7636]: https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 + * NewFileFromPath creates a new File instance from the provided local file path. */ - (code: string): string + (path: string): (File) } - interface md5 { + interface newFileFromBytes { /** - * MD5 creates md5 hash from the provided plain text. + * NewFileFromBytes creates a new File instance from the provided byte slice. */ - (text: string): string + (b: string|Array, name: string): (File) } - interface sha256 { + interface newFileFromMultipart { /** - * SHA256 creates sha256 hash as defined in FIPS 180-4 from the provided text. + * NewFileFromMultipart creates a new File from the provided multipart header. */ - (text: string): string + (mh: multipart.FileHeader): (File) } - interface sha512 { + interface newFileFromUrl { /** - * SHA512 creates sha512 hash as defined in FIPS 180-4 from the provided text. + * NewFileFromUrl creates a new File from the provided url by + * downloading the resource and load it as BytesReader. + * + * Example + * + * ``` + * ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + * defer cancel() + * + * file, err := filesystem.NewFileFromUrl(ctx, "https://example.com/image.png") + * ``` */ - (text: string): string + (ctx: context.Context, url: string): (File) } - interface hs256 { + /** + * MultipartReader defines a FileReader from [multipart.FileHeader]. + */ + interface MultipartReader { + header?: multipart.FileHeader + } + interface MultipartReader { /** - * HS256 creates a HMAC hash with sha256 digest algorithm. + * Open implements the [filesystem.FileReader] interface. */ - (text: string, secret: string): string + open(): io.ReadSeekCloser } - interface hs512 { + /** + * PathReader defines a FileReader from a local file path. + */ + interface PathReader { + path: string + } + interface PathReader { /** - * HS512 creates a HMAC hash with sha512 digest algorithm. + * Open implements the [filesystem.FileReader] interface. */ - (text: string, secret: string): string - } - interface equal { - /** - * Equal compares two hash strings for equality without leaking timing information. - */ - (hash1: string, hash2: string): boolean - } - // @ts-ignore - import crand = rand - interface encrypt { - /** - * Encrypt encrypts data with key (must be valid 32 char aes key). - */ - (data: string|Array, key: string): string - } - interface decrypt { - /** - * Decrypt decrypts encrypted text with key (must be valid 32 chars aes key). - */ - (cipherText: string, key: string): string|Array - } - interface parseUnverifiedJWT { - /** - * ParseUnverifiedJWT parses JWT token and returns its claims - * but DOES NOT verify the signature. - * - * It verifies only the exp, iat and nbf claims. - */ - (token: string): jwt.MapClaims - } - interface parseJWT { - /** - * ParseJWT verifies and parses JWT token and returns its claims. - */ - (token: string, verificationKey: string): jwt.MapClaims - } - interface newJWT { - /** - * NewJWT generates and returns new HS256 signed JWT token. - */ - (payload: jwt.MapClaims, signingKey: string, secondsDuration: number): string - } - interface newToken { - /** - * Deprecated: - * Consider replacing with NewJWT(). - * - * NewToken is a legacy alias for NewJWT that generates a HS256 signed JWT token. - */ - (payload: jwt.MapClaims, signingKey: string, secondsDuration: number): string - } - // @ts-ignore - import cryptoRand = rand - // @ts-ignore - import mathRand = rand - interface randomString { - /** - * RandomString generates a cryptographically random string with the specified length. - * - * The generated string matches [A-Za-z0-9]+ and it's transparent to URL-encoding. - */ - (length: number): string - } - interface randomStringWithAlphabet { - /** - * RandomStringWithAlphabet generates a cryptographically random string - * with the specified length and characters set. - * - * It panics if for some reason rand.Int returns a non-nil error. - */ - (length: number, alphabet: string): string - } - interface pseudorandomString { - /** - * PseudorandomString generates a pseudorandom string with the specified length. - * - * The generated string matches [A-Za-z0-9]+ and it's transparent to URL-encoding. - * - * For a cryptographically random string (but a little bit slower) use RandomString instead. - */ - (length: number): string - } - interface pseudorandomStringWithAlphabet { - /** - * PseudorandomStringWithAlphabet generates a pseudorandom string - * with the specified length and characters set. - * - * For a cryptographically random (but a little bit slower) use RandomStringWithAlphabet instead. - */ - (length: number, alphabet: string): string - } -} - -namespace filesystem { - /** - * FileReader defines an interface for a file resource reader. - */ - interface FileReader { - [key:string]: any; - open(): io.ReadSeekCloser - } - /** - * File defines a single file [io.ReadSeekCloser] resource. - * - * The file could be from a local path, multipipart/formdata header, etc. - */ - interface File { - reader: FileReader - name: string - originalName: string - size: number - } - interface newFileFromPath { - /** - * NewFileFromPath creates a new File instance from the provided local file path. - */ - (path: string): (File) - } - interface newFileFromBytes { - /** - * NewFileFromBytes creates a new File instance from the provided byte slice. - */ - (b: string|Array, name: string): (File) - } - interface newFileFromMultipart { - /** - * NewFileFromMultipart creates a new File from the provided multipart header. - */ - (mh: multipart.FileHeader): (File) - } - interface newFileFromUrl { - /** - * NewFileFromUrl creates a new File from the provided url by - * downloading the resource and load it as BytesReader. - * - * Example - * - * ``` - * ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) - * defer cancel() - * - * file, err := filesystem.NewFileFromUrl(ctx, "https://example.com/image.png") - * ``` - */ - (ctx: context.Context, url: string): (File) - } - /** - * MultipartReader defines a FileReader from [multipart.FileHeader]. - */ - interface MultipartReader { - header?: multipart.FileHeader - } - interface MultipartReader { - /** - * Open implements the [filesystem.FileReader] interface. - */ - open(): io.ReadSeekCloser - } - /** - * PathReader defines a FileReader from a local file path. - */ - interface PathReader { - path: string - } - interface PathReader { - /** - * Open implements the [filesystem.FileReader] interface. - */ - open(): io.ReadSeekCloser + open(): io.ReadSeekCloser } /** * BytesReader defines a FileReader from bytes content. @@ -5065,8 +5080,8 @@ namespace filesystem { */ open(): io.ReadSeekCloser } - type _subDLaUX = bytes.Reader - interface bytesReadSeekCloser extends _subDLaUX { + type _subHVtTs = bytes.Reader + interface bytesReadSeekCloser extends _subHVtTs { } interface bytesReadSeekCloser { /** @@ -5451,7 +5466,7 @@ namespace forms { submit(...interceptors: InterceptorFunc[]): void } /** - * AppleClientSecretCreate is a [models.Admin] upsert (create/update) form. + * AppleClientSecretCreate is a form struct to generate a new Apple Client Secret. * * Reference: https://developer.apple.com/documentation/sign_in_with_apple/generate_and_validate_tokens */ @@ -5476,7 +5491,7 @@ namespace forms { */ privateKey: string /** - * Duration specifies how long the generated JWT token should be considered valid. + * Duration specifies how long the generated JWT should be considered valid. * The specified value must be in seconds and max 15777000 (~6months). */ duration: number @@ -6196,8 +6211,8 @@ namespace forms { /** * SettingsUpsert is a [settings.Settings] upsert (create/update) form. */ - type _subtmFEQ = settings.Settings - interface SettingsUpsert extends _subtmFEQ { + type _subxSkzb = settings.Settings + interface SettingsUpsert extends _subxSkzb { } interface newSettingsUpsert { /** @@ -6623,8 +6638,8 @@ namespace pocketbase { /** * appWrapper serves as a private CoreApp instance wrapper. */ - type _suboAkdh = CoreApp - interface appWrapper extends _suboAkdh { + type _subDghba = CoreApp + interface appWrapper extends _subDghba { } /** * PocketBase defines a PocketBase app launcher. @@ -6632,8 +6647,8 @@ namespace pocketbase { * It implements [CoreApp] via embedding and all of the app interface methods * could be accessed directly through the instance (eg. PocketBase.DataDir()). */ - type _subkOzHL = appWrapper - interface PocketBase extends _subkOzHL { + type _subQSfhg = appWrapper + interface PocketBase extends _subQSfhg { /** * RootCmd is the main console command */ @@ -6646,6 +6661,7 @@ namespace pocketbase { /** * optional default values for the console flags */ + defaultDev: boolean defaultDataDir: string // if not set, it will fallback to "./pb_data" defaultEncryptionEnv: string /** @@ -6821,93 +6837,235 @@ namespace template { } /** - * Package syscall contains an interface to the low-level operating system - * primitives. The details vary depending on the underlying system, and - * by default, godoc will display the syscall documentation for the current - * system. If you want godoc to display syscall documentation for another - * system, set $GOOS and $GOARCH to the desired system. For example, if - * you want to view documentation for freebsd/arm on linux/amd64, set $GOOS - * to freebsd and $GOARCH to arm. - * The primary use of syscall is inside other packages that provide a more - * portable interface to the system, such as "os", "time" and "net". Use - * those packages rather than this one if you can. - * For details of the functions and data types in this package consult - * the manuals for the appropriate operating system. - * These calls return err == nil to indicate success; otherwise - * err is an operating system error describing the failure. - * On most systems, that error has type syscall.Errno. + * Package io provides basic interfaces to I/O primitives. + * Its primary job is to wrap existing implementations of such primitives, + * such as those in package os, into shared public interfaces that + * abstract the functionality, plus some other related primitives. * - * Deprecated: this package is locked down. Callers should use the - * corresponding package in the golang.org/x/sys repository instead. - * That is also where updates required by new systems or versions - * should be applied. See https://golang.org/s/go1.4-syscall for more - * information. + * Because these interfaces and primitives wrap lower-level operations with + * various implementations, unless otherwise informed clients should not + * assume they are safe for parallel execution. */ -namespace syscall { - interface SysProcAttr { - chroot: string // Chroot. - credential?: Credential // Credential. - /** - * Ptrace tells the child to call ptrace(PTRACE_TRACEME). - * Call runtime.LockOSThread before starting a process with this set, - * and don't call UnlockOSThread until done with PtraceSyscall calls. - */ - ptrace: boolean - setsid: boolean // Create session. - /** - * Setpgid sets the process group ID of the child to Pgid, - * or, if Pgid == 0, to the new child's process ID. - */ - setpgid: boolean - /** - * Setctty sets the controlling terminal of the child to - * file descriptor Ctty. Ctty must be a descriptor number - * in the child process: an index into ProcAttr.Files. - * This is only meaningful if Setsid is true. - */ - setctty: boolean - noctty: boolean // Detach fd 0 from controlling terminal - ctty: number // Controlling TTY fd - /** - * Foreground places the child process group in the foreground. - * This implies Setpgid. The Ctty field must be set to - * the descriptor of the controlling TTY. - * Unlike Setctty, in this case Ctty must be a descriptor - * number in the parent process. - */ - foreground: boolean - pgid: number // Child's process group ID if Setpgid. - /** - * Pdeathsig, if non-zero, is a signal that the kernel will send to - * the child process when the creating thread dies. Note that the signal - * is sent on thread termination, which may happen before process termination. - * There are more details at https://go.dev/issue/27505. - */ - pdeathsig: Signal - cloneflags: number // Flags for clone calls (Linux only) - unshareflags: number // Flags for unshare calls (Linux only) - uidMappings: Array // User ID mappings for user namespaces. - gidMappings: Array // Group ID mappings for user namespaces. - /** - * GidMappingsEnableSetgroups enabling setgroups syscall. - * If false, then setgroups syscall will be disabled for the child process. - * This parameter is no-op if GidMappings == nil. Otherwise for unprivileged - * users this should be set to false for mappings work. - */ - gidMappingsEnableSetgroups: boolean - ambientCaps: Array // Ambient capabilities (Linux only) - useCgroupFD: boolean // Whether to make use of the CgroupFD field. - cgroupFD: number // File descriptor of a cgroup to put the new process into. - } - // @ts-ignore - import errorspkg = errors +namespace io { /** - * A RawConn is a raw network connection. - */ - interface RawConn { - [key:string]: any; - /** - * Control invokes f on the underlying connection's file + * Reader is the interface that wraps the basic Read method. + * + * Read reads up to len(p) bytes into p. It returns the number of bytes + * read (0 <= n <= len(p)) and any error encountered. Even if Read + * returns n < len(p), it may use all of p as scratch space during the call. + * If some data is available but not len(p) bytes, Read conventionally + * returns what is available instead of waiting for more. + * + * When Read encounters an error or end-of-file condition after + * successfully reading n > 0 bytes, it returns the number of + * bytes read. It may return the (non-nil) error from the same call + * or return the error (and n == 0) from a subsequent call. + * An instance of this general case is that a Reader returning + * a non-zero number of bytes at the end of the input stream may + * return either err == EOF or err == nil. The next Read should + * return 0, EOF. + * + * Callers should always process the n > 0 bytes returned before + * considering the error err. Doing so correctly handles I/O errors + * that happen after reading some bytes and also both of the + * allowed EOF behaviors. + * + * If len(p) == 0, Read should always return n == 0. It may return a + * non-nil error if some error condition is known, such as EOF. + * + * Implementations of Read are discouraged from returning a + * zero byte count with a nil error, except when len(p) == 0. + * Callers should treat a return of 0 and nil as indicating that + * nothing happened; in particular it does not indicate EOF. + * + * Implementations must not retain p. + */ + interface Reader { + [key:string]: any; + read(p: string|Array): number + } + /** + * ReadSeekCloser is the interface that groups the basic Read, Seek and Close + * methods. + */ + interface ReadSeekCloser { + [key:string]: any; + } +} + +/** + * Package bytes implements functions for the manipulation of byte slices. + * It is analogous to the facilities of the [strings] package. + */ +namespace bytes { + /** + * A Reader implements the io.Reader, io.ReaderAt, io.WriterTo, io.Seeker, + * io.ByteScanner, and io.RuneScanner interfaces by reading from + * a byte slice. + * Unlike a Buffer, a Reader is read-only and supports seeking. + * The zero value for Reader operates like a Reader of an empty slice. + */ + interface Reader { + } + interface Reader { + /** + * Len returns the number of bytes of the unread portion of the + * slice. + */ + len(): number + } + interface Reader { + /** + * Size returns the original length of the underlying byte slice. + * Size is the number of bytes available for reading via ReadAt. + * The result is unaffected by any method calls except Reset. + */ + size(): number + } + interface Reader { + /** + * Read implements the io.Reader interface. + */ + read(b: string|Array): number + } + interface Reader { + /** + * ReadAt implements the io.ReaderAt interface. + */ + readAt(b: string|Array, off: number): number + } + interface Reader { + /** + * ReadByte implements the io.ByteReader interface. + */ + readByte(): number + } + interface Reader { + /** + * UnreadByte complements ReadByte in implementing the io.ByteScanner interface. + */ + unreadByte(): void + } + interface Reader { + /** + * ReadRune implements the io.RuneReader interface. + */ + readRune(): [number, number] + } + interface Reader { + /** + * UnreadRune complements ReadRune in implementing the io.RuneScanner interface. + */ + unreadRune(): void + } + interface Reader { + /** + * Seek implements the io.Seeker interface. + */ + seek(offset: number, whence: number): number + } + interface Reader { + /** + * WriteTo implements the io.WriterTo interface. + */ + writeTo(w: io.Writer): number + } + interface Reader { + /** + * Reset resets the Reader to be reading from b. + */ + reset(b: string|Array): void + } +} + +/** + * Package syscall contains an interface to the low-level operating system + * primitives. The details vary depending on the underlying system, and + * by default, godoc will display the syscall documentation for the current + * system. If you want godoc to display syscall documentation for another + * system, set $GOOS and $GOARCH to the desired system. For example, if + * you want to view documentation for freebsd/arm on linux/amd64, set $GOOS + * to freebsd and $GOARCH to arm. + * The primary use of syscall is inside other packages that provide a more + * portable interface to the system, such as "os", "time" and "net". Use + * those packages rather than this one if you can. + * For details of the functions and data types in this package consult + * the manuals for the appropriate operating system. + * These calls return err == nil to indicate success; otherwise + * err is an operating system error describing the failure. + * On most systems, that error has type syscall.Errno. + * + * Deprecated: this package is locked down. Callers should use the + * corresponding package in the golang.org/x/sys repository instead. + * That is also where updates required by new systems or versions + * should be applied. See https://golang.org/s/go1.4-syscall for more + * information. + */ +namespace syscall { + interface SysProcAttr { + chroot: string // Chroot. + credential?: Credential // Credential. + /** + * Ptrace tells the child to call ptrace(PTRACE_TRACEME). + * Call runtime.LockOSThread before starting a process with this set, + * and don't call UnlockOSThread until done with PtraceSyscall calls. + */ + ptrace: boolean + setsid: boolean // Create session. + /** + * Setpgid sets the process group ID of the child to Pgid, + * or, if Pgid == 0, to the new child's process ID. + */ + setpgid: boolean + /** + * Setctty sets the controlling terminal of the child to + * file descriptor Ctty. Ctty must be a descriptor number + * in the child process: an index into ProcAttr.Files. + * This is only meaningful if Setsid is true. + */ + setctty: boolean + noctty: boolean // Detach fd 0 from controlling terminal + ctty: number // Controlling TTY fd + /** + * Foreground places the child process group in the foreground. + * This implies Setpgid. The Ctty field must be set to + * the descriptor of the controlling TTY. + * Unlike Setctty, in this case Ctty must be a descriptor + * number in the parent process. + */ + foreground: boolean + pgid: number // Child's process group ID if Setpgid. + /** + * Pdeathsig, if non-zero, is a signal that the kernel will send to + * the child process when the creating thread dies. Note that the signal + * is sent on thread termination, which may happen before process termination. + * There are more details at https://go.dev/issue/27505. + */ + pdeathsig: Signal + cloneflags: number // Flags for clone calls (Linux only) + unshareflags: number // Flags for unshare calls (Linux only) + uidMappings: Array // User ID mappings for user namespaces. + gidMappings: Array // Group ID mappings for user namespaces. + /** + * GidMappingsEnableSetgroups enabling setgroups syscall. + * If false, then setgroups syscall will be disabled for the child process. + * This parameter is no-op if GidMappings == nil. Otherwise for unprivileged + * users this should be set to false for mappings work. + */ + gidMappingsEnableSetgroups: boolean + ambientCaps: Array // Ambient capabilities (Linux only) + useCgroupFD: boolean // Whether to make use of the CgroupFD field. + cgroupFD: number // File descriptor of a cgroup to put the new process into. + } + // @ts-ignore + import errorspkg = errors + /** + * A RawConn is a raw network connection. + */ + interface RawConn { + [key:string]: any; + /** + * Control invokes f on the underlying connection's file * descriptor or handle. * The file descriptor fd is guaranteed to remain valid while * f executes but not after f returns. @@ -7690,70 +7848,13 @@ namespace context { } /** - * Package io provides basic interfaces to I/O primitives. - * Its primary job is to wrap existing implementations of such primitives, - * such as those in package os, into shared public interfaces that - * abstract the functionality, plus some other related primitives. - * - * Because these interfaces and primitives wrap lower-level operations with - * various implementations, unless otherwise informed clients should not - * assume they are safe for parallel execution. + * Package fs defines basic interfaces to a file system. + * A file system can be provided by the host operating system + * but also by other packages. */ -namespace io { +namespace fs { /** - * Reader is the interface that wraps the basic Read method. - * - * Read reads up to len(p) bytes into p. It returns the number of bytes - * read (0 <= n <= len(p)) and any error encountered. Even if Read - * returns n < len(p), it may use all of p as scratch space during the call. - * If some data is available but not len(p) bytes, Read conventionally - * returns what is available instead of waiting for more. - * - * When Read encounters an error or end-of-file condition after - * successfully reading n > 0 bytes, it returns the number of - * bytes read. It may return the (non-nil) error from the same call - * or return the error (and n == 0) from a subsequent call. - * An instance of this general case is that a Reader returning - * a non-zero number of bytes at the end of the input stream may - * return either err == EOF or err == nil. The next Read should - * return 0, EOF. - * - * Callers should always process the n > 0 bytes returned before - * considering the error err. Doing so correctly handles I/O errors - * that happen after reading some bytes and also both of the - * allowed EOF behaviors. - * - * If len(p) == 0, Read should always return n == 0. It may return a - * non-nil error if some error condition is known, such as EOF. - * - * Implementations of Read are discouraged from returning a - * zero byte count with a nil error, except when len(p) == 0. - * Callers should treat a return of 0 and nil as indicating that - * nothing happened; in particular it does not indicate EOF. - * - * Implementations must not retain p. - */ - interface Reader { - [key:string]: any; - read(p: string|Array): number - } - /** - * ReadSeekCloser is the interface that groups the basic Read, Seek and Close - * methods. - */ - interface ReadSeekCloser { - [key:string]: any; - } -} - -/** - * Package fs defines basic interfaces to a file system. - * A file system can be provided by the host operating system - * but also by other packages. - */ -namespace fs { - /** - * An FS provides access to a hierarchical file system. + * An FS provides access to a hierarchical file system. * * The FS interface is the minimum implementation required of the file system. * A file system may implement additional interfaces, @@ -7940,91 +8041,6 @@ namespace fs { interface WalkDirFunc {(path: string, d: DirEntry, err: Error): void } } -/** - * Package bytes implements functions for the manipulation of byte slices. - * It is analogous to the facilities of the [strings] package. - */ -namespace bytes { - /** - * A Reader implements the io.Reader, io.ReaderAt, io.WriterTo, io.Seeker, - * io.ByteScanner, and io.RuneScanner interfaces by reading from - * a byte slice. - * Unlike a Buffer, a Reader is read-only and supports seeking. - * The zero value for Reader operates like a Reader of an empty slice. - */ - interface Reader { - } - interface Reader { - /** - * Len returns the number of bytes of the unread portion of the - * slice. - */ - len(): number - } - interface Reader { - /** - * Size returns the original length of the underlying byte slice. - * Size is the number of bytes available for reading via ReadAt. - * The result is unaffected by any method calls except Reset. - */ - size(): number - } - interface Reader { - /** - * Read implements the io.Reader interface. - */ - read(b: string|Array): number - } - interface Reader { - /** - * ReadAt implements the io.ReaderAt interface. - */ - readAt(b: string|Array, off: number): number - } - interface Reader { - /** - * ReadByte implements the io.ByteReader interface. - */ - readByte(): number - } - interface Reader { - /** - * UnreadByte complements ReadByte in implementing the io.ByteScanner interface. - */ - unreadByte(): void - } - interface Reader { - /** - * ReadRune implements the io.RuneReader interface. - */ - readRune(): [number, number] - } - interface Reader { - /** - * UnreadRune complements ReadRune in implementing the io.RuneScanner interface. - */ - unreadRune(): void - } - interface Reader { - /** - * Seek implements the io.Seeker interface. - */ - seek(offset: number, whence: number): number - } - interface Reader { - /** - * WriteTo implements the io.WriterTo interface. - */ - writeTo(w: io.Writer): number - } - interface Reader { - /** - * Reset resets the Reader to be reading from b. - */ - reset(b: string|Array): void - } -} - /** * Package multipart implements MIME multipart parsing, as defined in RFC * 2046. @@ -8982,376 +8998,233 @@ namespace http { } /** - * Package exec runs external commands. It wraps os.StartProcess to make it - * easier to remap stdin and stdout, connect I/O with pipes, and do other - * adjustments. - * - * Unlike the "system" library call from C and other languages, the - * os/exec package intentionally does not invoke the system shell and - * does not expand any glob patterns or handle other expansions, - * pipelines, or redirections typically done by shells. The package - * behaves more like C's "exec" family of functions. To expand glob - * patterns, either call the shell directly, taking care to escape any - * dangerous input, or use the path/filepath package's Glob function. - * To expand environment variables, use package os's ExpandEnv. - * - * Note that the examples in this package assume a Unix system. - * They may not run on Windows, and they do not run in the Go Playground - * used by golang.org and godoc.org. - * - * # Executables in the current directory - * - * The functions Command and LookPath look for a program - * in the directories listed in the current path, following the - * conventions of the host operating system. - * Operating systems have for decades included the current - * directory in this search, sometimes implicitly and sometimes - * configured explicitly that way by default. - * Modern practice is that including the current directory - * is usually unexpected and often leads to security problems. + * Package blob provides an easy and portable way to interact with blobs + * within a storage location. Subpackages contain driver implementations of + * blob for supported services. * - * To avoid those security problems, as of Go 1.19, this package will not resolve a program - * using an implicit or explicit path entry relative to the current directory. - * That is, if you run exec.LookPath("go"), it will not successfully return - * ./go on Unix nor .\go.exe on Windows, no matter how the path is configured. - * Instead, if the usual path algorithms would result in that answer, - * these functions return an error err satisfying errors.Is(err, ErrDot). + * See https://gocloud.dev/howto/blob/ for a detailed how-to guide. * - * For example, consider these two program snippets: + * *blob.Bucket implements io/fs.FS and io/fs.SubFS, so it can be used with + * functions in that package. * - * ``` - * path, err := exec.LookPath("prog") - * if err != nil { - * log.Fatal(err) - * } - * use(path) - * ``` + * # Errors * - * and + * The errors returned from this package can be inspected in several ways: * - * ``` - * cmd := exec.Command("prog") - * if err := cmd.Run(); err != nil { - * log.Fatal(err) - * } - * ``` + * The Code function from gocloud.dev/gcerrors will return an error code, also + * defined in that package, when invoked on an error. * - * These will not find and run ./prog or .\prog.exe, - * no matter how the current path is configured. + * The Bucket.ErrorAs method can retrieve the driver error underlying the returned + * error. * - * Code that always wants to run a program from the current directory - * can be rewritten to say "./prog" instead of "prog". + * # OpenCensus Integration * - * Code that insists on including results from relative path entries - * can instead override the error using an errors.Is check: + * OpenCensus supports tracing and metric collection for multiple languages and + * backend providers. See https://opencensus.io. * + * This API collects OpenCensus traces and metrics for the following methods: * ``` - * path, err := exec.LookPath("prog") - * if errors.Is(err, exec.ErrDot) { - * err = nil - * } - * if err != nil { - * log.Fatal(err) - * } - * use(path) + * - Attributes + * - Copy + * - Delete + * - ListPage + * - NewRangeReader, from creation until the call to Close. (NewReader and ReadAll + * are included because they call NewRangeReader.) + * - NewWriter, from creation until the call to Close. * ``` * - * and + * All trace and metric names begin with the package import path. + * The traces add the method name. + * For example, "gocloud.dev/blob/Attributes". + * The metrics are "completed_calls", a count of completed method calls by driver, + * method and status (error code); and "latency", a distribution of method latency + * by driver and method. + * For example, "gocloud.dev/blob/latency". * + * It also collects the following metrics: * ``` - * cmd := exec.Command("prog") - * if errors.Is(cmd.Err, exec.ErrDot) { - * cmd.Err = nil - * } - * if err := cmd.Run(); err != nil { - * log.Fatal(err) - * } + * - gocloud.dev/blob/bytes_read: the total number of bytes read, by driver. + * - gocloud.dev/blob/bytes_written: the total number of bytes written, by driver. * ``` * - * Setting the environment variable GODEBUG=execerrdot=0 - * disables generation of ErrDot entirely, temporarily restoring the pre-Go 1.19 - * behavior for programs that are unable to apply more targeted fixes. - * A future version of Go may remove support for this variable. - * - * Before adding such overrides, make sure you understand the - * security implications of doing so. - * See https://go.dev/blog/path-security for more information. + * To enable trace collection in your application, see "Configure Exporter" at + * https://opencensus.io/quickstart/go/tracing. + * To enable metric collection in your application, see "Exporting stats" at + * https://opencensus.io/quickstart/go/metrics. */ -namespace exec { +namespace blob { /** - * Cmd represents an external command being prepared or run. - * - * A Cmd cannot be reused after calling its Run, Output or CombinedOutput - * methods. + * Reader reads bytes from a blob. + * It implements io.ReadSeekCloser, and must be closed after + * reads are finished. */ - interface Cmd { + interface Reader { + } + interface Reader { /** - * Path is the path of the command to run. - * - * This is the only field that must be set to a non-zero - * value. If Path is relative, it is evaluated relative - * to Dir. + * Read implements io.Reader (https://golang.org/pkg/io/#Reader). */ - path: string + read(p: string|Array): number + } + interface Reader { /** - * Args holds command line arguments, including the command as Args[0]. - * If the Args field is empty or nil, Run uses {Path}. - * - * In typical use, both Path and Args are set by calling Command. + * Seek implements io.Seeker (https://golang.org/pkg/io/#Seeker). */ - args: Array + seek(offset: number, whence: number): number + } + interface Reader { /** - * Env specifies the environment of the process. - * Each entry is of the form "key=value". - * If Env is nil, the new process uses the current process's - * environment. - * If Env contains duplicate environment keys, only the last - * value in the slice for each duplicate key is used. - * As a special case on Windows, SYSTEMROOT is always added if - * missing and not explicitly set to the empty string. + * Close implements io.Closer (https://golang.org/pkg/io/#Closer). */ - env: Array + close(): void + } + interface Reader { /** - * Dir specifies the working directory of the command. - * If Dir is the empty string, Run runs the command in the - * calling process's current directory. + * ContentType returns the MIME type of the blob. */ - dir: string + contentType(): string + } + interface Reader { /** - * Stdin specifies the process's standard input. - * - * If Stdin is nil, the process reads from the null device (os.DevNull). - * - * If Stdin is an *os.File, the process's standard input is connected - * directly to that file. - * - * Otherwise, during the execution of the command a separate - * goroutine reads from Stdin and delivers that data to the command - * over a pipe. In this case, Wait does not complete until the goroutine - * stops copying, either because it has reached the end of Stdin - * (EOF or a read error), or because writing to the pipe returned an error, - * or because a nonzero WaitDelay was set and expired. + * ModTime returns the time the blob was last modified. */ - stdin: io.Reader + modTime(): time.Time + } + interface Reader { /** - * Stdout and Stderr specify the process's standard output and error. - * - * If either is nil, Run connects the corresponding file descriptor - * to the null device (os.DevNull). - * - * If either is an *os.File, the corresponding output from the process - * is connected directly to that file. - * - * Otherwise, during the execution of the command a separate goroutine - * reads from the process over a pipe and delivers that data to the - * corresponding Writer. In this case, Wait does not complete until the - * goroutine reaches EOF or encounters an error or a nonzero WaitDelay - * expires. - * - * If Stdout and Stderr are the same writer, and have a type that can - * be compared with ==, at most one goroutine at a time will call Write. + * Size returns the size of the blob content in bytes. */ - stdout: io.Writer - stderr: io.Writer + size(): number + } + interface Reader { /** - * ExtraFiles specifies additional open files to be inherited by the - * new process. It does not include standard input, standard output, or - * standard error. If non-nil, entry i becomes file descriptor 3+i. + * As converts i to driver-specific types. + * See https://gocloud.dev/concepts/as/ for background information, the "As" + * examples in this package for examples, and the driver package + * documentation for the specific types supported for that driver. + */ + as(i: { + }): boolean + } + interface Reader { + /** + * WriteTo reads from r and writes to w until there's no more data or + * an error occurs. + * The return value is the number of bytes written to w. * - * ExtraFiles is not supported on Windows. + * It implements the io.WriterTo interface. */ - extraFiles: Array<(os.File | undefined)> + writeTo(w: io.Writer): number + } + /** + * Attributes contains attributes about a blob. + */ + interface Attributes { /** - * SysProcAttr holds optional, operating system-specific attributes. - * Run passes it to os.StartProcess as the os.ProcAttr's Sys field. + * CacheControl specifies caching attributes that services may use + * when serving the blob. + * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control */ - sysProcAttr?: syscall.SysProcAttr + cacheControl: string /** - * Process is the underlying process, once started. + * ContentDisposition specifies whether the blob content is expected to be + * displayed inline or as an attachment. + * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition */ - process?: os.Process + contentDisposition: string /** - * ProcessState contains information about an exited process. - * If the process was started successfully, Wait or Run will - * populate its ProcessState when the command completes. + * ContentEncoding specifies the encoding used for the blob's content, if any. + * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding */ - processState?: os.ProcessState - err: Error // LookPath error, if any. + contentEncoding: string /** - * If Cancel is non-nil, the command must have been created with - * CommandContext and Cancel will be called when the command's - * Context is done. By default, CommandContext sets Cancel to - * call the Kill method on the command's Process. - * - * Typically a custom Cancel will send a signal to the command's - * Process, but it may instead take other actions to initiate cancellation, - * such as closing a stdin or stdout pipe or sending a shutdown request on a - * network socket. - * - * If the command exits with a success status after Cancel is - * called, and Cancel does not return an error equivalent to - * os.ErrProcessDone, then Wait and similar methods will return a non-nil - * error: either an error wrapping the one returned by Cancel, - * or the error from the Context. - * (If the command exits with a non-success status, or Cancel - * returns an error that wraps os.ErrProcessDone, Wait and similar methods - * continue to return the command's usual exit status.) - * - * If Cancel is set to nil, nothing will happen immediately when the command's - * Context is done, but a nonzero WaitDelay will still take effect. That may - * be useful, for example, to work around deadlocks in commands that do not - * support shutdown signals but are expected to always finish quickly. - * - * Cancel will not be called if Start returns a non-nil error. + * ContentLanguage specifies the language used in the blob's content, if any. + * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language */ - cancel: () => void + contentLanguage: string /** - * If WaitDelay is non-zero, it bounds the time spent waiting on two sources - * of unexpected delay in Wait: a child process that fails to exit after the - * associated Context is canceled, and a child process that exits but leaves - * its I/O pipes unclosed. - * - * The WaitDelay timer starts when either the associated Context is done or a - * call to Wait observes that the child process has exited, whichever occurs - * first. When the delay has elapsed, the command shuts down the child process - * and/or its I/O pipes. - * - * If the child process has failed to exit — perhaps because it ignored or - * failed to receive a shutdown signal from a Cancel function, or because no - * Cancel function was set — then it will be terminated using os.Process.Kill. - * - * Then, if the I/O pipes communicating with the child process are still open, - * those pipes are closed in order to unblock any goroutines currently blocked - * on Read or Write calls. - * - * If pipes are closed due to WaitDelay, no Cancel call has occurred, - * and the command has otherwise exited with a successful status, Wait and - * similar methods will return ErrWaitDelay instead of nil. - * - * If WaitDelay is zero (the default), I/O pipes will be read until EOF, - * which might not occur until orphaned subprocesses of the command have - * also closed their descriptors for the pipes. + * ContentType is the MIME type of the blob. It will not be empty. + * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type */ - waitDelay: time.Duration - } - interface Cmd { + contentType: string /** - * String returns a human-readable description of c. - * It is intended only for debugging. - * In particular, it is not suitable for use as input to a shell. - * The output of String may vary across Go releases. + * Metadata holds key/value pairs associated with the blob. + * Keys are guaranteed to be in lowercase, even if the backend service + * has case-sensitive keys (although note that Metadata written via + * this package will always be lowercased). If there are duplicate + * case-insensitive keys (e.g., "foo" and "FOO"), only one value + * will be kept, and it is undefined which one. */ - string(): string - } - interface Cmd { + metadata: _TygojaDict /** - * Run starts the specified command and waits for it to complete. - * - * The returned error is nil if the command runs, has no problems - * copying stdin, stdout, and stderr, and exits with a zero exit - * status. - * - * If the command starts but does not complete successfully, the error is of - * type *ExitError. Other error types may be returned for other situations. - * - * If the calling goroutine has locked the operating system thread - * with runtime.LockOSThread and modified any inheritable OS-level - * thread state (for example, Linux or Plan 9 name spaces), the new - * process will inherit the caller's thread state. + * CreateTime is the time the blob was created, if available. If not available, + * CreateTime will be the zero time. */ - run(): void - } - interface Cmd { + createTime: time.Time /** - * Start starts the specified command but does not wait for it to complete. - * - * If Start returns successfully, the c.Process field will be set. - * - * After a successful call to Start the Wait method must be called in - * order to release associated system resources. + * ModTime is the time the blob was last modified. */ - start(): void - } - interface Cmd { + modTime: time.Time /** - * Wait waits for the command to exit and waits for any copying to - * stdin or copying from stdout or stderr to complete. - * - * The command must have been started by Start. - * - * The returned error is nil if the command runs, has no problems - * copying stdin, stdout, and stderr, and exits with a zero exit - * status. - * - * If the command fails to run or doesn't complete successfully, the - * error is of type *ExitError. Other error types may be - * returned for I/O problems. - * - * If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits - * for the respective I/O loop copying to or from the process to complete. - * - * Wait releases any resources associated with the Cmd. + * Size is the size of the blob's content in bytes. */ - wait(): void - } - interface Cmd { + size: number /** - * Output runs the command and returns its standard output. - * Any returned error will usually be of type *ExitError. - * If c.Stderr was nil, Output populates ExitError.Stderr. + * MD5 is an MD5 hash of the blob contents or nil if not available. */ - output(): string|Array - } - interface Cmd { + md5: string|Array /** - * CombinedOutput runs the command and returns its combined standard - * output and standard error. + * ETag for the blob; see https://en.wikipedia.org/wiki/HTTP_ETag. */ - combinedOutput(): string|Array + eTag: string } - interface Cmd { + interface Attributes { /** - * StdinPipe returns a pipe that will be connected to the command's - * standard input when the command starts. - * The pipe will be closed automatically after Wait sees the command exit. - * A caller need only call Close to force the pipe to close sooner. - * For example, if the command being run will not exit until standard input - * is closed, the caller must close the pipe. + * As converts i to driver-specific types. + * See https://gocloud.dev/concepts/as/ for background information, the "As" + * examples in this package for examples, and the driver package + * documentation for the specific types supported for that driver. */ - stdinPipe(): io.WriteCloser + as(i: { + }): boolean } - interface Cmd { + /** + * ListObject represents a single blob returned from List. + */ + interface ListObject { /** - * StdoutPipe returns a pipe that will be connected to the command's - * standard output when the command starts. - * - * Wait will close the pipe after seeing the command exit, so most callers - * need not close the pipe themselves. It is thus incorrect to call Wait - * before all reads from the pipe have completed. - * For the same reason, it is incorrect to call Run when using StdoutPipe. - * See the example for idiomatic usage. + * Key is the key for this blob. */ - stdoutPipe(): io.ReadCloser - } - interface Cmd { + key: string /** - * StderrPipe returns a pipe that will be connected to the command's - * standard error when the command starts. - * - * Wait will close the pipe after seeing the command exit, so most callers - * need not close the pipe themselves. It is thus incorrect to call Wait - * before all reads from the pipe have completed. - * For the same reason, it is incorrect to use Run when using StderrPipe. - * See the StdoutPipe example for idiomatic usage. + * ModTime is the time the blob was last modified. */ - stderrPipe(): io.ReadCloser + modTime: time.Time + /** + * Size is the size of the blob's content in bytes. + */ + size: number + /** + * MD5 is an MD5 hash of the blob contents or nil if not available. + */ + md5: string|Array + /** + * IsDir indicates that this result represents a "directory" in the + * hierarchical namespace, ending in ListOptions.Delimiter. Key can be + * passed as ListOptions.Prefix to list items in the "directory". + * Fields other than Key and IsDir will not be set if IsDir is true. + */ + isDir: boolean } - interface Cmd { + interface ListObject { /** - * Environ returns a copy of the environment in which the command would be run - * as it is currently configured. + * As converts i to driver-specific types. + * See https://gocloud.dev/concepts/as/ for background information, the "As" + * examples in this package for examples, and the driver package + * documentation for the specific types supported for that driver. */ - environ(): Array + as(i: { + }): boolean } } @@ -9413,5079 +9286,5226 @@ namespace jwt { } /** - * Package blob provides an easy and portable way to interact with blobs - * within a storage location. Subpackages contain driver implementations of - * blob for supported services. - * - * See https://gocloud.dev/howto/blob/ for a detailed how-to guide. - * - * *blob.Bucket implements io/fs.FS and io/fs.SubFS, so it can be used with - * functions in that package. - * - * # Errors - * - * The errors returned from this package can be inspected in several ways: - * - * The Code function from gocloud.dev/gcerrors will return an error code, also - * defined in that package, when invoked on an error. - * - * The Bucket.ErrorAs method can retrieve the driver error underlying the returned - * error. - * - * # OpenCensus Integration - * - * OpenCensus supports tracing and metric collection for multiple languages and - * backend providers. See https://opencensus.io. - * - * This API collects OpenCensus traces and metrics for the following methods: - * ``` - * - Attributes - * - Copy - * - Delete - * - ListPage - * - NewRangeReader, from creation until the call to Close. (NewReader and ReadAll - * are included because they call NewRangeReader.) - * - NewWriter, from creation until the call to Close. - * ``` - * - * All trace and metric names begin with the package import path. - * The traces add the method name. - * For example, "gocloud.dev/blob/Attributes". - * The metrics are "completed_calls", a count of completed method calls by driver, - * method and status (error code); and "latency", a distribution of method latency - * by driver and method. - * For example, "gocloud.dev/blob/latency". - * - * It also collects the following metrics: - * ``` - * - gocloud.dev/blob/bytes_read: the total number of bytes read, by driver. - * - gocloud.dev/blob/bytes_written: the total number of bytes written, by driver. - * ``` - * - * To enable trace collection in your application, see "Configure Exporter" at - * https://opencensus.io/quickstart/go/tracing. - * To enable metric collection in your application, see "Exporting stats" at - * https://opencensus.io/quickstart/go/metrics. + * Package types implements some commonly used db serializable types + * like datetime, json, etc. */ -namespace blob { +namespace types { /** - * Reader reads bytes from a blob. - * It implements io.ReadSeekCloser, and must be closed after - * reads are finished. + * JsonArray defines a slice that is safe for json and db read/write. */ - interface Reader { - } - interface Reader { + interface JsonArray extends Array{} + interface JsonArray { /** - * Read implements io.Reader (https://golang.org/pkg/io/#Reader). + * MarshalJSON implements the [json.Marshaler] interface. */ - read(p: string|Array): number + marshalJSON(): string|Array } - interface Reader { + interface JsonArray { /** - * Seek implements io.Seeker (https://golang.org/pkg/io/#Seeker). + * Value implements the [driver.Valuer] interface. */ - seek(offset: number, whence: number): number + value(): any } - interface Reader { + interface JsonArray { /** - * Close implements io.Closer (https://golang.org/pkg/io/#Closer). + * Scan implements [sql.Scanner] interface to scan the provided value + * into the current JsonArray[T] instance. */ - close(): void + scan(value: any): void } - interface Reader { + /** + * JsonMap defines a map that is safe for json and db read/write. + */ + interface JsonMap extends _TygojaDict{} + interface JsonMap { /** - * ContentType returns the MIME type of the blob. + * MarshalJSON implements the [json.Marshaler] interface. */ - contentType(): string + marshalJSON(): string|Array } - interface Reader { + interface JsonMap { /** - * ModTime returns the time the blob was last modified. + * Get retrieves a single value from the current JsonMap. + * + * This helper was added primarily to assist the goja integration since custom map types + * don't have direct access to the map keys (https://pkg.go.dev/github.com/dop251/goja#hdr-Maps_with_methods). */ - modTime(): time.Time + get(key: string): any } - interface Reader { + interface JsonMap { /** - * Size returns the size of the blob content in bytes. + * Set sets a single value in the current JsonMap. + * + * This helper was added primarily to assist the goja integration since custom map types + * don't have direct access to the map keys (https://pkg.go.dev/github.com/dop251/goja#hdr-Maps_with_methods). */ - size(): number + set(key: string, value: any): void } - interface Reader { + interface JsonMap { /** - * As converts i to driver-specific types. - * See https://gocloud.dev/concepts/as/ for background information, the "As" - * examples in this package for examples, and the driver package - * documentation for the specific types supported for that driver. + * Value implements the [driver.Valuer] interface. */ - as(i: { - }): boolean + value(): any } - interface Reader { + interface JsonMap { /** - * WriteTo reads from r and writes to w until there's no more data or - * an error occurs. - * The return value is the number of bytes written to w. - * - * It implements the io.WriterTo interface. + * Scan implements [sql.Scanner] interface to scan the provided value + * into the current `JsonMap` instance. */ - writeTo(w: io.Writer): number + scan(value: any): void } +} + +namespace auth { /** - * Attributes contains attributes about a blob. + * AuthUser defines a standardized oauth2 user data structure. */ - interface Attributes { + interface AuthUser { + id: string + name: string + username: string + email: string + avatarUrl: string + accessToken: string + refreshToken: string + expiry: types.DateTime + rawUser: _TygojaDict + } + /** + * Provider defines a common interface for an OAuth2 client. + */ + interface Provider { + [key:string]: any; /** - * CacheControl specifies caching attributes that services may use - * when serving the blob. - * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control + * Scopes returns the context associated with the provider (if any). */ - cacheControl: string + context(): context.Context /** - * ContentDisposition specifies whether the blob content is expected to be - * displayed inline or as an attachment. - * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition + * SetContext assigns the specified context to the current provider. */ - contentDisposition: string + setContext(ctx: context.Context): void /** - * ContentEncoding specifies the encoding used for the blob's content, if any. - * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding + * PKCE indicates whether the provider can use the PKCE flow. */ - contentEncoding: string + pkce(): boolean /** - * ContentLanguage specifies the language used in the blob's content, if any. - * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language + * SetPKCE toggles the state whether the provider can use the PKCE flow or not. */ - contentLanguage: string + setPKCE(enable: boolean): void /** - * ContentType is the MIME type of the blob. It will not be empty. - * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type + * DisplayName usually returns provider name as it is officially written + * and it could be used directly in the UI. */ - contentType: string + displayName(): string /** - * Metadata holds key/value pairs associated with the blob. - * Keys are guaranteed to be in lowercase, even if the backend service - * has case-sensitive keys (although note that Metadata written via - * this package will always be lowercased). If there are duplicate - * case-insensitive keys (e.g., "foo" and "FOO"), only one value - * will be kept, and it is undefined which one. + * SetDisplayName sets the provider's display name. */ - metadata: _TygojaDict + setDisplayName(displayName: string): void /** - * CreateTime is the time the blob was created, if available. If not available, - * CreateTime will be the zero time. - */ - createTime: time.Time - /** - * ModTime is the time the blob was last modified. + * Scopes returns the provider access permissions that will be requested. */ - modTime: time.Time + scopes(): Array /** - * Size is the size of the blob's content in bytes. + * SetScopes sets the provider access permissions that will be requested later. */ - size: number + setScopes(scopes: Array): void /** - * MD5 is an MD5 hash of the blob contents or nil if not available. + * ClientId returns the provider client's app ID. */ - md5: string|Array + clientId(): string /** - * ETag for the blob; see https://en.wikipedia.org/wiki/HTTP_ETag. + * SetClientId sets the provider client's ID. */ - eTag: string - } - interface Attributes { + setClientId(clientId: string): void /** - * As converts i to driver-specific types. - * See https://gocloud.dev/concepts/as/ for background information, the "As" - * examples in this package for examples, and the driver package - * documentation for the specific types supported for that driver. + * ClientSecret returns the provider client's app secret. */ - as(i: { - }): boolean - } - /** - * ListObject represents a single blob returned from List. - */ - interface ListObject { + clientSecret(): string /** - * Key is the key for this blob. + * SetClientSecret sets the provider client's app secret. */ - key: string + setClientSecret(secret: string): void /** - * ModTime is the time the blob was last modified. + * RedirectUrl returns the end address to redirect the user + * going through the OAuth flow. */ - modTime: time.Time + redirectUrl(): string /** - * Size is the size of the blob's content in bytes. + * SetRedirectUrl sets the provider's RedirectUrl. */ - size: number + setRedirectUrl(url: string): void /** - * MD5 is an MD5 hash of the blob contents or nil if not available. + * AuthUrl returns the provider's authorization service url. */ - md5: string|Array + authUrl(): string /** - * IsDir indicates that this result represents a "directory" in the - * hierarchical namespace, ending in ListOptions.Delimiter. Key can be - * passed as ListOptions.Prefix to list items in the "directory". - * Fields other than Key and IsDir will not be set if IsDir is true. + * SetAuthUrl sets the provider's AuthUrl. */ - isDir: boolean - } - interface ListObject { + setAuthUrl(url: string): void /** - * As converts i to driver-specific types. - * See https://gocloud.dev/concepts/as/ for background information, the "As" - * examples in this package for examples, and the driver package - * documentation for the specific types supported for that driver. + * TokenUrl returns the provider's token exchange service url. */ - as(i: { - }): boolean - } -} - -/** - * Package types implements some commonly used db serializable types - * like datetime, json, etc. - */ -namespace types { - /** - * JsonArray defines a slice that is safe for json and db read/write. - */ - interface JsonArray extends Array{} - interface JsonArray { + tokenUrl(): string /** - * MarshalJSON implements the [json.Marshaler] interface. + * SetTokenUrl sets the provider's TokenUrl. */ - marshalJSON(): string|Array - } - interface JsonArray { + setTokenUrl(url: string): void /** - * Value implements the [driver.Valuer] interface. + * UserApiUrl returns the provider's user info api url. */ - value(): any - } - interface JsonArray { + userApiUrl(): string /** - * Scan implements [sql.Scanner] interface to scan the provided value - * into the current JsonArray[T] instance. + * SetUserApiUrl sets the provider's UserApiUrl. */ - scan(value: any): void - } - /** - * JsonMap defines a map that is safe for json and db read/write. - */ - interface JsonMap extends _TygojaDict{} - interface JsonMap { + setUserApiUrl(url: string): void /** - * MarshalJSON implements the [json.Marshaler] interface. + * Client returns an http client using the provided token. */ - marshalJSON(): string|Array - } - interface JsonMap { + client(token: oauth2.Token): (any) /** - * Get retrieves a single value from the current JsonMap. - * - * This helper was added primarily to assist the goja integration since custom map types - * don't have direct access to the map keys (https://pkg.go.dev/github.com/dop251/goja#hdr-Maps_with_methods). + * BuildAuthUrl returns a URL to the provider's consent page + * that asks for permissions for the required scopes explicitly. */ - get(key: string): any - } - interface JsonMap { + buildAuthUrl(state: string, ...opts: oauth2.AuthCodeOption[]): string /** - * Set sets a single value in the current JsonMap. - * - * This helper was added primarily to assist the goja integration since custom map types - * don't have direct access to the map keys (https://pkg.go.dev/github.com/dop251/goja#hdr-Maps_with_methods). + * FetchToken converts an authorization code to token. */ - set(key: string, value: any): void - } - interface JsonMap { + fetchToken(code: string, ...opts: oauth2.AuthCodeOption[]): (oauth2.Token) /** - * Value implements the [driver.Valuer] interface. + * FetchRawUserData requests and marshalizes into `result` the + * the OAuth user api response. */ - value(): any - } - interface JsonMap { + fetchRawUserData(token: oauth2.Token): string|Array /** - * Scan implements [sql.Scanner] interface to scan the provided value - * into the current `JsonMap` instance. + * FetchAuthUser is similar to FetchRawUserData, but normalizes and + * marshalizes the user api response into a standardized AuthUser struct. */ - scan(value: any): void + fetchAuthUser(token: oauth2.Token): (AuthUser) } } /** - * Package schema implements custom Schema and SchemaField datatypes - * for handling the Collection schema definitions. + * Package echo implements high performance, minimalist Go web framework. + * + * Example: + * + * ``` + * package main + * + * import ( + * "github.com/labstack/echo/v5" + * "github.com/labstack/echo/v5/middleware" + * "log" + * "net/http" + * ) + * + * // Handler + * func hello(c echo.Context) error { + * return c.String(http.StatusOK, "Hello, World!") + * } + * + * func main() { + * // Echo instance + * e := echo.New() + * + * // Middleware + * e.Use(middleware.Logger()) + * e.Use(middleware.Recover()) + * + * // Routes + * e.GET("/", hello) + * + * // Start server + * if err := e.Start(":8080"); err != http.ErrServerClosed { + * log.Fatal(err) + * } + * } + * ``` + * + * Learn more at https://echo.labstack.com */ -namespace schema { - // @ts-ignore - import validation = ozzo_validation +namespace echo { /** - * Schema defines a dynamic db schema as a slice of `SchemaField`s. + * Context represents the context of the current HTTP request. It holds request and + * response objects, path, path parameters, data and registered handler. */ - interface Schema { - } - interface Schema { + interface Context { + [key:string]: any; /** - * Fields returns the registered schema fields. + * Request returns `*http.Request`. */ - fields(): Array<(SchemaField | undefined)> - } - interface Schema { + request(): (http.Request) /** - * InitFieldsOptions calls `InitOptions()` for all schema fields. + * SetRequest sets `*http.Request`. */ - initFieldsOptions(): void - } - interface Schema { + setRequest(r: http.Request): void /** - * Clone creates a deep clone of the current schema. + * SetResponse sets `*Response`. */ - clone(): (Schema) - } - interface Schema { + setResponse(r: Response): void /** - * AsMap returns a map with all registered schema field. - * The returned map is indexed with each field name. + * Response returns `*Response`. */ - asMap(): _TygojaDict - } - interface Schema { + response(): (Response) /** - * GetFieldById returns a single field by its id. + * IsTLS returns true if HTTP connection is TLS otherwise false. */ - getFieldById(id: string): (SchemaField) - } - interface Schema { + isTLS(): boolean /** - * GetFieldByName returns a single field by its name. + * IsWebSocket returns true if HTTP connection is WebSocket otherwise false. */ - getFieldByName(name: string): (SchemaField) - } - interface Schema { + isWebSocket(): boolean /** - * RemoveField removes a single schema field by its id. - * - * This method does nothing if field with `id` doesn't exist. + * Scheme returns the HTTP protocol scheme, `http` or `https`. */ - removeField(id: string): void - } - interface Schema { + scheme(): string /** - * AddField registers the provided newField to the current schema. - * - * If field with `newField.Id` already exist, the existing field is - * replaced with the new one. - * - * Otherwise the new field is appended to the other schema fields. + * RealIP returns the client's network address based on `X-Forwarded-For` + * or `X-Real-IP` request header. + * The behavior can be configured using `Echo#IPExtractor`. */ - addField(newField: SchemaField): void - } - interface Schema { + realIP(): string /** - * Validate makes Schema validatable by implementing [validation.Validatable] interface. - * - * Internally calls each individual field's validator and additionally - * checks for invalid renamed fields and field name duplications. + * RouteInfo returns current request route information. Method, Path, Name and params if they exist for matched route. + * In case of 404 (route not found) and 405 (method not allowed) RouteInfo returns generic struct for these cases. */ - validate(): void - } - interface Schema { + routeInfo(): RouteInfo /** - * MarshalJSON implements the [json.Marshaler] interface. + * Path returns the registered path for the handler. */ - marshalJSON(): string|Array - } - interface Schema { + path(): string /** - * UnmarshalJSON implements the [json.Unmarshaler] interface. - * - * On success, all schema field options are auto initialized. + * PathParam returns path parameter by name. */ - unmarshalJSON(data: string|Array): void - } - interface Schema { + pathParam(name: string): string /** - * Value implements the [driver.Valuer] interface. + * PathParamDefault returns the path parameter or default value for the provided name. + * + * Notes for DefaultRouter implementation: + * Path parameter could be empty for cases like that: + * * route `/release-:version/bin` and request URL is `/release-/bin` + * * route `/api/:version/image.jpg` and request URL is `/api//image.jpg` + * but not when path parameter is last part of route path + * * route `/download/file.:ext` will not match request `/download/file.` */ - value(): any - } - interface Schema { + pathParamDefault(name: string, defaultValue: string): string /** - * Scan implements [sql.Scanner] interface to scan the provided value - * into the current Schema instance. + * PathParams returns path parameter values. */ - scan(value: any): void - } -} - -/** - * Package sql provides a generic interface around SQL (or SQL-like) - * databases. - * - * The sql package must be used in conjunction with a database driver. - * See https://golang.org/s/sqldrivers for a list of drivers. - * - * Drivers that do not support context cancellation will not return until - * after the query is completed. - * - * For usage examples, see the wiki page at - * https://golang.org/s/sqlwiki. - */ -namespace sql { - /** - * TxOptions holds the transaction options to be used in DB.BeginTx. - */ - interface TxOptions { + pathParams(): PathParams /** - * Isolation is the transaction isolation level. - * If zero, the driver or database's default level is used. + * SetPathParams sets path parameters for current request. */ - isolation: IsolationLevel - readOnly: boolean - } - /** - * DB is a database handle representing a pool of zero or more - * underlying connections. It's safe for concurrent use by multiple - * goroutines. - * - * The sql package creates and frees connections automatically; it - * also maintains a free pool of idle connections. If the database has - * a concept of per-connection state, such state can be reliably observed - * within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the - * returned Tx is bound to a single connection. Once Commit or - * Rollback is called on the transaction, that transaction's - * connection is returned to DB's idle connection pool. The pool size - * can be controlled with SetMaxIdleConns. - */ - interface DB { - } - interface DB { + setPathParams(params: PathParams): void /** - * PingContext verifies a connection to the database is still alive, - * establishing a connection if necessary. + * QueryParam returns the query param for the provided name. */ - pingContext(ctx: context.Context): void - } - interface DB { + queryParam(name: string): string /** - * Ping verifies a connection to the database is still alive, - * establishing a connection if necessary. - * - * Ping uses context.Background internally; to specify the context, use - * PingContext. + * QueryParamDefault returns the query param or default value for the provided name. */ - ping(): void - } - interface DB { + queryParamDefault(name: string): string /** - * Close closes the database and prevents new queries from starting. - * Close then waits for all queries that have started processing on the server - * to finish. - * - * It is rare to Close a DB, as the DB handle is meant to be - * long-lived and shared between many goroutines. + * QueryParams returns the query parameters as `url.Values`. */ - close(): void - } - interface DB { + queryParams(): url.Values /** - * SetMaxIdleConns sets the maximum number of connections in the idle - * connection pool. - * - * If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, - * then the new MaxIdleConns will be reduced to match the MaxOpenConns limit. - * - * If n <= 0, no idle connections are retained. - * - * The default max idle connections is currently 2. This may change in - * a future release. + * QueryString returns the URL query string. */ - setMaxIdleConns(n: number): void - } - interface DB { + queryString(): string /** - * SetMaxOpenConns sets the maximum number of open connections to the database. - * - * If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than - * MaxIdleConns, then MaxIdleConns will be reduced to match the new - * MaxOpenConns limit. - * - * If n <= 0, then there is no limit on the number of open connections. - * The default is 0 (unlimited). + * FormValue returns the form field value for the provided name. */ - setMaxOpenConns(n: number): void - } - interface DB { + formValue(name: string): string /** - * SetConnMaxLifetime sets the maximum amount of time a connection may be reused. - * - * Expired connections may be closed lazily before reuse. - * - * If d <= 0, connections are not closed due to a connection's age. + * FormValueDefault returns the form field value or default value for the provided name. */ - setConnMaxLifetime(d: time.Duration): void - } - interface DB { + formValueDefault(name: string): string /** - * SetConnMaxIdleTime sets the maximum amount of time a connection may be idle. - * - * Expired connections may be closed lazily before reuse. - * - * If d <= 0, connections are not closed due to a connection's idle time. + * FormValues returns the form field values as `url.Values`. */ - setConnMaxIdleTime(d: time.Duration): void - } - interface DB { + formValues(): url.Values /** - * Stats returns database statistics. + * FormFile returns the multipart form file for the provided name. */ - stats(): DBStats - } - interface DB { + formFile(name: string): (multipart.FileHeader) /** - * PrepareContext creates a prepared statement for later queries or executions. - * Multiple queries or executions may be run concurrently from the - * returned statement. - * The caller must call the statement's Close method - * when the statement is no longer needed. - * - * The provided context is used for the preparation of the statement, not for the - * execution of the statement. + * MultipartForm returns the multipart form. */ - prepareContext(ctx: context.Context, query: string): (Stmt) - } - interface DB { + multipartForm(): (multipart.Form) /** - * Prepare creates a prepared statement for later queries or executions. - * Multiple queries or executions may be run concurrently from the - * returned statement. - * The caller must call the statement's Close method - * when the statement is no longer needed. - * - * Prepare uses context.Background internally; to specify the context, use - * PrepareContext. + * Cookie returns the named cookie provided in the request. */ - prepare(query: string): (Stmt) - } - interface DB { + cookie(name: string): (http.Cookie) /** - * ExecContext executes a query without returning any rows. - * The args are for any placeholder parameters in the query. + * SetCookie adds a `Set-Cookie` header in HTTP response. */ - execContext(ctx: context.Context, query: string, ...args: any[]): Result - } - interface DB { + setCookie(cookie: http.Cookie): void /** - * Exec executes a query without returning any rows. - * The args are for any placeholder parameters in the query. - * - * Exec uses context.Background internally; to specify the context, use - * ExecContext. + * Cookies returns the HTTP cookies sent with the request. */ - exec(query: string, ...args: any[]): Result - } - interface DB { + cookies(): Array<(http.Cookie | undefined)> /** - * QueryContext executes a query that returns rows, typically a SELECT. - * The args are for any placeholder parameters in the query. + * Get retrieves data from the context. */ - queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) + get(key: string): { } - interface DB { /** - * Query executes a query that returns rows, typically a SELECT. - * The args are for any placeholder parameters in the query. - * - * Query uses context.Background internally; to specify the context, use - * QueryContext. + * Set saves data in the context. */ - query(query: string, ...args: any[]): (Rows) - } - interface DB { + set(key: string, val: { + }): void /** - * QueryRowContext executes a query that is expected to return at most one row. - * QueryRowContext always returns a non-nil value. Errors are deferred until - * Row's Scan method is called. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. + * Bind binds path params, query params and the request body into provided type `i`. The default binder + * binds body based on Content-Type header. */ - queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) - } - interface DB { + bind(i: { + }): void /** - * QueryRow executes a query that is expected to return at most one row. - * QueryRow always returns a non-nil value. Errors are deferred until - * Row's Scan method is called. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. - * - * QueryRow uses context.Background internally; to specify the context, use - * QueryRowContext. + * Validate validates provided `i`. It is usually called after `Context#Bind()`. + * Validator must be registered using `Echo#Validator`. */ - queryRow(query: string, ...args: any[]): (Row) - } - interface DB { + validate(i: { + }): void /** - * BeginTx starts a transaction. - * - * The provided context is used until the transaction is committed or rolled back. - * If the context is canceled, the sql package will roll back - * the transaction. Tx.Commit will return an error if the context provided to - * BeginTx is canceled. - * - * The provided TxOptions is optional and may be nil if defaults should be used. - * If a non-default isolation level is used that the driver doesn't support, - * an error will be returned. + * Render renders a template with data and sends a text/html response with status + * code. Renderer must be registered using `Echo.Renderer`. */ - beginTx(ctx: context.Context, opts: TxOptions): (Tx) - } - interface DB { + render(code: number, name: string, data: { + }): void /** - * Begin starts a transaction. The default isolation level is dependent on - * the driver. - * - * Begin uses context.Background internally; to specify the context, use - * BeginTx. + * HTML sends an HTTP response with status code. */ - begin(): (Tx) - } - interface DB { + html(code: number, html: string): void /** - * Driver returns the database's underlying driver. + * HTMLBlob sends an HTTP blob response with status code. */ - driver(): any - } - interface DB { + htmlBlob(code: number, b: string|Array): void /** - * Conn returns a single connection by either opening a new connection - * or returning an existing connection from the connection pool. Conn will - * block until either a connection is returned or ctx is canceled. - * Queries run on the same Conn will be run in the same database session. - * - * Every Conn must be returned to the database pool after use by - * calling Conn.Close. + * String sends a string response with status code. */ - conn(ctx: context.Context): (Conn) - } - /** - * Tx is an in-progress database transaction. - * - * A transaction must end with a call to Commit or Rollback. - * - * After a call to Commit or Rollback, all operations on the - * transaction fail with ErrTxDone. - * - * The statements prepared for a transaction by calling - * the transaction's Prepare or Stmt methods are closed - * by the call to Commit or Rollback. - */ - interface Tx { - } - interface Tx { + string(code: number, s: string): void /** - * Commit commits the transaction. + * JSON sends a JSON response with status code. */ - commit(): void - } - interface Tx { + json(code: number, i: { + }): void /** - * Rollback aborts the transaction. + * JSONPretty sends a pretty-print JSON with status code. */ - rollback(): void - } - interface Tx { + jsonPretty(code: number, i: { + }, indent: string): void /** - * PrepareContext creates a prepared statement for use within a transaction. - * - * The returned statement operates within the transaction and will be closed - * when the transaction has been committed or rolled back. - * - * To use an existing prepared statement on this transaction, see Tx.Stmt. - * - * The provided context will be used for the preparation of the context, not - * for the execution of the returned statement. The returned statement - * will run in the transaction context. + * JSONBlob sends a JSON blob response with status code. */ - prepareContext(ctx: context.Context, query: string): (Stmt) - } - interface Tx { + jsonBlob(code: number, b: string|Array): void /** - * Prepare creates a prepared statement for use within a transaction. - * - * The returned statement operates within the transaction and will be closed - * when the transaction has been committed or rolled back. - * - * To use an existing prepared statement on this transaction, see Tx.Stmt. - * - * Prepare uses context.Background internally; to specify the context, use - * PrepareContext. + * JSONP sends a JSONP response with status code. It uses `callback` to construct + * the JSONP payload. */ - prepare(query: string): (Stmt) - } - interface Tx { + jsonp(code: number, callback: string, i: { + }): void /** - * StmtContext returns a transaction-specific prepared statement from - * an existing statement. - * - * Example: - * - * ``` - * updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") - * ... - * tx, err := db.Begin() - * ... - * res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203) - * ``` - * - * The provided context is used for the preparation of the statement, not for the - * execution of the statement. - * - * The returned statement operates within the transaction and will be closed - * when the transaction has been committed or rolled back. + * JSONPBlob sends a JSONP blob response with status code. It uses `callback` + * to construct the JSONP payload. */ - stmtContext(ctx: context.Context, stmt: Stmt): (Stmt) - } - interface Tx { + jsonpBlob(code: number, callback: string, b: string|Array): void /** - * Stmt returns a transaction-specific prepared statement from - * an existing statement. - * - * Example: - * - * ``` - * updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") - * ... - * tx, err := db.Begin() - * ... - * res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203) - * ``` - * - * The returned statement operates within the transaction and will be closed - * when the transaction has been committed or rolled back. - * - * Stmt uses context.Background internally; to specify the context, use - * StmtContext. + * XML sends an XML response with status code. */ - stmt(stmt: Stmt): (Stmt) - } - interface Tx { + xml(code: number, i: { + }): void /** - * ExecContext executes a query that doesn't return rows. - * For example: an INSERT and UPDATE. + * XMLPretty sends a pretty-print XML with status code. */ - execContext(ctx: context.Context, query: string, ...args: any[]): Result - } - interface Tx { + xmlPretty(code: number, i: { + }, indent: string): void /** - * Exec executes a query that doesn't return rows. - * For example: an INSERT and UPDATE. - * - * Exec uses context.Background internally; to specify the context, use - * ExecContext. + * XMLBlob sends an XML blob response with status code. */ - exec(query: string, ...args: any[]): Result - } - interface Tx { + xmlBlob(code: number, b: string|Array): void /** - * QueryContext executes a query that returns rows, typically a SELECT. + * Blob sends a blob response with status code and content type. */ - queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) - } - interface Tx { + blob(code: number, contentType: string, b: string|Array): void /** - * Query executes a query that returns rows, typically a SELECT. - * - * Query uses context.Background internally; to specify the context, use - * QueryContext. + * Stream sends a streaming response with status code and content type. */ - query(query: string, ...args: any[]): (Rows) - } - interface Tx { + stream(code: number, contentType: string, r: io.Reader): void /** - * QueryRowContext executes a query that is expected to return at most one row. - * QueryRowContext always returns a non-nil value. Errors are deferred until - * Row's Scan method is called. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. + * File sends a response with the content of the file. */ - queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) - } - interface Tx { + file(file: string): void /** - * QueryRow executes a query that is expected to return at most one row. - * QueryRow always returns a non-nil value. Errors are deferred until - * Row's Scan method is called. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. - * - * QueryRow uses context.Background internally; to specify the context, use - * QueryRowContext. + * FileFS sends a response with the content of the file from given filesystem. */ - queryRow(query: string, ...args: any[]): (Row) - } - /** - * Stmt is a prepared statement. - * A Stmt is safe for concurrent use by multiple goroutines. - * - * If a Stmt is prepared on a Tx or Conn, it will be bound to a single - * underlying connection forever. If the Tx or Conn closes, the Stmt will - * become unusable and all operations will return an error. - * If a Stmt is prepared on a DB, it will remain usable for the lifetime of the - * DB. When the Stmt needs to execute on a new underlying connection, it will - * prepare itself on the new connection automatically. - */ - interface Stmt { - } - interface Stmt { + fileFS(file: string, filesystem: fs.FS): void /** - * ExecContext executes a prepared statement with the given arguments and - * returns a Result summarizing the effect of the statement. + * Attachment sends a response as attachment, prompting client to save the + * file. */ - execContext(ctx: context.Context, ...args: any[]): Result - } - interface Stmt { + attachment(file: string, name: string): void /** - * Exec executes a prepared statement with the given arguments and - * returns a Result summarizing the effect of the statement. - * - * Exec uses context.Background internally; to specify the context, use - * ExecContext. + * Inline sends a response as inline, opening the file in the browser. */ - exec(...args: any[]): Result - } - interface Stmt { + inline(file: string, name: string): void /** - * QueryContext executes a prepared query statement with the given arguments - * and returns the query results as a *Rows. + * NoContent sends a response with no body and a status code. */ - queryContext(ctx: context.Context, ...args: any[]): (Rows) - } - interface Stmt { + noContent(code: number): void /** - * Query executes a prepared query statement with the given arguments - * and returns the query results as a *Rows. - * - * Query uses context.Background internally; to specify the context, use - * QueryContext. + * Redirect redirects the request to a provided URL with status code. */ - query(...args: any[]): (Rows) - } - interface Stmt { - /** - * QueryRowContext executes a prepared query statement with the given arguments. - * If an error occurs during the execution of the statement, that error will - * be returned by a call to Scan on the returned *Row, which is always non-nil. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. - */ - queryRowContext(ctx: context.Context, ...args: any[]): (Row) - } - interface Stmt { + redirect(code: number, url: string): void /** - * QueryRow executes a prepared query statement with the given arguments. - * If an error occurs during the execution of the statement, that error will - * be returned by a call to Scan on the returned *Row, which is always non-nil. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. - * - * Example usage: - * - * ``` - * var name string - * err := nameByUseridStmt.QueryRow(id).Scan(&name) - * ``` + * Error invokes the registered global HTTP error handler. Generally used by middleware. + * A side-effect of calling global error handler is that now Response has been committed (sent to the client) and + * middlewares up in chain can not change Response status code or Response body anymore. * - * QueryRow uses context.Background internally; to specify the context, use - * QueryRowContext. + * Avoid using this method in handlers as no middleware will be able to effectively handle errors after that. + * Instead of calling this method in handler return your error and let it be handled by middlewares or global error handler. */ - queryRow(...args: any[]): (Row) - } - interface Stmt { + error(err: Error): void /** - * Close closes the statement. + * Echo returns the `Echo` instance. + * + * WARNING: Remember that Echo public fields and methods are coroutine safe ONLY when you are NOT mutating them + * anywhere in your code after Echo server has started. */ - close(): void + echo(): (Echo) } + // @ts-ignore + import stdContext = context /** - * Rows is the result of a query. Its cursor starts before the first row - * of the result set. Use Next to advance from row to row. + * Echo is the top-level framework instance. + * + * Goroutine safety: Do not mutate Echo instance fields after server has started. Accessing these + * fields from handlers/middlewares and changing field values at the same time leads to data-races. + * Same rule applies to adding new routes after server has been started - Adding a route is not Goroutine safe action. */ - interface Rows { - } - interface Rows { + interface Echo { /** - * Next prepares the next result row for reading with the Scan method. It - * returns true on success, or false if there is no next result row or an error - * happened while preparing it. Err should be consulted to distinguish between - * the two cases. + * NewContextFunc allows using custom context implementations, instead of default *echo.context + */ + newContextFunc: (e: Echo, pathParamAllocSize: number) => ServableContext + debug: boolean + httpErrorHandler: HTTPErrorHandler + binder: Binder + jsonSerializer: JSONSerializer + validator: Validator + renderer: Renderer + logger: Logger + ipExtractor: IPExtractor + /** + * Filesystem is file system used by Static and File handlers to access files. + * Defaults to os.DirFS(".") * - * Every call to Scan, even the first one, must be preceded by a call to Next. + * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary + * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths + * including `assets/images` as their prefix. */ - next(): boolean + filesystem: fs.FS + /** + * OnAddRoute is called when Echo adds new route to specific host router. Handler is called for every router + * and before route is added to the host router. + */ + onAddRoute: (host: string, route: Routable) => void } - interface Rows { + /** + * HandlerFunc defines a function to serve HTTP requests. + */ + interface HandlerFunc {(c: Context): void } + /** + * MiddlewareFunc defines a function to process middleware. + */ + interface MiddlewareFunc {(next: HandlerFunc): HandlerFunc } + interface Echo { /** - * NextResultSet prepares the next result set for reading. It reports whether - * there is further result sets, or false if there is no further result set - * or if there is an error advancing to it. The Err method should be consulted - * to distinguish between the two cases. + * NewContext returns a new Context instance. * - * After calling NextResultSet, the Next method should always be called before - * scanning. If there are further result sets they may not have rows in the result - * set. + * Note: both request and response can be left to nil as Echo.ServeHTTP will call c.Reset(req,resp) anyway + * these arguments are useful when creating context for tests and cases like that. */ - nextResultSet(): boolean + newContext(r: http.Request, w: http.ResponseWriter): Context } - interface Rows { + interface Echo { /** - * Err returns the error, if any, that was encountered during iteration. - * Err may be called after an explicit or implicit Close. + * Router returns the default router. */ - err(): void + router(): Router } - interface Rows { + interface Echo { /** - * Columns returns the column names. - * Columns returns an error if the rows are closed. + * Routers returns the new map of host => router. */ - columns(): Array + routers(): _TygojaDict } - interface Rows { + interface Echo { /** - * ColumnTypes returns column information such as column type, length, - * and nullable. Some information may not be available from some drivers. + * RouterFor returns Router for given host. When host is left empty the default router is returned. */ - columnTypes(): Array<(ColumnType | undefined)> + routerFor(host: string): [Router, boolean] } - interface Rows { + interface Echo { /** - * Scan copies the columns in the current row into the values pointed - * at by dest. The number of values in dest must be the same as the - * number of columns in Rows. - * - * Scan converts columns read from the database into the following - * common Go types and special types provided by the sql package: - * - * ``` - * *string - * *[]byte - * *int, *int8, *int16, *int32, *int64 - * *uint, *uint8, *uint16, *uint32, *uint64 - * *bool - * *float32, *float64 - * *interface{} - * *RawBytes - * *Rows (cursor value) - * any type implementing Scanner (see Scanner docs) - * ``` - * - * In the most simple case, if the type of the value from the source - * column is an integer, bool or string type T and dest is of type *T, - * Scan simply assigns the value through the pointer. - * - * Scan also converts between string and numeric types, as long as no - * information would be lost. While Scan stringifies all numbers - * scanned from numeric database columns into *string, scans into - * numeric types are checked for overflow. For example, a float64 with - * value 300 or a string with value "300" can scan into a uint16, but - * not into a uint8, though float64(255) or "255" can scan into a - * uint8. One exception is that scans of some float64 numbers to - * strings may lose information when stringifying. In general, scan - * floating point columns into *float64. - * - * If a dest argument has type *[]byte, Scan saves in that argument a - * copy of the corresponding data. The copy is owned by the caller and - * can be modified and held indefinitely. The copy can be avoided by - * using an argument of type *RawBytes instead; see the documentation - * for RawBytes for restrictions on its use. - * - * If an argument has type *interface{}, Scan copies the value - * provided by the underlying driver without conversion. When scanning - * from a source value of type []byte to *interface{}, a copy of the - * slice is made and the caller owns the result. - * - * Source values of type time.Time may be scanned into values of type - * *time.Time, *interface{}, *string, or *[]byte. When converting to - * the latter two, time.RFC3339Nano is used. - * - * Source values of type bool may be scanned into types *bool, - * *interface{}, *string, *[]byte, or *RawBytes. - * - * For scanning into *bool, the source may be true, false, 1, 0, or - * string inputs parseable by strconv.ParseBool. - * - * Scan can also convert a cursor returned from a query, such as - * "select cursor(select * from my_table) from dual", into a - * *Rows value that can itself be scanned from. The parent - * select query will close any cursor *Rows if the parent *Rows is closed. - * - * If any of the first arguments implementing Scanner returns an error, - * that error will be wrapped in the returned error. + * ResetRouterCreator resets callback for creating new router instances. + * Note: current (default) router is immediately replaced with router created with creator func and vhost routers are cleared. */ - scan(...dest: any[]): void + resetRouterCreator(creator: (e: Echo) => Router): void } - interface Rows { + interface Echo { /** - * Close closes the Rows, preventing further enumeration. If Next is called - * and returns false and there are no further result sets, - * the Rows are closed automatically and it will suffice to check the - * result of Err. Close is idempotent and does not affect the result of Err. + * Pre adds middleware to the chain which is run before router tries to find matching route. + * Meaning middleware is executed even for 404 (not found) cases. */ - close(): void + pre(...middleware: MiddlewareFunc[]): void } - /** - * A Result summarizes an executed SQL command. - */ - interface Result { - [key:string]: any; + interface Echo { /** - * LastInsertId returns the integer generated by the database - * in response to a command. Typically this will be from an - * "auto increment" column when inserting a new row. Not all - * databases support this feature, and the syntax of such - * statements varies. + * Use adds middleware to the chain which is run after router has found matching route and before route/request handler method is executed. */ - lastInsertId(): number + use(...middleware: MiddlewareFunc[]): void + } + interface Echo { /** - * RowsAffected returns the number of rows affected by an - * update, insert, or delete. Not every database or database - * driver may support this. + * CONNECT registers a new CONNECT route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - rowsAffected(): number - } -} - -/** - * Package models implements all PocketBase DB models and DTOs. - */ -namespace models { - type _subYlRNg = BaseModel - interface Admin extends _subYlRNg { - avatar: number - email: string - tokenKey: string - passwordHash: string - lastResetSentAt: types.DateTime + connect(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Admin { + interface Echo { /** - * TableName returns the Admin model SQL table name. + * DELETE registers a new DELETE route for a path with matching handler in the router + * with optional route-level middleware. Panics on error. */ - tableName(): string + delete(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Admin { + interface Echo { /** - * ValidatePassword validates a plain password against the model's password. + * GET registers a new GET route for a path with matching handler in the router + * with optional route-level middleware. Panics on error. */ - validatePassword(password: string): boolean + get(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Admin { - /** - * SetPassword sets cryptographically secure string to `model.Password`. - * - * Additionally this method also resets the LastResetSentAt and the TokenKey fields. - */ - setPassword(password: string): void - } - interface Admin { + interface Echo { /** - * RefreshTokenKey generates and sets new random token key. + * HEAD registers a new HEAD route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - refreshTokenKey(): void + head(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - // @ts-ignore - import validation = ozzo_validation - type _subeQlzp = BaseModel - interface Collection extends _subeQlzp { - name: string - type: string - system: boolean - schema: schema.Schema - indexes: types.JsonArray + interface Echo { /** - * rules + * OPTIONS registers a new OPTIONS route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - listRule?: string - viewRule?: string - createRule?: string - updateRule?: string - deleteRule?: string - options: types.JsonMap + options(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * TableName returns the Collection model SQL table name. + * PATCH registers a new PATCH route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - tableName(): string + patch(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * BaseFilesPath returns the storage dir path used by the collection. + * POST registers a new POST route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - baseFilesPath(): string + post(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * IsBase checks if the current collection has "base" type. + * PUT registers a new PUT route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - isBase(): boolean + put(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * IsAuth checks if the current collection has "auth" type. + * TRACE registers a new TRACE route for a path with matching handler in the + * router with optional route-level middleware. Panics on error. */ - isAuth(): boolean + trace(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * IsView checks if the current collection has "view" type. + * RouteNotFound registers a special-case route which is executed when no other route is found (i.e. HTTP 404 cases) + * for current request URL. + * Path supports static and named/any parameters just like other http method is defined. Generally path is ended with + * wildcard/match-any character (`/*`, `/download/*` etc). + * + * Example: `e.RouteNotFound("/*", func(c echo.Context) error { return c.NoContent(http.StatusNotFound) })` */ - isView(): boolean + routeNotFound(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * MarshalJSON implements the [json.Marshaler] interface. + * Any registers a new route for all HTTP methods (supported by Echo) and path with matching handler + * in the router with optional route-level middleware. + * + * Note: this method only adds specific set of supported HTTP methods as handler and is not true + * "catch-any-arbitrary-method" way of matching requests. */ - marshalJSON(): string|Array + any(path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes } - interface Collection { + interface Echo { /** - * BaseOptions decodes the current collection options and returns them - * as new [CollectionBaseOptions] instance. + * Match registers a new route for multiple HTTP methods and path with matching + * handler in the router with optional route-level middleware. Panics on error. */ - baseOptions(): CollectionBaseOptions + match(methods: Array, path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes } - interface Collection { + interface Echo { /** - * AuthOptions decodes the current collection options and returns them - * as new [CollectionAuthOptions] instance. + * Static registers a new route with path prefix to serve static files from the provided root directory. */ - authOptions(): CollectionAuthOptions + static(pathPrefix: string): RouteInfo } - interface Collection { + interface Echo { /** - * ViewOptions decodes the current collection options and returns them - * as new [CollectionViewOptions] instance. + * StaticFS registers a new route with path prefix to serve static files from the provided file system. + * + * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary + * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths + * including `assets/images` as their prefix. */ - viewOptions(): CollectionViewOptions + staticFS(pathPrefix: string, filesystem: fs.FS): RouteInfo } - interface Collection { + interface Echo { /** - * NormalizeOptions updates the current collection options with a - * new normalized state based on the collection type. + * FileFS registers a new route with path to serve file from the provided file system. */ - normalizeOptions(): void + fileFS(path: string, filesystem: fs.FS, ...m: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * DecodeOptions decodes the current collection options into the - * provided "result" (must be a pointer). + * File registers a new route with path to serve a static file with optional route-level middleware. Panics on error. */ - decodeOptions(result: any): void + file(path: string, ...middleware: MiddlewareFunc[]): RouteInfo } - interface Collection { + interface Echo { /** - * SetOptions normalizes and unmarshals the specified options into m.Options. + * AddRoute registers a new Route with default host Router */ - setOptions(typedOptions: any): void - } - type _subbYlmv = BaseModel - interface ExternalAuth extends _subbYlmv { - collectionId: string - recordId: string - provider: string - providerId: string - } - interface ExternalAuth { - tableName(): string - } - type _subgEvDY = BaseModel - interface Record extends _subgEvDY { + addRoute(route: Routable): RouteInfo } - interface Record { + interface Echo { /** - * TableName returns the table name associated to the current Record model. + * Add registers a new route for an HTTP method and path with matching handler + * in the router with optional route-level middleware. */ - tableName(): string + add(method: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): RouteInfo } - interface Record { + interface Echo { /** - * Collection returns the Collection model associated to the current Record model. + * Host creates a new router group for the provided host and optional host-level middleware. */ - collection(): (Collection) + host(name: string, ...m: MiddlewareFunc[]): (Group) } - interface Record { + interface Echo { /** - * OriginalCopy returns a copy of the current record model populated - * with its ORIGINAL data state (aka. the initially loaded) and - * everything else reset to the defaults. + * Group creates a new router group with prefix and optional group-level middleware. */ - originalCopy(): (Record) + group(prefix: string, ...m: MiddlewareFunc[]): (Group) } - interface Record { + interface Echo { /** - * CleanCopy returns a copy of the current record model populated only - * with its LATEST data state and everything else reset to the defaults. + * AcquireContext returns an empty `Context` instance from the pool. + * You must return the context by calling `ReleaseContext()`. */ - cleanCopy(): (Record) + acquireContext(): Context } - interface Record { + interface Echo { /** - * Expand returns a shallow copy of the current Record model expand data. + * ReleaseContext returns the `Context` instance back to the pool. + * You must call it after `AcquireContext()`. */ - expand(): _TygojaDict + releaseContext(c: Context): void } - interface Record { + interface Echo { /** - * SetExpand shallow copies the provided data to the current Record model's expand. + * ServeHTTP implements `http.Handler` interface, which serves HTTP requests. */ - setExpand(expand: _TygojaDict): void + serveHTTP(w: http.ResponseWriter, r: http.Request): void } - interface Record { + interface Echo { /** - * MergeExpand merges recursively the provided expand data into - * the current model's expand (if any). + * Start stars HTTP server on given address with Echo as a handler serving requests. The server can be shutdown by + * sending os.Interrupt signal with `ctrl+c`. * - * Note that if an expanded prop with the same key is a slice (old or new expand) - * then both old and new records will be merged into a new slice (aka. a :merge: [b,c] => [a,b,c]). - * Otherwise the "old" expanded record will be replace with the "new" one (aka. a :merge: aNew => aNew). - */ - mergeExpand(expand: _TygojaDict): void - } - interface Record { - /** - * SchemaData returns a shallow copy ONLY of the defined record schema fields data. - */ - schemaData(): _TygojaDict - } - interface Record { - /** - * UnknownData returns a shallow copy ONLY of the unknown record fields data, - * aka. fields that are neither one of the base and special system ones, - * nor defined by the collection schema. - */ - unknownData(): _TygojaDict - } - interface Record { - /** - * IgnoreEmailVisibility toggles the flag to ignore the auth record email visibility check. - */ - ignoreEmailVisibility(state: boolean): void - } - interface Record { - /** - * WithUnknownData toggles the export/serialization of unknown data fields - * (false by default). - */ - withUnknownData(state: boolean): void - } - interface Record { - /** - * Set sets the provided key-value data pair for the current Record model. + * Note: this method is created for use in examples/demos and is deliberately simple without providing configuration + * options. * - * If the record collection has field with name matching the provided "key", - * the value will be further normalized according to the field rules. - */ - set(key: string, value: any): void - } - interface Record { - /** - * Get returns a normalized single record model data value for "key". - */ - get(key: string): any - } - interface Record { - /** - * GetBool returns the data value for "key" as a bool. + * In need of customization use: + * + * ``` + * sc := echo.StartConfig{Address: ":8080"} + * if err := sc.Start(e); err != http.ErrServerClosed { + * log.Fatal(err) + * } + * ``` + * + * // or standard library `http.Server` + * + * ``` + * s := http.Server{Addr: ":8080", Handler: e} + * if err := s.ListenAndServe(); err != http.ErrServerClosed { + * log.Fatal(err) + * } + * ``` */ - getBool(key: string): boolean + start(address: string): void } - interface Record { - /** - * GetString returns the data value for "key" as a string. - */ - getString(key: string): string - } - interface Record { - /** - * GetInt returns the data value for "key" as an int. - */ - getInt(key: string): number - } - interface Record { +} + +/** + * Package exec runs external commands. It wraps os.StartProcess to make it + * easier to remap stdin and stdout, connect I/O with pipes, and do other + * adjustments. + * + * Unlike the "system" library call from C and other languages, the + * os/exec package intentionally does not invoke the system shell and + * does not expand any glob patterns or handle other expansions, + * pipelines, or redirections typically done by shells. The package + * behaves more like C's "exec" family of functions. To expand glob + * patterns, either call the shell directly, taking care to escape any + * dangerous input, or use the path/filepath package's Glob function. + * To expand environment variables, use package os's ExpandEnv. + * + * Note that the examples in this package assume a Unix system. + * They may not run on Windows, and they do not run in the Go Playground + * used by golang.org and godoc.org. + * + * # Executables in the current directory + * + * The functions Command and LookPath look for a program + * in the directories listed in the current path, following the + * conventions of the host operating system. + * Operating systems have for decades included the current + * directory in this search, sometimes implicitly and sometimes + * configured explicitly that way by default. + * Modern practice is that including the current directory + * is usually unexpected and often leads to security problems. + * + * To avoid those security problems, as of Go 1.19, this package will not resolve a program + * using an implicit or explicit path entry relative to the current directory. + * That is, if you run exec.LookPath("go"), it will not successfully return + * ./go on Unix nor .\go.exe on Windows, no matter how the path is configured. + * Instead, if the usual path algorithms would result in that answer, + * these functions return an error err satisfying errors.Is(err, ErrDot). + * + * For example, consider these two program snippets: + * + * ``` + * path, err := exec.LookPath("prog") + * if err != nil { + * log.Fatal(err) + * } + * use(path) + * ``` + * + * and + * + * ``` + * cmd := exec.Command("prog") + * if err := cmd.Run(); err != nil { + * log.Fatal(err) + * } + * ``` + * + * These will not find and run ./prog or .\prog.exe, + * no matter how the current path is configured. + * + * Code that always wants to run a program from the current directory + * can be rewritten to say "./prog" instead of "prog". + * + * Code that insists on including results from relative path entries + * can instead override the error using an errors.Is check: + * + * ``` + * path, err := exec.LookPath("prog") + * if errors.Is(err, exec.ErrDot) { + * err = nil + * } + * if err != nil { + * log.Fatal(err) + * } + * use(path) + * ``` + * + * and + * + * ``` + * cmd := exec.Command("prog") + * if errors.Is(cmd.Err, exec.ErrDot) { + * cmd.Err = nil + * } + * if err := cmd.Run(); err != nil { + * log.Fatal(err) + * } + * ``` + * + * Setting the environment variable GODEBUG=execerrdot=0 + * disables generation of ErrDot entirely, temporarily restoring the pre-Go 1.19 + * behavior for programs that are unable to apply more targeted fixes. + * A future version of Go may remove support for this variable. + * + * Before adding such overrides, make sure you understand the + * security implications of doing so. + * See https://go.dev/blog/path-security for more information. + */ +namespace exec { + /** + * Cmd represents an external command being prepared or run. + * + * A Cmd cannot be reused after calling its Run, Output or CombinedOutput + * methods. + */ + interface Cmd { /** - * GetFloat returns the data value for "key" as a float64. + * Path is the path of the command to run. + * + * This is the only field that must be set to a non-zero + * value. If Path is relative, it is evaluated relative + * to Dir. */ - getFloat(key: string): number - } - interface Record { + path: string /** - * GetTime returns the data value for "key" as a [time.Time] instance. + * Args holds command line arguments, including the command as Args[0]. + * If the Args field is empty or nil, Run uses {Path}. + * + * In typical use, both Path and Args are set by calling Command. */ - getTime(key: string): time.Time - } - interface Record { + args: Array /** - * GetDateTime returns the data value for "key" as a DateTime instance. + * Env specifies the environment of the process. + * Each entry is of the form "key=value". + * If Env is nil, the new process uses the current process's + * environment. + * If Env contains duplicate environment keys, only the last + * value in the slice for each duplicate key is used. + * As a special case on Windows, SYSTEMROOT is always added if + * missing and not explicitly set to the empty string. */ - getDateTime(key: string): types.DateTime - } - interface Record { + env: Array /** - * GetStringSlice returns the data value for "key" as a slice of unique strings. + * Dir specifies the working directory of the command. + * If Dir is the empty string, Run runs the command in the + * calling process's current directory. */ - getStringSlice(key: string): Array - } - interface Record { + dir: string /** - * ExpandedOne retrieves a single relation Record from the already - * loaded expand data of the current model. + * Stdin specifies the process's standard input. * - * If the requested expand relation is multiple, this method returns - * only first available Record from the expanded relation. + * If Stdin is nil, the process reads from the null device (os.DevNull). * - * Returns nil if there is no such expand relation loaded. + * If Stdin is an *os.File, the process's standard input is connected + * directly to that file. + * + * Otherwise, during the execution of the command a separate + * goroutine reads from Stdin and delivers that data to the command + * over a pipe. In this case, Wait does not complete until the goroutine + * stops copying, either because it has reached the end of Stdin + * (EOF or a read error), or because writing to the pipe returned an error, + * or because a nonzero WaitDelay was set and expired. */ - expandedOne(relField: string): (Record) - } - interface Record { + stdin: io.Reader /** - * ExpandedAll retrieves a slice of relation Records from the already - * loaded expand data of the current model. + * Stdout and Stderr specify the process's standard output and error. * - * If the requested expand relation is single, this method normalizes - * the return result and will wrap the single model as a slice. + * If either is nil, Run connects the corresponding file descriptor + * to the null device (os.DevNull). * - * Returns nil slice if there is no such expand relation loaded. - */ - expandedAll(relField: string): Array<(Record | undefined)> - } - interface Record { - /** - * Retrieves the "key" json field value and unmarshals it into "result". + * If either is an *os.File, the corresponding output from the process + * is connected directly to that file. * - * Example + * Otherwise, during the execution of the command a separate goroutine + * reads from the process over a pipe and delivers that data to the + * corresponding Writer. In this case, Wait does not complete until the + * goroutine reaches EOF or encounters an error or a nonzero WaitDelay + * expires. * - * ``` - * result := struct { - * FirstName string `json:"first_name"` - * }{} - * err := m.UnmarshalJSONField("my_field_name", &result) - * ``` + * If Stdout and Stderr are the same writer, and have a type that can + * be compared with ==, at most one goroutine at a time will call Write. */ - unmarshalJSONField(key: string, result: any): void - } - interface Record { + stdout: io.Writer + stderr: io.Writer /** - * BaseFilesPath returns the storage dir path used by the record. + * ExtraFiles specifies additional open files to be inherited by the + * new process. It does not include standard input, standard output, or + * standard error. If non-nil, entry i becomes file descriptor 3+i. + * + * ExtraFiles is not supported on Windows. */ - baseFilesPath(): string - } - interface Record { + extraFiles: Array<(os.File | undefined)> /** - * FindFileFieldByFile returns the first file type field for which - * any of the record's data contains the provided filename. + * SysProcAttr holds optional, operating system-specific attributes. + * Run passes it to os.StartProcess as the os.ProcAttr's Sys field. */ - findFileFieldByFile(filename: string): (schema.SchemaField) - } - interface Record { + sysProcAttr?: syscall.SysProcAttr /** - * Load bulk loads the provided data into the current Record model. + * Process is the underlying process, once started. */ - load(data: _TygojaDict): void - } - interface Record { + process?: os.Process /** - * ColumnValueMap implements [ColumnValueMapper] interface. + * ProcessState contains information about an exited process. + * If the process was started successfully, Wait or Run will + * populate its ProcessState when the command completes. */ - columnValueMap(): _TygojaDict - } - interface Record { + processState?: os.ProcessState + err: Error // LookPath error, if any. /** - * PublicExport exports only the record fields that are safe to be public. + * If Cancel is non-nil, the command must have been created with + * CommandContext and Cancel will be called when the command's + * Context is done. By default, CommandContext sets Cancel to + * call the Kill method on the command's Process. * - * For auth records, to force the export of the email field you need to set - * `m.IgnoreEmailVisibility(true)`. - */ - publicExport(): _TygojaDict - } - interface Record { - /** - * MarshalJSON implements the [json.Marshaler] interface. + * Typically a custom Cancel will send a signal to the command's + * Process, but it may instead take other actions to initiate cancellation, + * such as closing a stdin or stdout pipe or sending a shutdown request on a + * network socket. * - * Only the data exported by `PublicExport()` will be serialized. - */ - marshalJSON(): string|Array - } - interface Record { - /** - * UnmarshalJSON implements the [json.Unmarshaler] interface. + * If the command exits with a success status after Cancel is + * called, and Cancel does not return an error equivalent to + * os.ErrProcessDone, then Wait and similar methods will return a non-nil + * error: either an error wrapping the one returned by Cancel, + * or the error from the Context. + * (If the command exits with a non-success status, or Cancel + * returns an error that wraps os.ErrProcessDone, Wait and similar methods + * continue to return the command's usual exit status.) + * + * If Cancel is set to nil, nothing will happen immediately when the command's + * Context is done, but a nonzero WaitDelay will still take effect. That may + * be useful, for example, to work around deadlocks in commands that do not + * support shutdown signals but are expected to always finish quickly. + * + * Cancel will not be called if Start returns a non-nil error. */ - unmarshalJSON(data: string|Array): void - } - interface Record { + cancel: () => void /** - * ReplaceModifers returns a new map with applied modifier - * values based on the current record and the specified data. + * If WaitDelay is non-zero, it bounds the time spent waiting on two sources + * of unexpected delay in Wait: a child process that fails to exit after the + * associated Context is canceled, and a child process that exits but leaves + * its I/O pipes unclosed. * - * The resolved modifier keys will be removed. + * The WaitDelay timer starts when either the associated Context is done or a + * call to Wait observes that the child process has exited, whichever occurs + * first. When the delay has elapsed, the command shuts down the child process + * and/or its I/O pipes. * - * Multiple modifiers will be applied one after another, - * while reusing the previous base key value result (eg. 1; -5; +2 => -2). + * If the child process has failed to exit — perhaps because it ignored or + * failed to receive a shutdown signal from a Cancel function, or because no + * Cancel function was set — then it will be terminated using os.Process.Kill. * - * Example usage: + * Then, if the I/O pipes communicating with the child process are still open, + * those pipes are closed in order to unblock any goroutines currently blocked + * on Read or Write calls. * - * ``` - * newData := record.ReplaceModifers(data) - * // record: {"field": 10} - * // data: {"field+": 5} - * // newData: {"field": 15} - * ``` + * If pipes are closed due to WaitDelay, no Cancel call has occurred, + * and the command has otherwise exited with a successful status, Wait and + * similar methods will return ErrWaitDelay instead of nil. + * + * If WaitDelay is zero (the default), I/O pipes will be read until EOF, + * which might not occur until orphaned subprocesses of the command have + * also closed their descriptors for the pipes. */ - replaceModifers(data: _TygojaDict): _TygojaDict + waitDelay: time.Duration } - interface Record { + interface Cmd { /** - * Username returns the "username" auth record data value. + * String returns a human-readable description of c. + * It is intended only for debugging. + * In particular, it is not suitable for use as input to a shell. + * The output of String may vary across Go releases. */ - username(): string + string(): string } - interface Record { + interface Cmd { /** - * SetUsername sets the "username" auth record data value. + * Run starts the specified command and waits for it to complete. * - * This method doesn't check whether the provided value is a valid username. + * The returned error is nil if the command runs, has no problems + * copying stdin, stdout, and stderr, and exits with a zero exit + * status. * - * Returns an error if the record is not from an auth collection. + * If the command starts but does not complete successfully, the error is of + * type *ExitError. Other error types may be returned for other situations. + * + * If the calling goroutine has locked the operating system thread + * with runtime.LockOSThread and modified any inheritable OS-level + * thread state (for example, Linux or Plan 9 name spaces), the new + * process will inherit the caller's thread state. */ - setUsername(username: string): void + run(): void } - interface Record { + interface Cmd { /** - * Email returns the "email" auth record data value. + * Start starts the specified command but does not wait for it to complete. + * + * If Start returns successfully, the c.Process field will be set. + * + * After a successful call to Start the Wait method must be called in + * order to release associated system resources. */ - email(): string + start(): void } - interface Record { + interface Cmd { /** - * SetEmail sets the "email" auth record data value. + * Wait waits for the command to exit and waits for any copying to + * stdin or copying from stdout or stderr to complete. * - * This method doesn't check whether the provided value is a valid email. + * The command must have been started by Start. * - * Returns an error if the record is not from an auth collection. + * The returned error is nil if the command runs, has no problems + * copying stdin, stdout, and stderr, and exits with a zero exit + * status. + * + * If the command fails to run or doesn't complete successfully, the + * error is of type *ExitError. Other error types may be + * returned for I/O problems. + * + * If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits + * for the respective I/O loop copying to or from the process to complete. + * + * Wait releases any resources associated with the Cmd. */ - setEmail(email: string): void + wait(): void } - interface Record { + interface Cmd { /** - * Verified returns the "emailVisibility" auth record data value. + * Output runs the command and returns its standard output. + * Any returned error will usually be of type *ExitError. + * If c.Stderr was nil, Output populates ExitError.Stderr. */ - emailVisibility(): boolean + output(): string|Array } - interface Record { + interface Cmd { /** - * SetEmailVisibility sets the "emailVisibility" auth record data value. - * - * Returns an error if the record is not from an auth collection. + * CombinedOutput runs the command and returns its combined standard + * output and standard error. */ - setEmailVisibility(visible: boolean): void + combinedOutput(): string|Array } - interface Record { + interface Cmd { /** - * Verified returns the "verified" auth record data value. + * StdinPipe returns a pipe that will be connected to the command's + * standard input when the command starts. + * The pipe will be closed automatically after Wait sees the command exit. + * A caller need only call Close to force the pipe to close sooner. + * For example, if the command being run will not exit until standard input + * is closed, the caller must close the pipe. */ - verified(): boolean + stdinPipe(): io.WriteCloser } - interface Record { + interface Cmd { /** - * SetVerified sets the "verified" auth record data value. + * StdoutPipe returns a pipe that will be connected to the command's + * standard output when the command starts. * - * Returns an error if the record is not from an auth collection. + * Wait will close the pipe after seeing the command exit, so most callers + * need not close the pipe themselves. It is thus incorrect to call Wait + * before all reads from the pipe have completed. + * For the same reason, it is incorrect to call Run when using StdoutPipe. + * See the example for idiomatic usage. */ - setVerified(verified: boolean): void + stdoutPipe(): io.ReadCloser } - interface Record { + interface Cmd { /** - * TokenKey returns the "tokenKey" auth record data value. + * StderrPipe returns a pipe that will be connected to the command's + * standard error when the command starts. + * + * Wait will close the pipe after seeing the command exit, so most callers + * need not close the pipe themselves. It is thus incorrect to call Wait + * before all reads from the pipe have completed. + * For the same reason, it is incorrect to use Run when using StderrPipe. + * See the StdoutPipe example for idiomatic usage. */ - tokenKey(): string + stderrPipe(): io.ReadCloser } - interface Record { + interface Cmd { /** - * SetTokenKey sets the "tokenKey" auth record data value. - * - * Returns an error if the record is not from an auth collection. + * Environ returns a copy of the environment in which the command would be run + * as it is currently configured. */ - setTokenKey(key: string): void + environ(): Array } - interface Record { +} + +/** + * Package sql provides a generic interface around SQL (or SQL-like) + * databases. + * + * The sql package must be used in conjunction with a database driver. + * See https://golang.org/s/sqldrivers for a list of drivers. + * + * Drivers that do not support context cancellation will not return until + * after the query is completed. + * + * For usage examples, see the wiki page at + * https://golang.org/s/sqlwiki. + */ +namespace sql { + /** + * TxOptions holds the transaction options to be used in DB.BeginTx. + */ + interface TxOptions { /** - * RefreshTokenKey generates and sets new random auth record "tokenKey". - * - * Returns an error if the record is not from an auth collection. + * Isolation is the transaction isolation level. + * If zero, the driver or database's default level is used. */ - refreshTokenKey(): void + isolation: IsolationLevel + readOnly: boolean } - interface Record { + /** + * DB is a database handle representing a pool of zero or more + * underlying connections. It's safe for concurrent use by multiple + * goroutines. + * + * The sql package creates and frees connections automatically; it + * also maintains a free pool of idle connections. If the database has + * a concept of per-connection state, such state can be reliably observed + * within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the + * returned Tx is bound to a single connection. Once Commit or + * Rollback is called on the transaction, that transaction's + * connection is returned to DB's idle connection pool. The pool size + * can be controlled with SetMaxIdleConns. + */ + interface DB { + } + interface DB { /** - * LastResetSentAt returns the "lastResentSentAt" auth record data value. + * PingContext verifies a connection to the database is still alive, + * establishing a connection if necessary. */ - lastResetSentAt(): types.DateTime + pingContext(ctx: context.Context): void } - interface Record { + interface DB { /** - * SetLastResetSentAt sets the "lastResentSentAt" auth record data value. + * Ping verifies a connection to the database is still alive, + * establishing a connection if necessary. * - * Returns an error if the record is not from an auth collection. + * Ping uses context.Background internally; to specify the context, use + * PingContext. */ - setLastResetSentAt(dateTime: types.DateTime): void + ping(): void } - interface Record { + interface DB { /** - * LastVerificationSentAt returns the "lastVerificationSentAt" auth record data value. + * Close closes the database and prevents new queries from starting. + * Close then waits for all queries that have started processing on the server + * to finish. + * + * It is rare to Close a DB, as the DB handle is meant to be + * long-lived and shared between many goroutines. */ - lastVerificationSentAt(): types.DateTime + close(): void } - interface Record { + interface DB { /** - * SetLastVerificationSentAt sets an "lastVerificationSentAt" auth record data value. + * SetMaxIdleConns sets the maximum number of connections in the idle + * connection pool. * - * Returns an error if the record is not from an auth collection. + * If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, + * then the new MaxIdleConns will be reduced to match the MaxOpenConns limit. + * + * If n <= 0, no idle connections are retained. + * + * The default max idle connections is currently 2. This may change in + * a future release. */ - setLastVerificationSentAt(dateTime: types.DateTime): void + setMaxIdleConns(n: number): void } - interface Record { + interface DB { /** - * PasswordHash returns the "passwordHash" auth record data value. + * SetMaxOpenConns sets the maximum number of open connections to the database. + * + * If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than + * MaxIdleConns, then MaxIdleConns will be reduced to match the new + * MaxOpenConns limit. + * + * If n <= 0, then there is no limit on the number of open connections. + * The default is 0 (unlimited). */ - passwordHash(): string + setMaxOpenConns(n: number): void } - interface Record { + interface DB { /** - * ValidatePassword validates a plain password against the auth record password. + * SetConnMaxLifetime sets the maximum amount of time a connection may be reused. * - * Returns false if the password is incorrect or record is not from an auth collection. + * Expired connections may be closed lazily before reuse. + * + * If d <= 0, connections are not closed due to a connection's age. */ - validatePassword(password: string): boolean + setConnMaxLifetime(d: time.Duration): void } - interface Record { + interface DB { /** - * SetPassword sets cryptographically secure string to the auth record "password" field. - * This method also resets the "lastResetSentAt" and the "tokenKey" fields. + * SetConnMaxIdleTime sets the maximum amount of time a connection may be idle. * - * Returns an error if the record is not from an auth collection or - * an empty password is provided. + * Expired connections may be closed lazily before reuse. + * + * If d <= 0, connections are not closed due to a connection's idle time. */ - setPassword(password: string): void - } - /** - * RequestInfo defines a HTTP request data struct, usually used - * as part of the `@request.*` filter resolver. - */ - interface RequestInfo { - query: _TygojaDict - data: _TygojaDict - headers: _TygojaDict - authRecord?: Record - admin?: Admin - method: string + setConnMaxIdleTime(d: time.Duration): void } - interface RequestInfo { + interface DB { /** - * HasModifierDataKeys loosely checks if the current struct has any modifier Data keys. + * Stats returns database statistics. */ - hasModifierDataKeys(): boolean - } -} - -namespace auth { - /** - * AuthUser defines a standardized oauth2 user data structure. - */ - interface AuthUser { - id: string - name: string - username: string - email: string - avatarUrl: string - accessToken: string - refreshToken: string - expiry: types.DateTime - rawUser: _TygojaDict + stats(): DBStats } - /** - * Provider defines a common interface for an OAuth2 client. - */ - interface Provider { - [key:string]: any; + interface DB { /** - * Scopes returns the context associated with the provider (if any). + * PrepareContext creates a prepared statement for later queries or executions. + * Multiple queries or executions may be run concurrently from the + * returned statement. + * The caller must call the statement's Close method + * when the statement is no longer needed. + * + * The provided context is used for the preparation of the statement, not for the + * execution of the statement. */ - context(): context.Context + prepareContext(ctx: context.Context, query: string): (Stmt) + } + interface DB { /** - * SetContext assigns the specified context to the current provider. + * Prepare creates a prepared statement for later queries or executions. + * Multiple queries or executions may be run concurrently from the + * returned statement. + * The caller must call the statement's Close method + * when the statement is no longer needed. + * + * Prepare uses context.Background internally; to specify the context, use + * PrepareContext. */ - setContext(ctx: context.Context): void + prepare(query: string): (Stmt) + } + interface DB { /** - * PKCE indicates whether the provider can use the PKCE flow. + * ExecContext executes a query without returning any rows. + * The args are for any placeholder parameters in the query. */ - pkce(): boolean + execContext(ctx: context.Context, query: string, ...args: any[]): Result + } + interface DB { /** - * SetPKCE toggles the state whether the provider can use the PKCE flow or not. + * Exec executes a query without returning any rows. + * The args are for any placeholder parameters in the query. + * + * Exec uses context.Background internally; to specify the context, use + * ExecContext. */ - setPKCE(enable: boolean): void + exec(query: string, ...args: any[]): Result + } + interface DB { /** - * DisplayName usually returns provider name as it is officially written - * and it could be used directly in the UI. + * QueryContext executes a query that returns rows, typically a SELECT. + * The args are for any placeholder parameters in the query. */ - displayName(): string + queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) + } + interface DB { /** - * SetDisplayName sets the provider's display name. + * Query executes a query that returns rows, typically a SELECT. + * The args are for any placeholder parameters in the query. + * + * Query uses context.Background internally; to specify the context, use + * QueryContext. */ - setDisplayName(displayName: string): void + query(query: string, ...args: any[]): (Rows) + } + interface DB { /** - * Scopes returns the provider access permissions that will be requested. + * QueryRowContext executes a query that is expected to return at most one row. + * QueryRowContext always returns a non-nil value. Errors are deferred until + * Row's Scan method is called. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. */ - scopes(): Array + queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) + } + interface DB { /** - * SetScopes sets the provider access permissions that will be requested later. + * QueryRow executes a query that is expected to return at most one row. + * QueryRow always returns a non-nil value. Errors are deferred until + * Row's Scan method is called. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. + * + * QueryRow uses context.Background internally; to specify the context, use + * QueryRowContext. */ - setScopes(scopes: Array): void + queryRow(query: string, ...args: any[]): (Row) + } + interface DB { /** - * ClientId returns the provider client's app ID. + * BeginTx starts a transaction. + * + * The provided context is used until the transaction is committed or rolled back. + * If the context is canceled, the sql package will roll back + * the transaction. Tx.Commit will return an error if the context provided to + * BeginTx is canceled. + * + * The provided TxOptions is optional and may be nil if defaults should be used. + * If a non-default isolation level is used that the driver doesn't support, + * an error will be returned. */ - clientId(): string + beginTx(ctx: context.Context, opts: TxOptions): (Tx) + } + interface DB { /** - * SetClientId sets the provider client's ID. + * Begin starts a transaction. The default isolation level is dependent on + * the driver. + * + * Begin uses context.Background internally; to specify the context, use + * BeginTx. */ - setClientId(clientId: string): void + begin(): (Tx) + } + interface DB { /** - * ClientSecret returns the provider client's app secret. + * Driver returns the database's underlying driver. */ - clientSecret(): string + driver(): any + } + interface DB { /** - * SetClientSecret sets the provider client's app secret. + * Conn returns a single connection by either opening a new connection + * or returning an existing connection from the connection pool. Conn will + * block until either a connection is returned or ctx is canceled. + * Queries run on the same Conn will be run in the same database session. + * + * Every Conn must be returned to the database pool after use by + * calling Conn.Close. */ - setClientSecret(secret: string): void + conn(ctx: context.Context): (Conn) + } + /** + * Tx is an in-progress database transaction. + * + * A transaction must end with a call to Commit or Rollback. + * + * After a call to Commit or Rollback, all operations on the + * transaction fail with ErrTxDone. + * + * The statements prepared for a transaction by calling + * the transaction's Prepare or Stmt methods are closed + * by the call to Commit or Rollback. + */ + interface Tx { + } + interface Tx { /** - * RedirectUrl returns the end address to redirect the user - * going through the OAuth flow. + * Commit commits the transaction. */ - redirectUrl(): string + commit(): void + } + interface Tx { /** - * SetRedirectUrl sets the provider's RedirectUrl. + * Rollback aborts the transaction. */ - setRedirectUrl(url: string): void + rollback(): void + } + interface Tx { /** - * AuthUrl returns the provider's authorization service url. - */ - authUrl(): string - /** - * SetAuthUrl sets the provider's AuthUrl. + * PrepareContext creates a prepared statement for use within a transaction. + * + * The returned statement operates within the transaction and will be closed + * when the transaction has been committed or rolled back. + * + * To use an existing prepared statement on this transaction, see Tx.Stmt. + * + * The provided context will be used for the preparation of the context, not + * for the execution of the returned statement. The returned statement + * will run in the transaction context. */ - setAuthUrl(url: string): void + prepareContext(ctx: context.Context, query: string): (Stmt) + } + interface Tx { /** - * TokenUrl returns the provider's token exchange service url. + * Prepare creates a prepared statement for use within a transaction. + * + * The returned statement operates within the transaction and will be closed + * when the transaction has been committed or rolled back. + * + * To use an existing prepared statement on this transaction, see Tx.Stmt. + * + * Prepare uses context.Background internally; to specify the context, use + * PrepareContext. */ - tokenUrl(): string + prepare(query: string): (Stmt) + } + interface Tx { /** - * SetTokenUrl sets the provider's TokenUrl. + * StmtContext returns a transaction-specific prepared statement from + * an existing statement. + * + * Example: + * + * ``` + * updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") + * ... + * tx, err := db.Begin() + * ... + * res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203) + * ``` + * + * The provided context is used for the preparation of the statement, not for the + * execution of the statement. + * + * The returned statement operates within the transaction and will be closed + * when the transaction has been committed or rolled back. */ - setTokenUrl(url: string): void + stmtContext(ctx: context.Context, stmt: Stmt): (Stmt) + } + interface Tx { /** - * UserApiUrl returns the provider's user info api url. + * Stmt returns a transaction-specific prepared statement from + * an existing statement. + * + * Example: + * + * ``` + * updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?") + * ... + * tx, err := db.Begin() + * ... + * res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203) + * ``` + * + * The returned statement operates within the transaction and will be closed + * when the transaction has been committed or rolled back. + * + * Stmt uses context.Background internally; to specify the context, use + * StmtContext. */ - userApiUrl(): string + stmt(stmt: Stmt): (Stmt) + } + interface Tx { /** - * SetUserApiUrl sets the provider's UserApiUrl. + * ExecContext executes a query that doesn't return rows. + * For example: an INSERT and UPDATE. */ - setUserApiUrl(url: string): void + execContext(ctx: context.Context, query: string, ...args: any[]): Result + } + interface Tx { /** - * Client returns an http client using the provided token. + * Exec executes a query that doesn't return rows. + * For example: an INSERT and UPDATE. + * + * Exec uses context.Background internally; to specify the context, use + * ExecContext. */ - client(token: oauth2.Token): (any) + exec(query: string, ...args: any[]): Result + } + interface Tx { /** - * BuildAuthUrl returns a URL to the provider's consent page - * that asks for permissions for the required scopes explicitly. + * QueryContext executes a query that returns rows, typically a SELECT. */ - buildAuthUrl(state: string, ...opts: oauth2.AuthCodeOption[]): string + queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) + } + interface Tx { /** - * FetchToken converts an authorization code to token. + * Query executes a query that returns rows, typically a SELECT. + * + * Query uses context.Background internally; to specify the context, use + * QueryContext. */ - fetchToken(code: string, ...opts: oauth2.AuthCodeOption[]): (oauth2.Token) + query(query: string, ...args: any[]): (Rows) + } + interface Tx { /** - * FetchRawUserData requests and marshalizes into `result` the - * the OAuth user api response. + * QueryRowContext executes a query that is expected to return at most one row. + * QueryRowContext always returns a non-nil value. Errors are deferred until + * Row's Scan method is called. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. */ - fetchRawUserData(token: oauth2.Token): string|Array + queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) + } + interface Tx { /** - * FetchAuthUser is similar to FetchRawUserData, but normalizes and - * marshalizes the user api response into a standardized AuthUser struct. + * QueryRow executes a query that is expected to return at most one row. + * QueryRow always returns a non-nil value. Errors are deferred until + * Row's Scan method is called. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. + * + * QueryRow uses context.Background internally; to specify the context, use + * QueryRowContext. */ - fetchAuthUser(token: oauth2.Token): (AuthUser) + queryRow(query: string, ...args: any[]): (Row) } -} - -/** - * Package echo implements high performance, minimalist Go web framework. - * - * Example: - * - * ``` - * package main - * - * import ( - * "github.com/labstack/echo/v5" - * "github.com/labstack/echo/v5/middleware" - * "log" - * "net/http" - * ) - * - * // Handler - * func hello(c echo.Context) error { - * return c.String(http.StatusOK, "Hello, World!") - * } - * - * func main() { - * // Echo instance - * e := echo.New() - * - * // Middleware - * e.Use(middleware.Logger()) - * e.Use(middleware.Recover()) - * - * // Routes - * e.GET("/", hello) - * - * // Start server - * if err := e.Start(":8080"); err != http.ErrServerClosed { - * log.Fatal(err) - * } - * } - * ``` - * - * Learn more at https://echo.labstack.com - */ -namespace echo { /** - * Context represents the context of the current HTTP request. It holds request and - * response objects, path, path parameters, data and registered handler. + * Stmt is a prepared statement. + * A Stmt is safe for concurrent use by multiple goroutines. + * + * If a Stmt is prepared on a Tx or Conn, it will be bound to a single + * underlying connection forever. If the Tx or Conn closes, the Stmt will + * become unusable and all operations will return an error. + * If a Stmt is prepared on a DB, it will remain usable for the lifetime of the + * DB. When the Stmt needs to execute on a new underlying connection, it will + * prepare itself on the new connection automatically. */ - interface Context { - [key:string]: any; - /** - * Request returns `*http.Request`. - */ - request(): (http.Request) - /** - * SetRequest sets `*http.Request`. - */ - setRequest(r: http.Request): void - /** - * SetResponse sets `*Response`. - */ - setResponse(r: Response): void + interface Stmt { + } + interface Stmt { /** - * Response returns `*Response`. + * ExecContext executes a prepared statement with the given arguments and + * returns a Result summarizing the effect of the statement. */ - response(): (Response) + execContext(ctx: context.Context, ...args: any[]): Result + } + interface Stmt { /** - * IsTLS returns true if HTTP connection is TLS otherwise false. + * Exec executes a prepared statement with the given arguments and + * returns a Result summarizing the effect of the statement. + * + * Exec uses context.Background internally; to specify the context, use + * ExecContext. */ - isTLS(): boolean + exec(...args: any[]): Result + } + interface Stmt { /** - * IsWebSocket returns true if HTTP connection is WebSocket otherwise false. + * QueryContext executes a prepared query statement with the given arguments + * and returns the query results as a *Rows. */ - isWebSocket(): boolean + queryContext(ctx: context.Context, ...args: any[]): (Rows) + } + interface Stmt { /** - * Scheme returns the HTTP protocol scheme, `http` or `https`. + * Query executes a prepared query statement with the given arguments + * and returns the query results as a *Rows. + * + * Query uses context.Background internally; to specify the context, use + * QueryContext. */ - scheme(): string + query(...args: any[]): (Rows) + } + interface Stmt { /** - * RealIP returns the client's network address based on `X-Forwarded-For` - * or `X-Real-IP` request header. - * The behavior can be configured using `Echo#IPExtractor`. + * QueryRowContext executes a prepared query statement with the given arguments. + * If an error occurs during the execution of the statement, that error will + * be returned by a call to Scan on the returned *Row, which is always non-nil. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. */ - realIP(): string + queryRowContext(ctx: context.Context, ...args: any[]): (Row) + } + interface Stmt { /** - * RouteInfo returns current request route information. Method, Path, Name and params if they exist for matched route. - * In case of 404 (route not found) and 405 (method not allowed) RouteInfo returns generic struct for these cases. - */ - routeInfo(): RouteInfo - /** - * Path returns the registered path for the handler. - */ - path(): string - /** - * PathParam returns path parameter by name. - */ - pathParam(name: string): string - /** - * PathParamDefault returns the path parameter or default value for the provided name. + * QueryRow executes a prepared query statement with the given arguments. + * If an error occurs during the execution of the statement, that error will + * be returned by a call to Scan on the returned *Row, which is always non-nil. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. * - * Notes for DefaultRouter implementation: - * Path parameter could be empty for cases like that: - * * route `/release-:version/bin` and request URL is `/release-/bin` - * * route `/api/:version/image.jpg` and request URL is `/api//image.jpg` - * but not when path parameter is last part of route path - * * route `/download/file.:ext` will not match request `/download/file.` - */ - pathParamDefault(name: string, defaultValue: string): string - /** - * PathParams returns path parameter values. - */ - pathParams(): PathParams - /** - * SetPathParams sets path parameters for current request. + * Example usage: + * + * ``` + * var name string + * err := nameByUseridStmt.QueryRow(id).Scan(&name) + * ``` + * + * QueryRow uses context.Background internally; to specify the context, use + * QueryRowContext. */ - setPathParams(params: PathParams): void + queryRow(...args: any[]): (Row) + } + interface Stmt { /** - * QueryParam returns the query param for the provided name. + * Close closes the statement. */ - queryParam(name: string): string + close(): void + } + /** + * Rows is the result of a query. Its cursor starts before the first row + * of the result set. Use Next to advance from row to row. + */ + interface Rows { + } + interface Rows { /** - * QueryParamDefault returns the query param or default value for the provided name. + * Next prepares the next result row for reading with the Scan method. It + * returns true on success, or false if there is no next result row or an error + * happened while preparing it. Err should be consulted to distinguish between + * the two cases. + * + * Every call to Scan, even the first one, must be preceded by a call to Next. */ - queryParamDefault(name: string): string + next(): boolean + } + interface Rows { /** - * QueryParams returns the query parameters as `url.Values`. + * NextResultSet prepares the next result set for reading. It reports whether + * there is further result sets, or false if there is no further result set + * or if there is an error advancing to it. The Err method should be consulted + * to distinguish between the two cases. + * + * After calling NextResultSet, the Next method should always be called before + * scanning. If there are further result sets they may not have rows in the result + * set. */ - queryParams(): url.Values + nextResultSet(): boolean + } + interface Rows { /** - * QueryString returns the URL query string. + * Err returns the error, if any, that was encountered during iteration. + * Err may be called after an explicit or implicit Close. */ - queryString(): string + err(): void + } + interface Rows { /** - * FormValue returns the form field value for the provided name. + * Columns returns the column names. + * Columns returns an error if the rows are closed. */ - formValue(name: string): string + columns(): Array + } + interface Rows { /** - * FormValueDefault returns the form field value or default value for the provided name. + * ColumnTypes returns column information such as column type, length, + * and nullable. Some information may not be available from some drivers. */ - formValueDefault(name: string): string + columnTypes(): Array<(ColumnType | undefined)> + } + interface Rows { /** - * FormValues returns the form field values as `url.Values`. + * Scan copies the columns in the current row into the values pointed + * at by dest. The number of values in dest must be the same as the + * number of columns in Rows. + * + * Scan converts columns read from the database into the following + * common Go types and special types provided by the sql package: + * + * ``` + * *string + * *[]byte + * *int, *int8, *int16, *int32, *int64 + * *uint, *uint8, *uint16, *uint32, *uint64 + * *bool + * *float32, *float64 + * *interface{} + * *RawBytes + * *Rows (cursor value) + * any type implementing Scanner (see Scanner docs) + * ``` + * + * In the most simple case, if the type of the value from the source + * column is an integer, bool or string type T and dest is of type *T, + * Scan simply assigns the value through the pointer. + * + * Scan also converts between string and numeric types, as long as no + * information would be lost. While Scan stringifies all numbers + * scanned from numeric database columns into *string, scans into + * numeric types are checked for overflow. For example, a float64 with + * value 300 or a string with value "300" can scan into a uint16, but + * not into a uint8, though float64(255) or "255" can scan into a + * uint8. One exception is that scans of some float64 numbers to + * strings may lose information when stringifying. In general, scan + * floating point columns into *float64. + * + * If a dest argument has type *[]byte, Scan saves in that argument a + * copy of the corresponding data. The copy is owned by the caller and + * can be modified and held indefinitely. The copy can be avoided by + * using an argument of type *RawBytes instead; see the documentation + * for RawBytes for restrictions on its use. + * + * If an argument has type *interface{}, Scan copies the value + * provided by the underlying driver without conversion. When scanning + * from a source value of type []byte to *interface{}, a copy of the + * slice is made and the caller owns the result. + * + * Source values of type time.Time may be scanned into values of type + * *time.Time, *interface{}, *string, or *[]byte. When converting to + * the latter two, time.RFC3339Nano is used. + * + * Source values of type bool may be scanned into types *bool, + * *interface{}, *string, *[]byte, or *RawBytes. + * + * For scanning into *bool, the source may be true, false, 1, 0, or + * string inputs parseable by strconv.ParseBool. + * + * Scan can also convert a cursor returned from a query, such as + * "select cursor(select * from my_table) from dual", into a + * *Rows value that can itself be scanned from. The parent + * select query will close any cursor *Rows if the parent *Rows is closed. + * + * If any of the first arguments implementing Scanner returns an error, + * that error will be wrapped in the returned error. */ - formValues(): url.Values + scan(...dest: any[]): void + } + interface Rows { /** - * FormFile returns the multipart form file for the provided name. + * Close closes the Rows, preventing further enumeration. If Next is called + * and returns false and there are no further result sets, + * the Rows are closed automatically and it will suffice to check the + * result of Err. Close is idempotent and does not affect the result of Err. */ - formFile(name: string): (multipart.FileHeader) + close(): void + } + /** + * A Result summarizes an executed SQL command. + */ + interface Result { + [key:string]: any; /** - * MultipartForm returns the multipart form. + * LastInsertId returns the integer generated by the database + * in response to a command. Typically this will be from an + * "auto increment" column when inserting a new row. Not all + * databases support this feature, and the syntax of such + * statements varies. */ - multipartForm(): (multipart.Form) + lastInsertId(): number /** - * Cookie returns the named cookie provided in the request. + * RowsAffected returns the number of rows affected by an + * update, insert, or delete. Not every database or database + * driver may support this. */ - cookie(name: string): (http.Cookie) + rowsAffected(): number + } +} + +namespace migrate { + /** + * MigrationsList defines a list with migration definitions + */ + interface MigrationsList { + } + interface MigrationsList { /** - * SetCookie adds a `Set-Cookie` header in HTTP response. + * Item returns a single migration from the list by its index. */ - setCookie(cookie: http.Cookie): void + item(index: number): (Migration) + } + interface MigrationsList { /** - * Cookies returns the HTTP cookies sent with the request. + * Items returns the internal migrations list slice. */ - cookies(): Array<(http.Cookie | undefined)> + items(): Array<(Migration | undefined)> + } + interface MigrationsList { /** - * Get retrieves data from the context. + * Register adds new migration definition to the list. + * + * If `optFilename` is not provided, it will try to get the name from its .go file. + * + * The list will be sorted automatically based on the migrations file name. */ - get(key: string): { + register(up: (db: dbx.Builder) => void, down: (db: dbx.Builder) => void, ...optFilename: string[]): void } +} + +namespace settings { + // @ts-ignore + import validation = ozzo_validation + /** + * Settings defines common app configuration options. + */ + interface Settings { + meta: MetaConfig + logs: LogsConfig + smtp: SmtpConfig + s3: S3Config + backups: BackupsConfig + adminAuthToken: TokenConfig + adminPasswordResetToken: TokenConfig + adminFileToken: TokenConfig + recordAuthToken: TokenConfig + recordPasswordResetToken: TokenConfig + recordEmailChangeToken: TokenConfig + recordVerificationToken: TokenConfig + recordFileToken: TokenConfig /** - * Set saves data in the context. + * Deprecated: Will be removed in v0.9+ */ - set(key: string, val: { - }): void - /** - * Bind binds path params, query params and the request body into provided type `i`. The default binder - * binds body based on Content-Type header. - */ - bind(i: { - }): void + emailAuth: EmailAuthConfig + googleAuth: AuthProviderConfig + facebookAuth: AuthProviderConfig + githubAuth: AuthProviderConfig + gitlabAuth: AuthProviderConfig + discordAuth: AuthProviderConfig + twitterAuth: AuthProviderConfig + microsoftAuth: AuthProviderConfig + spotifyAuth: AuthProviderConfig + kakaoAuth: AuthProviderConfig + twitchAuth: AuthProviderConfig + stravaAuth: AuthProviderConfig + giteeAuth: AuthProviderConfig + livechatAuth: AuthProviderConfig + giteaAuth: AuthProviderConfig + oidcAuth: AuthProviderConfig + oidc2Auth: AuthProviderConfig + oidc3Auth: AuthProviderConfig + appleAuth: AuthProviderConfig + instagramAuth: AuthProviderConfig + vkAuth: AuthProviderConfig + yandexAuth: AuthProviderConfig + patreonAuth: AuthProviderConfig + mailcowAuth: AuthProviderConfig + } + interface Settings { /** - * Validate validates provided `i`. It is usually called after `Context#Bind()`. - * Validator must be registered using `Echo#Validator`. + * Validate makes Settings validatable by implementing [validation.Validatable] interface. */ - validate(i: { - }): void + validate(): void + } + interface Settings { /** - * Render renders a template with data and sends a text/html response with status - * code. Renderer must be registered using `Echo.Renderer`. + * Merge merges `other` settings into the current one. */ - render(code: number, name: string, data: { - }): void + merge(other: Settings): void + } + interface Settings { /** - * HTML sends an HTTP response with status code. + * Clone creates a new deep copy of the current settings. */ - html(code: number, html: string): void + clone(): (Settings) + } + interface Settings { /** - * HTMLBlob sends an HTTP blob response with status code. + * RedactClone creates a new deep copy of the current settings, + * while replacing the secret values with `******`. */ - htmlBlob(code: number, b: string|Array): void + redactClone(): (Settings) + } + interface Settings { /** - * String sends a string response with status code. + * NamedAuthProviderConfigs returns a map with all registered OAuth2 + * provider configurations (indexed by their name identifier). */ - string(code: number, s: string): void + namedAuthProviderConfigs(): _TygojaDict + } +} + +/** + * Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces. + * In addition to providing an interface, Cobra simultaneously provides a controller to organize your application code. + */ +namespace cobra { + interface Command { /** - * JSON sends a JSON response with status code. + * GenBashCompletion generates bash completion file and writes to the passed writer. */ - json(code: number, i: { - }): void + genBashCompletion(w: io.Writer): void + } + interface Command { /** - * JSONPretty sends a pretty-print JSON with status code. + * GenBashCompletionFile generates bash completion file. */ - jsonPretty(code: number, i: { - }, indent: string): void + genBashCompletionFile(filename: string): void + } + interface Command { /** - * JSONBlob sends a JSON blob response with status code. + * GenBashCompletionFileV2 generates Bash completion version 2. */ - jsonBlob(code: number, b: string|Array): void + genBashCompletionFileV2(filename: string, includeDesc: boolean): void + } + interface Command { /** - * JSONP sends a JSONP response with status code. It uses `callback` to construct - * the JSONP payload. + * GenBashCompletionV2 generates Bash completion file version 2 + * and writes it to the passed writer. */ - jsonp(code: number, callback: string, i: { - }): void + genBashCompletionV2(w: io.Writer, includeDesc: boolean): void + } + // @ts-ignore + import flag = pflag + /** + * Command is just that, a command for your application. + * E.g. 'go run ...' - 'run' is the command. Cobra requires + * you to define the usage and description as part of your command + * definition to ensure usability. + */ + interface Command { /** - * JSONPBlob sends a JSONP blob response with status code. It uses `callback` - * to construct the JSONP payload. + * Use is the one-line usage message. + * Recommended syntax is as follows: + * ``` + * [ ] identifies an optional argument. Arguments that are not enclosed in brackets are required. + * ... indicates that you can specify multiple values for the previous argument. + * | indicates mutually exclusive information. You can use the argument to the left of the separator or the + * argument to the right of the separator. You cannot use both arguments in a single use of the command. + * { } delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are + * optional, they are enclosed in brackets ([ ]). + * ``` + * Example: add [-F file | -D dir]... [-f format] profile */ - jsonpBlob(code: number, callback: string, b: string|Array): void + use: string /** - * XML sends an XML response with status code. + * Aliases is an array of aliases that can be used instead of the first word in Use. */ - xml(code: number, i: { - }): void + aliases: Array /** - * XMLPretty sends a pretty-print XML with status code. + * SuggestFor is an array of command names for which this command will be suggested - + * similar to aliases but only suggests. */ - xmlPretty(code: number, i: { - }, indent: string): void + suggestFor: Array /** - * XMLBlob sends an XML blob response with status code. + * Short is the short description shown in the 'help' output. */ - xmlBlob(code: number, b: string|Array): void + short: string /** - * Blob sends a blob response with status code and content type. + * The group id under which this subcommand is grouped in the 'help' output of its parent. */ - blob(code: number, contentType: string, b: string|Array): void + groupID: string /** - * Stream sends a streaming response with status code and content type. + * Long is the long message shown in the 'help ' output. */ - stream(code: number, contentType: string, r: io.Reader): void + long: string /** - * File sends a response with the content of the file. + * Example is examples of how to use the command. */ - file(file: string): void + example: string /** - * FileFS sends a response with the content of the file from given filesystem. + * ValidArgs is list of all valid non-flag arguments that are accepted in shell completions */ - fileFS(file: string, filesystem: fs.FS): void + validArgs: Array /** - * Attachment sends a response as attachment, prompting client to save the - * file. + * ValidArgsFunction is an optional function that provides valid non-flag arguments for shell completion. + * It is a dynamic version of using ValidArgs. + * Only one of ValidArgs and ValidArgsFunction can be used for a command. */ - attachment(file: string, name: string): void + validArgsFunction: (cmd: Command, args: Array, toComplete: string) => [Array, ShellCompDirective] /** - * Inline sends a response as inline, opening the file in the browser. + * Expected arguments */ - inline(file: string, name: string): void + args: PositionalArgs /** - * NoContent sends a response with no body and a status code. + * ArgAliases is List of aliases for ValidArgs. + * These are not suggested to the user in the shell completion, + * but accepted if entered manually. */ - noContent(code: number): void + argAliases: Array /** - * Redirect redirects the request to a provided URL with status code. + * BashCompletionFunction is custom bash functions used by the legacy bash autocompletion generator. + * For portability with other shells, it is recommended to instead use ValidArgsFunction */ - redirect(code: number, url: string): void + bashCompletionFunction: string /** - * Error invokes the registered global HTTP error handler. Generally used by middleware. - * A side-effect of calling global error handler is that now Response has been committed (sent to the client) and - * middlewares up in chain can not change Response status code or Response body anymore. - * - * Avoid using this method in handlers as no middleware will be able to effectively handle errors after that. - * Instead of calling this method in handler return your error and let it be handled by middlewares or global error handler. + * Deprecated defines, if this command is deprecated and should print this string when used. */ - error(err: Error): void + deprecated: string /** - * Echo returns the `Echo` instance. - * - * WARNING: Remember that Echo public fields and methods are coroutine safe ONLY when you are NOT mutating them - * anywhere in your code after Echo server has started. + * Annotations are key/value pairs that can be used by applications to identify or + * group commands or set special options. */ - echo(): (Echo) - } - // @ts-ignore - import stdContext = context - /** - * Echo is the top-level framework instance. - * - * Goroutine safety: Do not mutate Echo instance fields after server has started. Accessing these - * fields from handlers/middlewares and changing field values at the same time leads to data-races. - * Same rule applies to adding new routes after server has been started - Adding a route is not Goroutine safe action. - */ - interface Echo { + annotations: _TygojaDict /** - * NewContextFunc allows using custom context implementations, instead of default *echo.context + * Version defines the version for this command. If this value is non-empty and the command does not + * define a "version" flag, a "version" boolean flag will be added to the command and, if specified, + * will print content of the "Version" variable. A shorthand "v" flag will also be added if the + * command does not define one. */ - newContextFunc: (e: Echo, pathParamAllocSize: number) => ServableContext - debug: boolean - httpErrorHandler: HTTPErrorHandler - binder: Binder - jsonSerializer: JSONSerializer - validator: Validator - renderer: Renderer - logger: Logger - ipExtractor: IPExtractor + version: string /** - * Filesystem is file system used by Static and File handlers to access files. - * Defaults to os.DirFS(".") + * The *Run functions are executed in the following order: + * ``` + * * PersistentPreRun() + * * PreRun() + * * Run() + * * PostRun() + * * PersistentPostRun() + * ``` + * All functions get the same args, the arguments after the command name. + * The *PreRun and *PostRun functions will only be executed if the Run function of the current + * command has been declared. * - * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary - * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths - * including `assets/images` as their prefix. + * PersistentPreRun: children of this command will inherit and execute. */ - filesystem: fs.FS + persistentPreRun: (cmd: Command, args: Array) => void /** - * OnAddRoute is called when Echo adds new route to specific host router. Handler is called for every router - * and before route is added to the host router. + * PersistentPreRunE: PersistentPreRun but returns an error. */ - onAddRoute: (host: string, route: Routable) => void - } - /** - * HandlerFunc defines a function to serve HTTP requests. - */ - interface HandlerFunc {(c: Context): void } - /** - * MiddlewareFunc defines a function to process middleware. - */ - interface MiddlewareFunc {(next: HandlerFunc): HandlerFunc } - interface Echo { + persistentPreRunE: (cmd: Command, args: Array) => void /** - * NewContext returns a new Context instance. - * - * Note: both request and response can be left to nil as Echo.ServeHTTP will call c.Reset(req,resp) anyway - * these arguments are useful when creating context for tests and cases like that. + * PreRun: children of this command will not inherit. */ - newContext(r: http.Request, w: http.ResponseWriter): Context - } - interface Echo { + preRun: (cmd: Command, args: Array) => void /** - * Router returns the default router. + * PreRunE: PreRun but returns an error. */ - router(): Router - } - interface Echo { + preRunE: (cmd: Command, args: Array) => void /** - * Routers returns the new map of host => router. + * Run: Typically the actual work function. Most commands will only implement this. */ - routers(): _TygojaDict - } - interface Echo { + run: (cmd: Command, args: Array) => void /** - * RouterFor returns Router for given host. When host is left empty the default router is returned. + * RunE: Run but returns an error. */ - routerFor(host: string): [Router, boolean] - } - interface Echo { + runE: (cmd: Command, args: Array) => void /** - * ResetRouterCreator resets callback for creating new router instances. - * Note: current (default) router is immediately replaced with router created with creator func and vhost routers are cleared. + * PostRun: run after the Run command. */ - resetRouterCreator(creator: (e: Echo) => Router): void - } - interface Echo { + postRun: (cmd: Command, args: Array) => void /** - * Pre adds middleware to the chain which is run before router tries to find matching route. - * Meaning middleware is executed even for 404 (not found) cases. + * PostRunE: PostRun but returns an error. */ - pre(...middleware: MiddlewareFunc[]): void - } - interface Echo { + postRunE: (cmd: Command, args: Array) => void /** - * Use adds middleware to the chain which is run after router has found matching route and before route/request handler method is executed. + * PersistentPostRun: children of this command will inherit and execute after PostRun. */ - use(...middleware: MiddlewareFunc[]): void - } - interface Echo { + persistentPostRun: (cmd: Command, args: Array) => void /** - * CONNECT registers a new CONNECT route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * PersistentPostRunE: PersistentPostRun but returns an error. */ - connect(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Echo { + persistentPostRunE: (cmd: Command, args: Array) => void /** - * DELETE registers a new DELETE route for a path with matching handler in the router - * with optional route-level middleware. Panics on error. + * FParseErrWhitelist flag parse errors to be ignored */ - delete(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Echo { + fParseErrWhitelist: FParseErrWhitelist /** - * GET registers a new GET route for a path with matching handler in the router - * with optional route-level middleware. Panics on error. + * CompletionOptions is a set of options to control the handling of shell completion */ - get(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Echo { + completionOptions: CompletionOptions /** - * HEAD registers a new HEAD route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * TraverseChildren parses flags on all parents before executing child command. */ - head(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Echo { + traverseChildren: boolean /** - * OPTIONS registers a new OPTIONS route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * Hidden defines, if this command is hidden and should NOT show up in the list of available commands. */ - options(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Echo { + hidden: boolean /** - * PATCH registers a new PATCH route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * SilenceErrors is an option to quiet errors down stream. */ - patch(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + silenceErrors: boolean + /** + * SilenceUsage is an option to silence usage when an error occurs. + */ + silenceUsage: boolean + /** + * DisableFlagParsing disables the flag parsing. + * If this is true all flags will be passed to the command as arguments. + */ + disableFlagParsing: boolean + /** + * DisableAutoGenTag defines, if gen tag ("Auto generated by spf13/cobra...") + * will be printed by generating docs for this command. + */ + disableAutoGenTag: boolean + /** + * DisableFlagsInUseLine will disable the addition of [flags] to the usage + * line of a command when printing help or generating docs + */ + disableFlagsInUseLine: boolean + /** + * DisableSuggestions disables the suggestions based on Levenshtein distance + * that go along with 'unknown command' messages. + */ + disableSuggestions: boolean + /** + * SuggestionsMinimumDistance defines minimum levenshtein distance to display suggestions. + * Must be > 0. + */ + suggestionsMinimumDistance: number } - interface Echo { + interface Command { /** - * POST registers a new POST route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * Context returns underlying command context. If command was executed + * with ExecuteContext or the context was set with SetContext, the + * previously set context will be returned. Otherwise, nil is returned. + * + * Notice that a call to Execute and ExecuteC will replace a nil context of + * a command with a context.Background, so a background context will be + * returned by Context after one of these functions has been called. */ - post(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + context(): context.Context } - interface Echo { + interface Command { /** - * PUT registers a new PUT route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * SetContext sets context for the command. This context will be overwritten by + * Command.ExecuteContext or Command.ExecuteContextC. */ - put(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + setContext(ctx: context.Context): void } - interface Echo { + interface Command { /** - * TRACE registers a new TRACE route for a path with matching handler in the - * router with optional route-level middleware. Panics on error. + * SetArgs sets arguments for the command. It is set to os.Args[1:] by default, if desired, can be overridden + * particularly useful when testing. */ - trace(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + setArgs(a: Array): void } - interface Echo { + interface Command { /** - * RouteNotFound registers a special-case route which is executed when no other route is found (i.e. HTTP 404 cases) - * for current request URL. - * Path supports static and named/any parameters just like other http method is defined. Generally path is ended with - * wildcard/match-any character (`/*`, `/download/*` etc). - * - * Example: `e.RouteNotFound("/*", func(c echo.Context) error { return c.NoContent(http.StatusNotFound) })` + * SetOutput sets the destination for usage and error messages. + * If output is nil, os.Stderr is used. + * Deprecated: Use SetOut and/or SetErr instead */ - routeNotFound(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + setOutput(output: io.Writer): void } - interface Echo { + interface Command { /** - * Any registers a new route for all HTTP methods (supported by Echo) and path with matching handler - * in the router with optional route-level middleware. - * - * Note: this method only adds specific set of supported HTTP methods as handler and is not true - * "catch-any-arbitrary-method" way of matching requests. + * SetOut sets the destination for usage messages. + * If newOut is nil, os.Stdout is used. */ - any(path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes + setOut(newOut: io.Writer): void } - interface Echo { + interface Command { /** - * Match registers a new route for multiple HTTP methods and path with matching - * handler in the router with optional route-level middleware. Panics on error. + * SetErr sets the destination for error messages. + * If newErr is nil, os.Stderr is used. */ - match(methods: Array, path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes + setErr(newErr: io.Writer): void } - interface Echo { + interface Command { /** - * Static registers a new route with path prefix to serve static files from the provided root directory. + * SetIn sets the source for input data + * If newIn is nil, os.Stdin is used. */ - static(pathPrefix: string): RouteInfo + setIn(newIn: io.Reader): void } - interface Echo { + interface Command { /** - * StaticFS registers a new route with path prefix to serve static files from the provided file system. - * - * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary - * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths - * including `assets/images` as their prefix. + * SetUsageFunc sets usage function. Usage can be defined by application. */ - staticFS(pathPrefix: string, filesystem: fs.FS): RouteInfo + setUsageFunc(f: (_arg0: Command) => void): void } - interface Echo { + interface Command { /** - * FileFS registers a new route with path to serve file from the provided file system. + * SetUsageTemplate sets usage template. Can be defined by Application. */ - fileFS(path: string, filesystem: fs.FS, ...m: MiddlewareFunc[]): RouteInfo + setUsageTemplate(s: string): void } - interface Echo { + interface Command { /** - * File registers a new route with path to serve a static file with optional route-level middleware. Panics on error. + * SetFlagErrorFunc sets a function to generate an error when flag parsing + * fails. */ - file(path: string, ...middleware: MiddlewareFunc[]): RouteInfo + setFlagErrorFunc(f: (_arg0: Command, _arg1: Error) => void): void } - interface Echo { + interface Command { /** - * AddRoute registers a new Route with default host Router + * SetHelpFunc sets help function. Can be defined by Application. */ - addRoute(route: Routable): RouteInfo + setHelpFunc(f: (_arg0: Command, _arg1: Array) => void): void } - interface Echo { + interface Command { /** - * Add registers a new route for an HTTP method and path with matching handler - * in the router with optional route-level middleware. + * SetHelpCommand sets help command. */ - add(method: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): RouteInfo + setHelpCommand(cmd: Command): void } - interface Echo { + interface Command { /** - * Host creates a new router group for the provided host and optional host-level middleware. + * SetHelpCommandGroupID sets the group id of the help command. */ - host(name: string, ...m: MiddlewareFunc[]): (Group) + setHelpCommandGroupID(groupID: string): void } - interface Echo { + interface Command { /** - * Group creates a new router group with prefix and optional group-level middleware. + * SetCompletionCommandGroupID sets the group id of the completion command. */ - group(prefix: string, ...m: MiddlewareFunc[]): (Group) + setCompletionCommandGroupID(groupID: string): void } - interface Echo { + interface Command { /** - * AcquireContext returns an empty `Context` instance from the pool. - * You must return the context by calling `ReleaseContext()`. + * SetHelpTemplate sets help template to be used. Application can use it to set custom template. */ - acquireContext(): Context + setHelpTemplate(s: string): void } - interface Echo { + interface Command { /** - * ReleaseContext returns the `Context` instance back to the pool. - * You must call it after `AcquireContext()`. + * SetVersionTemplate sets version template to be used. Application can use it to set custom template. */ - releaseContext(c: Context): void + setVersionTemplate(s: string): void } - interface Echo { + interface Command { /** - * ServeHTTP implements `http.Handler` interface, which serves HTTP requests. + * SetErrPrefix sets error message prefix to be used. Application can use it to set custom prefix. */ - serveHTTP(w: http.ResponseWriter, r: http.Request): void + setErrPrefix(s: string): void } - interface Echo { + interface Command { /** - * Start stars HTTP server on given address with Echo as a handler serving requests. The server can be shutdown by - * sending os.Interrupt signal with `ctrl+c`. - * - * Note: this method is created for use in examples/demos and is deliberately simple without providing configuration - * options. - * - * In need of customization use: - * - * ``` - * sc := echo.StartConfig{Address: ":8080"} - * if err := sc.Start(e); err != http.ErrServerClosed { - * log.Fatal(err) - * } - * ``` - * - * // or standard library `http.Server` - * - * ``` - * s := http.Server{Addr: ":8080", Handler: e} - * if err := s.ListenAndServe(); err != http.ErrServerClosed { - * log.Fatal(err) - * } - * ``` + * SetGlobalNormalizationFunc sets a normalization function to all flag sets and also to child commands. + * The user should not have a cyclic dependency on commands. */ - start(address: string): void + setGlobalNormalizationFunc(n: (f: any, name: string) => any): void } -} - -namespace settings { - // @ts-ignore - import validation = ozzo_validation - /** - * Settings defines common app configuration options. - */ - interface Settings { - meta: MetaConfig - logs: LogsConfig - smtp: SmtpConfig - s3: S3Config - backups: BackupsConfig - adminAuthToken: TokenConfig - adminPasswordResetToken: TokenConfig - adminFileToken: TokenConfig - recordAuthToken: TokenConfig - recordPasswordResetToken: TokenConfig - recordEmailChangeToken: TokenConfig - recordVerificationToken: TokenConfig - recordFileToken: TokenConfig + interface Command { /** - * Deprecated: Will be removed in v0.9+ + * OutOrStdout returns output to stdout. */ - emailAuth: EmailAuthConfig - googleAuth: AuthProviderConfig - facebookAuth: AuthProviderConfig - githubAuth: AuthProviderConfig - gitlabAuth: AuthProviderConfig - discordAuth: AuthProviderConfig - twitterAuth: AuthProviderConfig - microsoftAuth: AuthProviderConfig - spotifyAuth: AuthProviderConfig - kakaoAuth: AuthProviderConfig - twitchAuth: AuthProviderConfig - stravaAuth: AuthProviderConfig - giteeAuth: AuthProviderConfig - livechatAuth: AuthProviderConfig - giteaAuth: AuthProviderConfig - oidcAuth: AuthProviderConfig - oidc2Auth: AuthProviderConfig - oidc3Auth: AuthProviderConfig - appleAuth: AuthProviderConfig - instagramAuth: AuthProviderConfig - vkAuth: AuthProviderConfig - yandexAuth: AuthProviderConfig - patreonAuth: AuthProviderConfig - mailcowAuth: AuthProviderConfig + outOrStdout(): io.Writer } - interface Settings { + interface Command { /** - * Validate makes Settings validatable by implementing [validation.Validatable] interface. + * OutOrStderr returns output to stderr */ - validate(): void + outOrStderr(): io.Writer } - interface Settings { + interface Command { /** - * Merge merges `other` settings into the current one. + * ErrOrStderr returns output to stderr */ - merge(other: Settings): void + errOrStderr(): io.Writer } - interface Settings { + interface Command { /** - * Clone creates a new deep copy of the current settings. + * InOrStdin returns input to stdin */ - clone(): (Settings) + inOrStdin(): io.Reader } - interface Settings { + interface Command { /** - * RedactClone creates a new deep copy of the current settings, - * while replacing the secret values with `******`. + * UsageFunc returns either the function set by SetUsageFunc for this command + * or a parent, or it returns a default usage function. */ - redactClone(): (Settings) + usageFunc(): (_arg0: Command) => void } - interface Settings { + interface Command { /** - * NamedAuthProviderConfigs returns a map with all registered OAuth2 - * provider configurations (indexed by their name identifier). + * Usage puts out the usage for the command. + * Used when a user provides invalid input. + * Can be defined by user by overriding UsageFunc. */ - namedAuthProviderConfigs(): _TygojaDict - } -} - -namespace migrate { - /** - * MigrationsList defines a list with migration definitions - */ - interface MigrationsList { + usage(): void } - interface MigrationsList { + interface Command { /** - * Item returns a single migration from the list by its index. + * HelpFunc returns either the function set by SetHelpFunc for this command + * or a parent, or it returns a function with default help behavior. */ - item(index: number): (Migration) + helpFunc(): (_arg0: Command, _arg1: Array) => void } - interface MigrationsList { + interface Command { /** - * Items returns the internal migrations list slice. + * Help puts out the help for the command. + * Used when a user calls help [command]. + * Can be defined by user by overriding HelpFunc. */ - items(): Array<(Migration | undefined)> + help(): void } - interface MigrationsList { + interface Command { /** - * Register adds new migration definition to the list. - * - * If `optFilename` is not provided, it will try to get the name from its .go file. - * - * The list will be sorted automatically based on the migrations file name. + * UsageString returns usage string. */ - register(up: (db: dbx.Builder) => void, down: (db: dbx.Builder) => void, ...optFilename: string[]): void + usageString(): string } -} - -/** - * Package daos handles common PocketBase DB model manipulations. - * - * Think of daos as DB repository and service layer in one. - */ -namespace daos { - interface Dao { + interface Command { /** - * AdminQuery returns a new Admin select query. + * FlagErrorFunc returns either the function set by SetFlagErrorFunc for this + * command or a parent, or it returns a function which returns the original + * error. */ - adminQuery(): (dbx.SelectQuery) + flagErrorFunc(): (_arg0: Command, _arg1: Error) => void } - interface Dao { + interface Command { /** - * FindAdminById finds the admin with the provided id. + * UsagePadding return padding for the usage. */ - findAdminById(id: string): (models.Admin) + usagePadding(): number } - interface Dao { + interface Command { /** - * FindAdminByEmail finds the admin with the provided email address. + * CommandPathPadding return padding for the command path. */ - findAdminByEmail(email: string): (models.Admin) + commandPathPadding(): number } - interface Dao { + interface Command { /** - * FindAdminByToken finds the admin associated with the provided JWT token. - * - * Returns an error if the JWT token is invalid or expired. + * NamePadding returns padding for the name. */ - findAdminByToken(token: string, baseTokenKey: string): (models.Admin) + namePadding(): number } - interface Dao { + interface Command { /** - * TotalAdmins returns the number of existing admin records. + * UsageTemplate returns usage template for the command. */ - totalAdmins(): number + usageTemplate(): string } - interface Dao { + interface Command { /** - * IsAdminEmailUnique checks if the provided email address is not - * already in use by other admins. + * HelpTemplate return help template for the command. */ - isAdminEmailUnique(email: string, ...excludeIds: string[]): boolean + helpTemplate(): string } - interface Dao { + interface Command { /** - * DeleteAdmin deletes the provided Admin model. - * - * Returns an error if there is only 1 admin. + * VersionTemplate return version template for the command. */ - deleteAdmin(admin: models.Admin): void + versionTemplate(): string } - interface Dao { + interface Command { /** - * SaveAdmin upserts the provided Admin model. + * ErrPrefix return error message prefix for the command */ - saveAdmin(admin: models.Admin): void + errPrefix(): string } - /** - * Dao handles various db operations. - * - * You can think of Dao as a repository and service layer in one. - */ - interface Dao { + interface Command { /** - * MaxLockRetries specifies the default max "database is locked" auto retry attempts. + * Find the target command given the args and command tree + * Meant to be run on the highest node. Only searches down. */ - maxLockRetries: number + find(args: Array): [(Command), Array] + } + interface Command { /** - * ModelQueryTimeout is the default max duration of a running ModelQuery(). - * - * This field has no effect if an explicit query context is already specified. + * Traverse the command tree to find the command, and parse args for + * each parent. */ - modelQueryTimeout: time.Duration + traverse(args: Array): [(Command), Array] + } + interface Command { /** - * write hooks + * SuggestionsFor provides suggestions for the typedName. */ - beforeCreateFunc: (eventDao: Dao, m: models.Model, action: () => void) => void - afterCreateFunc: (eventDao: Dao, m: models.Model) => void - beforeUpdateFunc: (eventDao: Dao, m: models.Model, action: () => void) => void - afterUpdateFunc: (eventDao: Dao, m: models.Model) => void - beforeDeleteFunc: (eventDao: Dao, m: models.Model, action: () => void) => void - afterDeleteFunc: (eventDao: Dao, m: models.Model) => void + suggestionsFor(typedName: string): Array } - interface Dao { + interface Command { /** - * DB returns the default dao db builder (*dbx.DB or *dbx.TX). - * - * Currently the default db builder is dao.concurrentDB but that may change in the future. + * VisitParents visits all parents of the command and invokes fn on each parent. */ - db(): dbx.Builder + visitParents(fn: (_arg0: Command) => void): void } - interface Dao { + interface Command { /** - * ConcurrentDB returns the dao concurrent (aka. multiple open connections) - * db builder (*dbx.DB or *dbx.TX). - * - * In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance. + * Root finds root command. */ - concurrentDB(): dbx.Builder + root(): (Command) } - interface Dao { + interface Command { /** - * NonconcurrentDB returns the dao nonconcurrent (aka. single open connection) - * db builder (*dbx.DB or *dbx.TX). - * - * In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance. + * ArgsLenAtDash will return the length of c.Flags().Args at the moment + * when a -- was found during args parsing. */ - nonconcurrentDB(): dbx.Builder + argsLenAtDash(): number } - interface Dao { + interface Command { /** - * Clone returns a new Dao with the same configuration options as the current one. + * ExecuteContext is the same as Execute(), but sets the ctx on the command. + * Retrieve ctx by calling cmd.Context() inside your *Run lifecycle or ValidArgs + * functions. */ - clone(): (Dao) + executeContext(ctx: context.Context): void } - interface Dao { + interface Command { /** - * WithoutHooks returns a new Dao with the same configuration options - * as the current one, but without create/update/delete hooks. + * Execute uses the args (os.Args[1:] by default) + * and run through the command tree finding appropriate matches + * for commands and then corresponding flags. */ - withoutHooks(): (Dao) + execute(): void } - interface Dao { + interface Command { /** - * ModelQuery creates a new preconfigured select query with preset - * SELECT, FROM and other common fields based on the provided model. + * ExecuteContextC is the same as ExecuteC(), but sets the ctx on the command. + * Retrieve ctx by calling cmd.Context() inside your *Run lifecycle or ValidArgs + * functions. */ - modelQuery(m: models.Model): (dbx.SelectQuery) + executeContextC(ctx: context.Context): (Command) } - interface Dao { + interface Command { /** - * FindById finds a single db record with the specified id and - * scans the result into m. + * ExecuteC executes the command. */ - findById(m: models.Model, id: string): void + executeC(): (Command) } - interface Dao { + interface Command { + validateArgs(args: Array): void + } + interface Command { /** - * RunInTransaction wraps fn into a transaction. - * - * It is safe to nest RunInTransaction calls as long as you use the txDao. + * ValidateRequiredFlags validates all required flags are present and returns an error otherwise */ - runInTransaction(fn: (txDao: Dao) => void): void + validateRequiredFlags(): void } - interface Dao { + interface Command { /** - * Delete deletes the provided model. + * InitDefaultHelpFlag adds default help flag to c. + * It is called automatically by executing the c or by calling help and usage. + * If c already has help flag, it will do nothing. */ - delete(m: models.Model): void + initDefaultHelpFlag(): void } - interface Dao { + interface Command { /** - * Save persists the provided model in the database. - * - * If m.IsNew() is true, the method will perform a create, otherwise an update. - * To explicitly mark a model for update you can use m.MarkAsNotNew(). + * InitDefaultVersionFlag adds default version flag to c. + * It is called automatically by executing the c. + * If c already has a version flag, it will do nothing. + * If c.Version is empty, it will do nothing. */ - save(m: models.Model): void + initDefaultVersionFlag(): void } - interface Dao { + interface Command { /** - * CollectionQuery returns a new Collection select query. + * InitDefaultHelpCmd adds default help command to c. + * It is called automatically by executing the c or by calling help and usage. + * If c already has help command or c has no subcommands, it will do nothing. */ - collectionQuery(): (dbx.SelectQuery) + initDefaultHelpCmd(): void } - interface Dao { + interface Command { /** - * FindCollectionsByType finds all collections by the given type. + * ResetCommands delete parent, subcommand and help command from c. */ - findCollectionsByType(collectionType: string): Array<(models.Collection | undefined)> + resetCommands(): void } - interface Dao { + interface Command { /** - * FindCollectionByNameOrId finds a single collection by its name (case insensitive) or id. + * Commands returns a sorted slice of child commands. */ - findCollectionByNameOrId(nameOrId: string): (models.Collection) + commands(): Array<(Command | undefined)> } - interface Dao { + interface Command { /** - * IsCollectionNameUnique checks that there is no existing collection - * with the provided name (case insensitive!). - * - * Note: case insensitive check because the name is used also as a table name for the records. + * AddCommand adds one or more commands to this parent command. */ - isCollectionNameUnique(name: string, ...excludeIds: string[]): boolean + addCommand(...cmds: (Command | undefined)[]): void } - interface Dao { + interface Command { /** - * FindCollectionReferences returns information for all - * relation schema fields referencing the provided collection. - * - * If the provided collection has reference to itself then it will be - * also included in the result. To exclude it, pass the collection id - * as the excludeId argument. + * Groups returns a slice of child command groups. */ - findCollectionReferences(collection: models.Collection, ...excludeIds: string[]): _TygojaDict + groups(): Array<(Group | undefined)> } - interface Dao { + interface Command { /** - * DeleteCollection deletes the provided Collection model. - * This method automatically deletes the related collection records table. - * - * NB! The collection cannot be deleted, if: - * - is system collection (aka. collection.System is true) - * - is referenced as part of a relation field in another collection + * AllChildCommandsHaveGroup returns if all subcommands are assigned to a group */ - deleteCollection(collection: models.Collection): void + allChildCommandsHaveGroup(): boolean } - interface Dao { + interface Command { /** - * SaveCollection persists the provided Collection model and updates - * its related records table schema. - * - * If collecction.IsNew() is true, the method will perform a create, otherwise an update. - * To explicitly mark a collection for update you can use collecction.MarkAsNotNew(). + * ContainsGroup return if groupID exists in the list of command groups. */ - saveCollection(collection: models.Collection): void + containsGroup(groupID: string): boolean } - interface Dao { + interface Command { /** - * ImportCollections imports the provided collections list within a single transaction. - * - * NB1! If deleteMissing is set, all local collections and schema fields, that are not present - * in the imported configuration, WILL BE DELETED (including their related records data). - * - * NB2! This method doesn't perform validations on the imported collections data! - * If you need validations, use [forms.CollectionsImport]. + * AddGroup adds one or more command groups to this parent command. */ - importCollections(importedCollections: Array<(models.Collection | undefined)>, deleteMissing: boolean, afterSync: (txDao: Dao, mappedImported: _TygojaDict) => void): void + addGroup(...groups: (Group | undefined)[]): void } - interface Dao { + interface Command { /** - * ExternalAuthQuery returns a new ExternalAuth select query. + * RemoveCommand removes one or more commands from a parent command. */ - externalAuthQuery(): (dbx.SelectQuery) + removeCommand(...cmds: (Command | undefined)[]): void } - interface Dao { + interface Command { /** - * FindAllExternalAuthsByRecord returns all ExternalAuth models - * linked to the provided auth record. + * Print is a convenience method to Print to the defined output, fallback to Stderr if not set. */ - findAllExternalAuthsByRecord(authRecord: models.Record): Array<(models.ExternalAuth | undefined)> + print(...i: { + }[]): void } - interface Dao { + interface Command { /** - * FindExternalAuthByRecordAndProvider returns the first available - * ExternalAuth model for the specified record data and provider. + * Println is a convenience method to Println to the defined output, fallback to Stderr if not set. */ - findExternalAuthByRecordAndProvider(authRecord: models.Record, provider: string): (models.ExternalAuth) + println(...i: { + }[]): void } - interface Dao { + interface Command { /** - * FindFirstExternalAuthByExpr returns the first available - * ExternalAuth model that satisfies the non-nil expression. + * Printf is a convenience method to Printf to the defined output, fallback to Stderr if not set. */ - findFirstExternalAuthByExpr(expr: dbx.Expression): (models.ExternalAuth) + printf(format: string, ...i: { + }[]): void } - interface Dao { + interface Command { /** - * SaveExternalAuth upserts the provided ExternalAuth model. + * PrintErr is a convenience method to Print to the defined Err output, fallback to Stderr if not set. */ - saveExternalAuth(model: models.ExternalAuth): void + printErr(...i: { + }[]): void } - interface Dao { + interface Command { /** - * DeleteExternalAuth deletes the provided ExternalAuth model. + * PrintErrln is a convenience method to Println to the defined Err output, fallback to Stderr if not set. */ - deleteExternalAuth(model: models.ExternalAuth): void + printErrln(...i: { + }[]): void } - interface Dao { + interface Command { /** - * LogQuery returns a new Log select query. + * PrintErrf is a convenience method to Printf to the defined Err output, fallback to Stderr if not set. */ - logQuery(): (dbx.SelectQuery) + printErrf(format: string, ...i: { + }[]): void } - interface Dao { + interface Command { /** - * FindLogById finds a single Log entry by its id. + * CommandPath returns the full path to this command. */ - findLogById(id: string): (models.Log) + commandPath(): string } - interface Dao { + interface Command { /** - * LogsStats returns hourly grouped requests logs statistics. + * UseLine puts out the full usage for a given command (including parents). */ - logsStats(expr: dbx.Expression): Array<(LogsStatsItem | undefined)> + useLine(): string } - interface Dao { + interface Command { /** - * DeleteOldLogs delete all requests that are created before createdBefore. + * DebugFlags used to determine which flags have been assigned to which commands + * and which persist. + * nolint:goconst */ - deleteOldLogs(createdBefore: time.Time): void + debugFlags(): void } - interface Dao { + interface Command { /** - * SaveLog upserts the provided Log model. + * Name returns the command's name: the first word in the use line. */ - saveLog(log: models.Log): void + name(): string } - interface Dao { + interface Command { /** - * ParamQuery returns a new Param select query. + * HasAlias determines if a given string is an alias of the command. */ - paramQuery(): (dbx.SelectQuery) + hasAlias(s: string): boolean } - interface Dao { + interface Command { /** - * FindParamByKey finds the first Param model with the provided key. + * CalledAs returns the command name or alias that was used to invoke + * this command or an empty string if the command has not been called. */ - findParamByKey(key: string): (models.Param) + calledAs(): string } - interface Dao { + interface Command { /** - * SaveParam creates or updates a Param model by the provided key-value pair. - * The value argument will be encoded as json string. - * - * If `optEncryptionKey` is provided it will encrypt the value before storing it. + * NameAndAliases returns a list of the command name and all aliases */ - saveParam(key: string, value: any, ...optEncryptionKey: string[]): void + nameAndAliases(): string } - interface Dao { + interface Command { /** - * DeleteParam deletes the provided Param model. + * HasExample determines if the command has example. */ - deleteParam(param: models.Param): void + hasExample(): boolean } - interface Dao { + interface Command { /** - * RecordQuery returns a new Record select query from a collection model, id or name. - * - * In case a collection id or name is provided and that collection doesn't - * actually exists, the generated query will be created with a cancelled context - * and will fail once an executor (Row(), One(), All(), etc.) is called. + * Runnable determines if the command is itself runnable. */ - recordQuery(collectionModelOrIdentifier: any): (dbx.SelectQuery) + runnable(): boolean } - interface Dao { + interface Command { /** - * FindRecordById finds the Record model by its id. + * HasSubCommands determines if the command has children commands. */ - findRecordById(collectionNameOrId: string, recordId: string, ...optFilters: ((q: dbx.SelectQuery) => void)[]): (models.Record) + hasSubCommands(): boolean } - interface Dao { + interface Command { /** - * FindRecordsByIds finds all Record models by the provided ids. - * If no records are found, returns an empty slice. + * IsAvailableCommand determines if a command is available as a non-help command + * (this includes all non deprecated/hidden commands). */ - findRecordsByIds(collectionNameOrId: string, recordIds: Array, ...optFilters: ((q: dbx.SelectQuery) => void)[]): Array<(models.Record | undefined)> + isAvailableCommand(): boolean } - interface Dao { + interface Command { /** - * @todo consider to depricate as it may be easier to just use dao.RecordQuery() - * - * FindRecordsByExpr finds all records by the specified db expression. - * - * Returns all collection records if no expressions are provided. - * - * Returns an empty slice if no records are found. - * - * Example: - * - * ``` - * expr1 := dbx.HashExp{"email": "test@example.com"} - * expr2 := dbx.NewExp("LOWER(username) = {:username}", dbx.Params{"username": "test"}) - * dao.FindRecordsByExpr("example", expr1, expr2) - * ``` + * IsAdditionalHelpTopicCommand determines if a command is an additional + * help topic command; additional help topic command is determined by the + * fact that it is NOT runnable/hidden/deprecated, and has no sub commands that + * are runnable/hidden/deprecated. + * Concrete example: https://github.com/spf13/cobra/issues/393#issuecomment-282741924. */ - findRecordsByExpr(collectionNameOrId: string, ...exprs: dbx.Expression[]): Array<(models.Record | undefined)> + isAdditionalHelpTopicCommand(): boolean } - interface Dao { + interface Command { /** - * FindFirstRecordByData returns the first found record matching - * the provided key-value pair. + * HasHelpSubCommands determines if a command has any available 'help' sub commands + * that need to be shown in the usage/help default template under 'additional help + * topics'. */ - findFirstRecordByData(collectionNameOrId: string, key: string, value: any): (models.Record) + hasHelpSubCommands(): boolean } - interface Dao { + interface Command { /** - * FindRecordsByFilter returns limit number of records matching the - * provided string filter. - * - * NB! Use the last "params" argument to bind untrusted user variables! - * - * The sort argument is optional and can be empty string OR the same format - * used in the web APIs, eg. "-created,title". - * - * If the limit argument is <= 0, no limit is applied to the query and - * all matching records are returned. - * - * Example: - * - * ``` - * dao.FindRecordsByFilter( - * "posts", - * "title ~ {:title} && visible = {:visible}", - * "-created", - * 10, - * 0, - * dbx.Params{"title": "lorem ipsum", "visible": true} - * ) - * ``` + * HasAvailableSubCommands determines if a command has available sub commands that + * need to be shown in the usage/help default template under 'available commands'. */ - findRecordsByFilter(collectionNameOrId: string, filter: string, sort: string, limit: number, offset: number, ...params: dbx.Params[]): Array<(models.Record | undefined)> + hasAvailableSubCommands(): boolean } - interface Dao { + interface Command { /** - * FindFirstRecordByFilter returns the first available record matching the provided filter. - * - * NB! Use the last params argument to bind untrusted user variables! - * - * Example: - * - * ``` - * dao.FindFirstRecordByFilter("posts", "slug={:slug} && status='public'", dbx.Params{"slug": "test"}) - * ``` + * HasParent determines if the command is a child command. */ - findFirstRecordByFilter(collectionNameOrId: string, filter: string, ...params: dbx.Params[]): (models.Record) + hasParent(): boolean } - interface Dao { + interface Command { /** - * IsRecordValueUnique checks if the provided key-value pair is a unique Record value. - * - * For correctness, if the collection is "auth" and the key is "username", - * the unique check will be case insensitive. - * - * NB! Array values (eg. from multiple select fields) are matched - * as a serialized json strings (eg. `["a","b"]`), so the value uniqueness - * depends on the elements order. Or in other words the following values - * are considered different: `[]string{"a","b"}` and `[]string{"b","a"}` + * GlobalNormalizationFunc returns the global normalization function or nil if it doesn't exist. */ - isRecordValueUnique(collectionNameOrId: string, key: string, value: any, ...excludeIds: string[]): boolean + globalNormalizationFunc(): (f: any, name: string) => any } - interface Dao { + interface Command { /** - * FindAuthRecordByToken finds the auth record associated with the provided JWT token. - * - * Returns an error if the JWT token is invalid, expired or not associated to an auth collection record. + * Flags returns the complete FlagSet that applies + * to this command (local and persistent declared here and by all parents). */ - findAuthRecordByToken(token: string, baseTokenKey: string): (models.Record) + flags(): (any) } - interface Dao { + interface Command { /** - * FindAuthRecordByEmail finds the auth record associated with the provided email. - * - * Returns an error if it is not an auth collection or the record is not found. + * LocalNonPersistentFlags are flags specific to this command which will NOT persist to subcommands. */ - findAuthRecordByEmail(collectionNameOrId: string, email: string): (models.Record) + localNonPersistentFlags(): (any) } - interface Dao { + interface Command { /** - * FindAuthRecordByUsername finds the auth record associated with the provided username (case insensitive). - * - * Returns an error if it is not an auth collection or the record is not found. + * LocalFlags returns the local FlagSet specifically set in the current command. */ - findAuthRecordByUsername(collectionNameOrId: string, username: string): (models.Record) + localFlags(): (any) } - interface Dao { + interface Command { /** - * SuggestUniqueAuthRecordUsername checks if the provided username is unique - * and return a new "unique" username with appended random numeric part - * (eg. "existingName" -> "existingName583"). - * - * The same username will be returned if the provided string is already unique. + * InheritedFlags returns all flags which were inherited from parent commands. */ - suggestUniqueAuthRecordUsername(collectionNameOrId: string, baseUsername: string, ...excludeIds: string[]): string + inheritedFlags(): (any) } - interface Dao { + interface Command { /** - * CanAccessRecord checks if a record is allowed to be accessed by the - * specified requestInfo and accessRule. - * - * Rule and db checks are ignored in case requestInfo.Admin is set. - * - * The returned error indicate that something unexpected happened during - * the check (eg. invalid rule or db error). - * - * The method always return false on invalid access rule or db error. - * - * Example: - * - * ``` - * requestInfo := apis.RequestInfo(c /* echo.Context *\/) - * record, _ := dao.FindRecordById("example", "RECORD_ID") - * rule := types.Pointer("@request.auth.id != '' || status = 'public'") - * // ... or use one of the record collection's rule, eg. record.Collection().ViewRule - * - * if ok, _ := dao.CanAccessRecord(record, requestInfo, rule); ok { ... } - * ``` + * NonInheritedFlags returns all flags which were not inherited from parent commands. */ - canAccessRecord(record: models.Record, requestInfo: models.RequestInfo, accessRule: string): boolean + nonInheritedFlags(): (any) } - interface Dao { + interface Command { /** - * SaveRecord persists the provided Record model in the database. - * - * If record.IsNew() is true, the method will perform a create, otherwise an update. - * To explicitly mark a record for update you can use record.MarkAsNotNew(). + * PersistentFlags returns the persistent FlagSet specifically set in the current command. */ - saveRecord(record: models.Record): void + persistentFlags(): (any) } - interface Dao { + interface Command { /** - * DeleteRecord deletes the provided Record model. - * - * This method will also cascade the delete operation to all linked - * relational records (delete or unset, depending on the rel settings). - * - * The delete operation may fail if the record is part of a required - * reference in another record (aka. cannot be deleted or unset). + * ResetFlags deletes all flags from command. */ - deleteRecord(record: models.Record): void + resetFlags(): void } - interface Dao { + interface Command { /** - * ExpandRecord expands the relations of a single Record model. - * - * If optFetchFunc is not set, then a default function will be used - * that returns all relation records. - * - * Returns a map with the failed expand parameters and their errors. + * HasFlags checks if the command contains any flags (local plus persistent from the entire structure). */ - expandRecord(record: models.Record, expands: Array, optFetchFunc: ExpandFetchFunc): _TygojaDict + hasFlags(): boolean } - interface Dao { + interface Command { /** - * ExpandRecords expands the relations of the provided Record models list. - * - * If optFetchFunc is not set, then a default function will be used - * that returns all relation records. - * - * Returns a map with the failed expand parameters and their errors. + * HasPersistentFlags checks if the command contains persistent flags. */ - expandRecords(records: Array<(models.Record | undefined)>, expands: Array, optFetchFunc: ExpandFetchFunc): _TygojaDict + hasPersistentFlags(): boolean } - // @ts-ignore - import validation = ozzo_validation - interface Dao { + interface Command { /** - * SyncRecordTableSchema compares the two provided collections - * and applies the necessary related record table changes. - * - * If `oldCollection` is null, then only `newCollection` is used to create the record table. + * HasLocalFlags checks if the command has flags specifically declared locally. */ - syncRecordTableSchema(newCollection: models.Collection, oldCollection: models.Collection): void + hasLocalFlags(): boolean } - interface Dao { + interface Command { /** - * FindSettings returns and decode the serialized app settings param value. - * - * The method will first try to decode the param value without decryption. - * If it fails and optEncryptionKey is set, it will try again by first - * decrypting the value and then decode it again. - * - * Returns an error if it fails to decode the stored serialized param value. + * HasInheritedFlags checks if the command has flags inherited from its parent command. */ - findSettings(...optEncryptionKey: string[]): (settings.Settings) + hasInheritedFlags(): boolean } - interface Dao { + interface Command { /** - * SaveSettings persists the specified settings configuration. - * - * If optEncryptionKey is set, then the stored serialized value will be encrypted with it. + * HasAvailableFlags checks if the command contains any flags (local plus persistent from the entire + * structure) which are not hidden or deprecated. */ - saveSettings(newSettings: settings.Settings, ...optEncryptionKey: string[]): void + hasAvailableFlags(): boolean } - interface Dao { + interface Command { /** - * HasTable checks if a table (or view) with the provided name exists (case insensitive). + * HasAvailablePersistentFlags checks if the command contains persistent flags which are not hidden or deprecated. */ - hasTable(tableName: string): boolean + hasAvailablePersistentFlags(): boolean } - interface Dao { + interface Command { /** - * TableColumns returns all column names of a single table by its name. + * HasAvailableLocalFlags checks if the command has flags specifically declared locally which are not hidden + * or deprecated. */ - tableColumns(tableName: string): Array + hasAvailableLocalFlags(): boolean } - interface Dao { + interface Command { /** - * TableInfo returns the `table_info` pragma result for the specified table. + * HasAvailableInheritedFlags checks if the command has flags inherited from its parent command which are + * not hidden or deprecated. */ - tableInfo(tableName: string): Array<(models.TableInfoRow | undefined)> + hasAvailableInheritedFlags(): boolean } - interface Dao { + interface Command { /** - * TableIndexes returns a name grouped map with all non empty index of the specified table. - * - * Note: This method doesn't return an error on nonexisting table. + * Flag climbs up the command tree looking for matching flag. */ - tableIndexes(tableName: string): _TygojaDict + flag(name: string): (any) } - interface Dao { + interface Command { /** - * DeleteTable drops the specified table. - * - * This method is a no-op if a table with the provided name doesn't exist. - * - * Be aware that this method is vulnerable to SQL injection and the - * "tableName" argument must come only from trusted input! + * ParseFlags parses persistent flag tree and local flags. */ - deleteTable(tableName: string): void + parseFlags(args: Array): void } - interface Dao { + interface Command { /** - * Vacuum executes VACUUM on the current dao.DB() instance in order to - * reclaim unused db disk space. + * Parent returns a commands parent command. */ - vacuum(): void + parent(): (Command) } - interface Dao { + interface Command { /** - * DeleteView drops the specified view name. - * - * This method is a no-op if a view with the provided name doesn't exist. - * - * Be aware that this method is vulnerable to SQL injection and the - * "name" argument must come only from trusted input! + * RegisterFlagCompletionFunc should be called to register a function to provide completion for a flag. */ - deleteView(name: string): void + registerFlagCompletionFunc(flagName: string, f: (cmd: Command, args: Array, toComplete: string) => [Array, ShellCompDirective]): void } - interface Dao { + interface Command { /** - * SaveView creates (or updates already existing) persistent SQL view. - * - * Be aware that this method is vulnerable to SQL injection and the - * "selectQuery" argument must come only from trusted input! + * GetFlagCompletionFunc returns the completion function for the given flag of the command, if available. */ - saveView(name: string, selectQuery: string): void + getFlagCompletionFunc(flagName: string): [(_arg0: Command, _arg1: Array, _arg2: string) => [Array, ShellCompDirective], boolean] } - interface Dao { + interface Command { /** - * CreateViewSchema creates a new view schema from the provided select query. - * - * There are some caveats: - * - The select query must have an "id" column. - * - Wildcard ("*") columns are not supported to avoid accidentally leaking sensitive data. + * InitDefaultCompletionCmd adds a default 'completion' command to c. + * This function will do nothing if any of the following is true: + * 1- the feature has been explicitly disabled by the program, + * 2- c has no subcommands (to avoid creating one), + * 3- c already has a 'completion' command provided by the program. */ - createViewSchema(selectQuery: string): schema.Schema + initDefaultCompletionCmd(): void } - interface Dao { + interface Command { /** - * FindRecordByViewFile returns the original models.Record of the - * provided view collection file. + * GenFishCompletion generates fish completion file and writes to the passed writer. */ - findRecordByViewFile(viewCollectionNameOrId: string, fileFieldName: string, filename: string): (models.Record) + genFishCompletion(w: io.Writer, includeDesc: boolean): void } -} - -/** - * Package core is the backbone of PocketBase. - * - * It defines the main PocketBase App interface and its base implementation. - */ -namespace core { - /** - * App defines the main PocketBase app interface. - */ - interface App { - [key:string]: any; + interface Command { /** - * Deprecated: - * This method may get removed in the near future. - * It is recommended to access the app db instance from app.Dao().DB() or - * if you want more flexibility - app.Dao().ConcurrentDB() and app.Dao().NonconcurrentDB(). - * - * DB returns the default app database instance. + * GenFishCompletionFile generates fish completion file. */ - db(): (dbx.DB) + genFishCompletionFile(filename: string, includeDesc: boolean): void + } + interface Command { /** - * Dao returns the default app Dao instance. - * - * This Dao could operate only on the tables and models - * associated with the default app database. For example, - * trying to access the request logs table will result in error. + * MarkFlagsRequiredTogether marks the given flags with annotations so that Cobra errors + * if the command is invoked with a subset (but not all) of the given flags. */ - dao(): (daos.Dao) + markFlagsRequiredTogether(...flagNames: string[]): void + } + interface Command { /** - * Deprecated: - * This method may get removed in the near future. - * It is recommended to access the logs db instance from app.LogsDao().DB() or - * if you want more flexibility - app.LogsDao().ConcurrentDB() and app.LogsDao().NonconcurrentDB(). - * - * LogsDB returns the app logs database instance. + * MarkFlagsOneRequired marks the given flags with annotations so that Cobra errors + * if the command is invoked without at least one flag from the given set of flags. */ - logsDB(): (dbx.DB) + markFlagsOneRequired(...flagNames: string[]): void + } + interface Command { /** - * LogsDao returns the app logs Dao instance. - * - * This Dao could operate only on the tables and models - * associated with the logs database. For example, trying to access - * the users table from LogsDao will result in error. + * MarkFlagsMutuallyExclusive marks the given flags with annotations so that Cobra errors + * if the command is invoked with more than one flag from the given set of flags. */ - logsDao(): (daos.Dao) + markFlagsMutuallyExclusive(...flagNames: string[]): void + } + interface Command { /** - * Logger returns the active app logger. + * ValidateFlagGroups validates the mutuallyExclusive/oneRequired/requiredAsGroup logic and returns the + * first error encountered. */ - logger(): (slog.Logger) + validateFlagGroups(): void + } + interface Command { /** - * DataDir returns the app data directory path. + * GenPowerShellCompletionFile generates powershell completion file without descriptions. */ - dataDir(): string + genPowerShellCompletionFile(filename: string): void + } + interface Command { /** - * EncryptionEnv returns the name of the app secret env key - * (used for settings encryption). + * GenPowerShellCompletion generates powershell completion file without descriptions + * and writes it to the passed writer. */ - encryptionEnv(): string + genPowerShellCompletion(w: io.Writer): void + } + interface Command { /** - * Settings returns the loaded app settings. + * GenPowerShellCompletionFileWithDesc generates powershell completion file with descriptions. */ - settings(): (settings.Settings) + genPowerShellCompletionFileWithDesc(filename: string): void + } + interface Command { /** - * Deprecated: Use app.Store() instead. + * GenPowerShellCompletionWithDesc generates powershell completion file with descriptions + * and writes it to the passed writer. */ - cache(): (store.Store) + genPowerShellCompletionWithDesc(w: io.Writer): void + } + interface Command { /** - * Store returns the app runtime store. + * MarkFlagRequired instructs the various shell completion implementations to + * prioritize the named flag when performing completion, + * and causes your command to report an error if invoked without the flag. */ - store(): (store.Store) + markFlagRequired(name: string): void + } + interface Command { /** - * SubscriptionsBroker returns the app realtime subscriptions broker instance. + * MarkPersistentFlagRequired instructs the various shell completion implementations to + * prioritize the named persistent flag when performing completion, + * and causes your command to report an error if invoked without the flag. */ - subscriptionsBroker(): (subscriptions.Broker) + markPersistentFlagRequired(name: string): void + } + interface Command { /** - * NewMailClient creates and returns a configured app mail client. + * MarkFlagFilename instructs the various shell completion implementations to + * limit completions for the named flag to the specified file extensions. */ - newMailClient(): mailer.Mailer + markFlagFilename(name: string, ...extensions: string[]): void + } + interface Command { /** - * NewFilesystem creates and returns a configured filesystem.System instance - * for managing regular app files (eg. collection uploads). + * MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists. + * The bash completion script will call the bash function f for the flag. * - * NB! Make sure to call Close() on the returned result - * after you are done working with it. + * This will only work for bash completion. + * It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows + * to register a Go function which will work across all shells. */ - newFilesystem(): (filesystem.System) + markFlagCustom(name: string, f: string): void + } + interface Command { /** - * NewBackupsFilesystem creates and returns a configured filesystem.System instance - * for managing app backups. - * - * NB! Make sure to call Close() on the returned result - * after you are done working with it. + * MarkPersistentFlagFilename instructs the various shell completion + * implementations to limit completions for the named persistent flag to the + * specified file extensions. */ - newBackupsFilesystem(): (filesystem.System) + markPersistentFlagFilename(name: string, ...extensions: string[]): void + } + interface Command { /** - * RefreshSettings reinitializes and reloads the stored application settings. + * MarkFlagDirname instructs the various shell completion implementations to + * limit completions for the named flag to directory names. */ - refreshSettings(): void + markFlagDirname(name: string): void + } + interface Command { /** - * IsBootstrapped checks if the application was initialized - * (aka. whether Bootstrap() was called). + * MarkPersistentFlagDirname instructs the various shell completion + * implementations to limit completions for the named persistent flag to + * directory names. */ - isBootstrapped(): boolean + markPersistentFlagDirname(name: string): void + } + interface Command { /** - * Bootstrap takes care for initializing the application - * (open db connections, load settings, etc.). - * - * It will call ResetBootstrapState() if the application was already bootstrapped. + * GenZshCompletionFile generates zsh completion file including descriptions. */ - bootstrap(): void + genZshCompletionFile(filename: string): void + } + interface Command { /** - * ResetBootstrapState takes care for releasing initialized app resources - * (eg. closing db connections). + * GenZshCompletion generates zsh completion file including descriptions + * and writes it to the passed writer. */ - resetBootstrapState(): void + genZshCompletion(w: io.Writer): void + } + interface Command { /** - * CreateBackup creates a new backup of the current app pb_data directory. - * - * Backups can be stored on S3 if it is configured in app.Settings().Backups. - * - * Please refer to the godoc of the specific CoreApp implementation - * for details on the backup procedures. + * GenZshCompletionFileNoDesc generates zsh completion file without descriptions. */ - createBackup(ctx: context.Context, name: string): void + genZshCompletionFileNoDesc(filename: string): void + } + interface Command { /** - * RestoreBackup restores the backup with the specified name and restarts - * the current running application process. - * - * The safely perform the restore it is recommended to have free disk space - * for at least 2x the size of the restored pb_data backup. - * - * Please refer to the godoc of the specific CoreApp implementation - * for details on the restore procedures. - * - * NB! This feature is experimental and currently is expected to work only on UNIX based systems. + * GenZshCompletionNoDesc generates zsh completion file without descriptions + * and writes it to the passed writer. */ - restoreBackup(ctx: context.Context, name: string): void + genZshCompletionNoDesc(w: io.Writer): void + } + interface Command { /** - * Restart restarts the current running application process. + * MarkZshCompPositionalArgumentFile only worked for zsh and its behavior was + * not consistent with Bash completion. It has therefore been disabled. + * Instead, when no other completion is specified, file completion is done by + * default for every argument. One can disable file completion on a per-argument + * basis by using ValidArgsFunction and ShellCompDirectiveNoFileComp. + * To achieve file extension filtering, one can use ValidArgsFunction and + * ShellCompDirectiveFilterFileExt. * - * Currently it is relying on execve so it is supported only on UNIX based systems. + * Deprecated */ - restart(): void + markZshCompPositionalArgumentFile(argPosition: number, ...patterns: string[]): void + } + interface Command { /** - * OnBeforeBootstrap hook is triggered before initializing the main - * application resources (eg. before db open and initial settings load). + * MarkZshCompPositionalArgumentWords only worked for zsh. It has therefore + * been disabled. + * To achieve the same behavior across all shells, one can use + * ValidArgs (for the first argument only) or ValidArgsFunction for + * any argument (can include the first one also). + * + * Deprecated */ - onBeforeBootstrap(): (hook.Hook) + markZshCompPositionalArgumentWords(argPosition: number, ...words: string[]): void + } +} + +/** + * Package schema implements custom Schema and SchemaField datatypes + * for handling the Collection schema definitions. + */ +namespace schema { + // @ts-ignore + import validation = ozzo_validation + /** + * Schema defines a dynamic db schema as a slice of `SchemaField`s. + */ + interface Schema { + } + interface Schema { /** - * OnAfterBootstrap hook is triggered after initializing the main - * application resources (eg. after db open and initial settings load). + * Fields returns the registered schema fields. */ - onAfterBootstrap(): (hook.Hook) + fields(): Array<(SchemaField | undefined)> + } + interface Schema { /** - * OnBeforeServe hook is triggered before serving the internal router (echo), - * allowing you to adjust its options and attach new routes or middlewares. + * InitFieldsOptions calls `InitOptions()` for all schema fields. */ - onBeforeServe(): (hook.Hook) + initFieldsOptions(): void + } + interface Schema { /** - * OnBeforeApiError hook is triggered right before sending an error API - * response to the client, allowing you to further modify the error data - * or to return a completely different API response. + * Clone creates a deep clone of the current schema. */ - onBeforeApiError(): (hook.Hook) + clone(): (Schema) + } + interface Schema { /** - * OnAfterApiError hook is triggered right after sending an error API - * response to the client. - * It could be used to log the final API error in external services. + * AsMap returns a map with all registered schema field. + * The returned map is indexed with each field name. */ - onAfterApiError(): (hook.Hook) + asMap(): _TygojaDict + } + interface Schema { /** - * OnTerminate hook is triggered when the app is in the process - * of being terminated (eg. on SIGTERM signal). + * GetFieldById returns a single field by its id. */ - onTerminate(): (hook.Hook) + getFieldById(id: string): (SchemaField) + } + interface Schema { /** - * OnModelBeforeCreate hook is triggered before inserting a new - * model in the DB, allowing you to modify or validate the stored data. - * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * GetFieldByName returns a single field by its name. */ - onModelBeforeCreate(...tags: string[]): (hook.TaggedHook) + getFieldByName(name: string): (SchemaField) + } + interface Schema { /** - * OnModelAfterCreate hook is triggered after successfully - * inserting a new model in the DB. + * RemoveField removes a single schema field by its id. * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * This method does nothing if field with `id` doesn't exist. */ - onModelAfterCreate(...tags: string[]): (hook.TaggedHook) + removeField(id: string): void + } + interface Schema { /** - * OnModelBeforeUpdate hook is triggered before updating existing - * model in the DB, allowing you to modify or validate the stored data. + * AddField registers the provided newField to the current schema. * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * If field with `newField.Id` already exist, the existing field is + * replaced with the new one. + * + * Otherwise the new field is appended to the other schema fields. */ - onModelBeforeUpdate(...tags: string[]): (hook.TaggedHook) + addField(newField: SchemaField): void + } + interface Schema { /** - * OnModelAfterUpdate hook is triggered after successfully updating - * existing model in the DB. + * Validate makes Schema validatable by implementing [validation.Validatable] interface. * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * Internally calls each individual field's validator and additionally + * checks for invalid renamed fields and field name duplications. */ - onModelAfterUpdate(...tags: string[]): (hook.TaggedHook) + validate(): void + } + interface Schema { /** - * OnModelBeforeDelete hook is triggered before deleting an - * existing model from the DB. - * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * MarshalJSON implements the [json.Marshaler] interface. */ - onModelBeforeDelete(...tags: string[]): (hook.TaggedHook) + marshalJSON(): string|Array + } + interface Schema { /** - * OnModelAfterDelete hook is triggered after successfully deleting an - * existing model from the DB. + * UnmarshalJSON implements the [json.Unmarshaler] interface. * - * If the optional "tags" list (table names and/or the Collection id for Record models) - * is specified, then all event handlers registered via the created hook - * will be triggered and called only if their event data origin matches the tags. + * On success, all schema field options are auto initialized. */ - onModelAfterDelete(...tags: string[]): (hook.TaggedHook) + unmarshalJSON(data: string|Array): void + } + interface Schema { /** - * OnMailerBeforeAdminResetPasswordSend hook is triggered right - * before sending a password reset email to an admin, allowing you - * to inspect and customize the email message that is being sent. + * Value implements the [driver.Valuer] interface. */ - onMailerBeforeAdminResetPasswordSend(): (hook.Hook) + value(): any + } + interface Schema { /** - * OnMailerAfterAdminResetPasswordSend hook is triggered after - * admin password reset email was successfully sent. + * Scan implements [sql.Scanner] interface to scan the provided value + * into the current Schema instance. */ - onMailerAfterAdminResetPasswordSend(): (hook.Hook) + scan(value: any): void + } +} + +/** + * Package models implements all PocketBase DB models and DTOs. + */ +namespace models { + type _subGeaoE = BaseModel + interface Admin extends _subGeaoE { + avatar: number + email: string + tokenKey: string + passwordHash: string + lastResetSentAt: types.DateTime + } + interface Admin { /** - * OnMailerBeforeRecordResetPasswordSend hook is triggered right - * before sending a password reset email to an auth record, allowing - * you to inspect and customize the email message that is being sent. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * TableName returns the Admin model SQL table name. */ - onMailerBeforeRecordResetPasswordSend(...tags: string[]): (hook.TaggedHook) + tableName(): string + } + interface Admin { /** - * OnMailerAfterRecordResetPasswordSend hook is triggered after - * an auth record password reset email was successfully sent. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * ValidatePassword validates a plain password against the model's password. */ - onMailerAfterRecordResetPasswordSend(...tags: string[]): (hook.TaggedHook) + validatePassword(password: string): boolean + } + interface Admin { /** - * OnMailerBeforeRecordVerificationSend hook is triggered right - * before sending a verification email to an auth record, allowing - * you to inspect and customize the email message that is being sent. + * SetPassword sets cryptographically secure string to `model.Password`. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Additionally this method also resets the LastResetSentAt and the TokenKey fields. */ - onMailerBeforeRecordVerificationSend(...tags: string[]): (hook.TaggedHook) + setPassword(password: string): void + } + interface Admin { /** - * OnMailerAfterRecordVerificationSend hook is triggered after a - * verification email was successfully sent to an auth record. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * RefreshTokenKey generates and sets new random token key. */ - onMailerAfterRecordVerificationSend(...tags: string[]): (hook.TaggedHook) + refreshTokenKey(): void + } + // @ts-ignore + import validation = ozzo_validation + type _subvYPhz = BaseModel + interface Collection extends _subvYPhz { + name: string + type: string + system: boolean + schema: schema.Schema + indexes: types.JsonArray /** - * OnMailerBeforeRecordChangeEmailSend hook is triggered right before - * sending a confirmation new address email to an auth record, allowing - * you to inspect and customize the email message that is being sent. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * rules */ - onMailerBeforeRecordChangeEmailSend(...tags: string[]): (hook.TaggedHook) - /** - * OnMailerAfterRecordChangeEmailSend hook is triggered after a - * verification email was successfully sent to an auth record. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. - */ - onMailerAfterRecordChangeEmailSend(...tags: string[]): (hook.TaggedHook) + listRule?: string + viewRule?: string + createRule?: string + updateRule?: string + deleteRule?: string + options: types.JsonMap + } + interface Collection { /** - * OnRealtimeConnectRequest hook is triggered right before establishing - * the SSE client connection. + * TableName returns the Collection model SQL table name. */ - onRealtimeConnectRequest(): (hook.Hook) + tableName(): string + } + interface Collection { /** - * OnRealtimeDisconnectRequest hook is triggered on disconnected/interrupted - * SSE client connection. + * BaseFilesPath returns the storage dir path used by the collection. */ - onRealtimeDisconnectRequest(): (hook.Hook) + baseFilesPath(): string + } + interface Collection { /** - * OnRealtimeBeforeMessage hook is triggered right before sending - * an SSE message to a client. - * - * Returning [hook.StopPropagation] will prevent sending the message. - * Returning any other non-nil error will close the realtime connection. + * IsBase checks if the current collection has "base" type. */ - onRealtimeBeforeMessageSend(): (hook.Hook) + isBase(): boolean + } + interface Collection { /** - * OnRealtimeBeforeMessage hook is triggered right after sending - * an SSE message to a client. + * IsAuth checks if the current collection has "auth" type. */ - onRealtimeAfterMessageSend(): (hook.Hook) + isAuth(): boolean + } + interface Collection { /** - * OnRealtimeBeforeSubscribeRequest hook is triggered before changing - * the client subscriptions, allowing you to further validate and - * modify the submitted change. + * IsView checks if the current collection has "view" type. */ - onRealtimeBeforeSubscribeRequest(): (hook.Hook) + isView(): boolean + } + interface Collection { /** - * OnRealtimeAfterSubscribeRequest hook is triggered after the client - * subscriptions were successfully changed. + * MarshalJSON implements the [json.Marshaler] interface. */ - onRealtimeAfterSubscribeRequest(): (hook.Hook) + marshalJSON(): string|Array + } + interface Collection { /** - * OnSettingsListRequest hook is triggered on each successful - * API Settings list request. - * - * Could be used to validate or modify the response before - * returning it to the client. + * BaseOptions decodes the current collection options and returns them + * as new [CollectionBaseOptions] instance. */ - onSettingsListRequest(): (hook.Hook) + baseOptions(): CollectionBaseOptions + } + interface Collection { /** - * OnSettingsBeforeUpdateRequest hook is triggered before each API - * Settings update request (after request data load and before settings persistence). - * - * Could be used to additionally validate the request data or - * implement completely different persistence behavior. + * AuthOptions decodes the current collection options and returns them + * as new [CollectionAuthOptions] instance. */ - onSettingsBeforeUpdateRequest(): (hook.Hook) + authOptions(): CollectionAuthOptions + } + interface Collection { /** - * OnSettingsAfterUpdateRequest hook is triggered after each - * successful API Settings update request. + * ViewOptions decodes the current collection options and returns them + * as new [CollectionViewOptions] instance. */ - onSettingsAfterUpdateRequest(): (hook.Hook) + viewOptions(): CollectionViewOptions + } + interface Collection { /** - * OnFileDownloadRequest hook is triggered before each API File download request. - * - * Could be used to validate or modify the file response before - * returning it to the client. + * NormalizeOptions updates the current collection options with a + * new normalized state based on the collection type. */ - onFileDownloadRequest(...tags: string[]): (hook.TaggedHook) + normalizeOptions(): void + } + interface Collection { /** - * OnFileBeforeTokenRequest hook is triggered before each file - * token API request. - * - * If no token or model was submitted, e.Model and e.Token will be empty, - * allowing you to implement your own custom model file auth implementation. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * DecodeOptions decodes the current collection options into the + * provided "result" (must be a pointer). */ - onFileBeforeTokenRequest(...tags: string[]): (hook.TaggedHook) + decodeOptions(result: any): void + } + interface Collection { /** - * OnFileAfterTokenRequest hook is triggered after each - * successful file token API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * SetOptions normalizes and unmarshals the specified options into m.Options. */ - onFileAfterTokenRequest(...tags: string[]): (hook.TaggedHook) + setOptions(typedOptions: any): void + } + type _subZrUNb = BaseModel + interface ExternalAuth extends _subZrUNb { + collectionId: string + recordId: string + provider: string + providerId: string + } + interface ExternalAuth { + tableName(): string + } + type _subdDjDh = BaseModel + interface Record extends _subdDjDh { + } + interface Record { /** - * OnAdminsListRequest hook is triggered on each API Admins list request. - * - * Could be used to validate or modify the response before returning it to the client. + * TableName returns the table name associated to the current Record model. */ - onAdminsListRequest(): (hook.Hook) + tableName(): string + } + interface Record { /** - * OnAdminViewRequest hook is triggered on each API Admin view request. - * - * Could be used to validate or modify the response before returning it to the client. + * Collection returns the Collection model associated to the current Record model. */ - onAdminViewRequest(): (hook.Hook) + collection(): (Collection) + } + interface Record { /** - * OnAdminBeforeCreateRequest hook is triggered before each API - * Admin create request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * OriginalCopy returns a copy of the current record model populated + * with its ORIGINAL data state (aka. the initially loaded) and + * everything else reset to the defaults. */ - onAdminBeforeCreateRequest(): (hook.Hook) + originalCopy(): (Record) + } + interface Record { /** - * OnAdminAfterCreateRequest hook is triggered after each - * successful API Admin create request. + * CleanCopy returns a copy of the current record model populated only + * with its LATEST data state and everything else reset to the defaults. */ - onAdminAfterCreateRequest(): (hook.Hook) + cleanCopy(): (Record) + } + interface Record { /** - * OnAdminBeforeUpdateRequest hook is triggered before each API - * Admin update request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * Expand returns a shallow copy of the current Record model expand data. */ - onAdminBeforeUpdateRequest(): (hook.Hook) + expand(): _TygojaDict + } + interface Record { /** - * OnAdminAfterUpdateRequest hook is triggered after each - * successful API Admin update request. + * SetExpand shallow copies the provided data to the current Record model's expand. */ - onAdminAfterUpdateRequest(): (hook.Hook) + setExpand(expand: _TygojaDict): void + } + interface Record { /** - * OnAdminBeforeDeleteRequest hook is triggered before each API - * Admin delete request (after model load and before actual deletion). + * MergeExpand merges recursively the provided expand data into + * the current model's expand (if any). * - * Could be used to additionally validate the request data or implement - * completely different delete behavior. + * Note that if an expanded prop with the same key is a slice (old or new expand) + * then both old and new records will be merged into a new slice (aka. a :merge: [b,c] => [a,b,c]). + * Otherwise the "old" expanded record will be replace with the "new" one (aka. a :merge: aNew => aNew). */ - onAdminBeforeDeleteRequest(): (hook.Hook) + mergeExpand(expand: _TygojaDict): void + } + interface Record { /** - * OnAdminAfterDeleteRequest hook is triggered after each - * successful API Admin delete request. + * SchemaData returns a shallow copy ONLY of the defined record schema fields data. */ - onAdminAfterDeleteRequest(): (hook.Hook) + schemaData(): _TygojaDict + } + interface Record { /** - * OnAdminAuthRequest hook is triggered on each successful API Admin - * authentication request (sign-in, token refresh, etc.). - * - * Could be used to additionally validate or modify the - * authenticated admin data and token. + * UnknownData returns a shallow copy ONLY of the unknown record fields data, + * aka. fields that are neither one of the base and special system ones, + * nor defined by the collection schema. */ - onAdminAuthRequest(): (hook.Hook) + unknownData(): _TygojaDict + } + interface Record { /** - * OnAdminBeforeAuthWithPasswordRequest hook is triggered before each Admin - * auth with password API request (after request data load and before password validation). - * - * Could be used to implement for example a custom password validation - * or to locate a different Admin identity (by assigning [AdminAuthWithPasswordEvent.Admin]). + * IgnoreEmailVisibility toggles the flag to ignore the auth record email visibility check. */ - onAdminBeforeAuthWithPasswordRequest(): (hook.Hook) + ignoreEmailVisibility(state: boolean): void + } + interface Record { /** - * OnAdminAfterAuthWithPasswordRequest hook is triggered after each - * successful Admin auth with password API request. + * WithUnknownData toggles the export/serialization of unknown data fields + * (false by default). */ - onAdminAfterAuthWithPasswordRequest(): (hook.Hook) + withUnknownData(state: boolean): void + } + interface Record { /** - * OnAdminBeforeAuthRefreshRequest hook is triggered before each Admin - * auth refresh API request (right before generating a new auth token). + * Set sets the provided key-value data pair for the current Record model. * - * Could be used to additionally validate the request data or implement - * completely different auth refresh behavior. + * If the record collection has field with name matching the provided "key", + * the value will be further normalized according to the field rules. */ - onAdminBeforeAuthRefreshRequest(): (hook.Hook) + set(key: string, value: any): void + } + interface Record { /** - * OnAdminAfterAuthRefreshRequest hook is triggered after each - * successful auth refresh API request (right after generating a new auth token). + * Get returns a normalized single record model data value for "key". */ - onAdminAfterAuthRefreshRequest(): (hook.Hook) + get(key: string): any + } + interface Record { /** - * OnAdminBeforeRequestPasswordResetRequest hook is triggered before each Admin - * request password reset API request (after request data load and before sending the reset email). - * - * Could be used to additionally validate the request data or implement - * completely different password reset behavior. + * GetBool returns the data value for "key" as a bool. */ - onAdminBeforeRequestPasswordResetRequest(): (hook.Hook) + getBool(key: string): boolean + } + interface Record { /** - * OnAdminAfterRequestPasswordResetRequest hook is triggered after each - * successful request password reset API request. + * GetString returns the data value for "key" as a string. */ - onAdminAfterRequestPasswordResetRequest(): (hook.Hook) + getString(key: string): string + } + interface Record { /** - * OnAdminBeforeConfirmPasswordResetRequest hook is triggered before each Admin - * confirm password reset API request (after request data load and before persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * GetInt returns the data value for "key" as an int. */ - onAdminBeforeConfirmPasswordResetRequest(): (hook.Hook) + getInt(key: string): number + } + interface Record { /** - * OnAdminAfterConfirmPasswordResetRequest hook is triggered after each - * successful confirm password reset API request. + * GetFloat returns the data value for "key" as a float64. */ - onAdminAfterConfirmPasswordResetRequest(): (hook.Hook) + getFloat(key: string): number + } + interface Record { /** - * OnRecordAuthRequest hook is triggered on each successful API - * record authentication request (sign-in, token refresh, etc.). - * - * Could be used to additionally validate or modify the authenticated - * record data and token. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * GetTime returns the data value for "key" as a [time.Time] instance. */ - onRecordAuthRequest(...tags: string[]): (hook.TaggedHook) + getTime(key: string): time.Time + } + interface Record { /** - * OnRecordBeforeAuthWithPasswordRequest hook is triggered before each Record - * auth with password API request (after request data load and before password validation). - * - * Could be used to implement for example a custom password validation - * or to locate a different Record model (by reassigning [RecordAuthWithPasswordEvent.Record]). - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * GetDateTime returns the data value for "key" as a DateTime instance. */ - onRecordBeforeAuthWithPasswordRequest(...tags: string[]): (hook.TaggedHook) + getDateTime(key: string): types.DateTime + } + interface Record { /** - * OnRecordAfterAuthWithPasswordRequest hook is triggered after each - * successful Record auth with password API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * GetStringSlice returns the data value for "key" as a slice of unique strings. */ - onRecordAfterAuthWithPasswordRequest(...tags: string[]): (hook.TaggedHook) + getStringSlice(key: string): Array + } + interface Record { /** - * OnRecordBeforeAuthWithOAuth2Request hook is triggered before each Record - * OAuth2 sign-in/sign-up API request (after token exchange and before external provider linking). - * - * If the [RecordAuthWithOAuth2Event.Record] is not set, then the OAuth2 - * request will try to create a new auth Record. + * ExpandedOne retrieves a single relation Record from the already + * loaded expand data of the current model. * - * To assign or link a different existing record model you can - * change the [RecordAuthWithOAuth2Event.Record] field. + * If the requested expand relation is multiple, this method returns + * only first available Record from the expanded relation. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns nil if there is no such expand relation loaded. */ - onRecordBeforeAuthWithOAuth2Request(...tags: string[]): (hook.TaggedHook) + expandedOne(relField: string): (Record) + } + interface Record { /** - * OnRecordAfterAuthWithOAuth2Request hook is triggered after each - * successful Record OAuth2 API request. + * ExpandedAll retrieves a slice of relation Records from the already + * loaded expand data of the current model. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * If the requested expand relation is single, this method normalizes + * the return result and will wrap the single model as a slice. + * + * Returns nil slice if there is no such expand relation loaded. */ - onRecordAfterAuthWithOAuth2Request(...tags: string[]): (hook.TaggedHook) + expandedAll(relField: string): Array<(Record | undefined)> + } + interface Record { /** - * OnRecordBeforeAuthRefreshRequest hook is triggered before each Record - * auth refresh API request (right before generating a new auth token). + * Retrieves the "key" json field value and unmarshals it into "result". * - * Could be used to additionally validate the request data or implement - * completely different auth refresh behavior. + * Example * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * ``` + * result := struct { + * FirstName string `json:"first_name"` + * }{} + * err := m.UnmarshalJSONField("my_field_name", &result) + * ``` */ - onRecordBeforeAuthRefreshRequest(...tags: string[]): (hook.TaggedHook) + unmarshalJSONField(key: string, result: any): void + } + interface Record { /** - * OnRecordAfterAuthRefreshRequest hook is triggered after each - * successful auth refresh API request (right after generating a new auth token). - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * BaseFilesPath returns the storage dir path used by the record. */ - onRecordAfterAuthRefreshRequest(...tags: string[]): (hook.TaggedHook) + baseFilesPath(): string + } + interface Record { /** - * OnRecordListExternalAuthsRequest hook is triggered on each API record external auths list request. - * - * Could be used to validate or modify the response before returning it to the client. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * FindFileFieldByFile returns the first file type field for which + * any of the record's data contains the provided filename. */ - onRecordListExternalAuthsRequest(...tags: string[]): (hook.TaggedHook) + findFileFieldByFile(filename: string): (schema.SchemaField) + } + interface Record { /** - * OnRecordBeforeUnlinkExternalAuthRequest hook is triggered before each API record - * external auth unlink request (after models load and before the actual relation deletion). - * - * Could be used to additionally validate the request data or implement - * completely different delete behavior. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Load bulk loads the provided data into the current Record model. */ - onRecordBeforeUnlinkExternalAuthRequest(...tags: string[]): (hook.TaggedHook) + load(data: _TygojaDict): void + } + interface Record { /** - * OnRecordAfterUnlinkExternalAuthRequest hook is triggered after each - * successful API record external auth unlink request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * ColumnValueMap implements [ColumnValueMapper] interface. */ - onRecordAfterUnlinkExternalAuthRequest(...tags: string[]): (hook.TaggedHook) + columnValueMap(): _TygojaDict + } + interface Record { /** - * OnRecordBeforeRequestPasswordResetRequest hook is triggered before each Record - * request password reset API request (after request data load and before sending the reset email). - * - * Could be used to additionally validate the request data or implement - * completely different password reset behavior. + * PublicExport exports only the record fields that are safe to be public. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * For auth records, to force the export of the email field you need to set + * `m.IgnoreEmailVisibility(true)`. */ - onRecordBeforeRequestPasswordResetRequest(...tags: string[]): (hook.TaggedHook) + publicExport(): _TygojaDict + } + interface Record { /** - * OnRecordAfterRequestPasswordResetRequest hook is triggered after each - * successful request password reset API request. + * MarshalJSON implements the [json.Marshaler] interface. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Only the data exported by `PublicExport()` will be serialized. */ - onRecordAfterRequestPasswordResetRequest(...tags: string[]): (hook.TaggedHook) + marshalJSON(): string|Array + } + interface Record { /** - * OnRecordBeforeConfirmPasswordResetRequest hook is triggered before each Record - * confirm password reset API request (after request data load and before persistence). + * UnmarshalJSON implements the [json.Unmarshaler] interface. + */ + unmarshalJSON(data: string|Array): void + } + interface Record { + /** + * ReplaceModifers returns a new map with applied modifier + * values based on the current record and the specified data. * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * The resolved modifier keys will be removed. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Multiple modifiers will be applied one after another, + * while reusing the previous base key value result (eg. 1; -5; +2 => -2). + * + * Example usage: + * + * ``` + * newData := record.ReplaceModifers(data) + * // record: {"field": 10} + * // data: {"field+": 5} + * // newData: {"field": 15} + * ``` */ - onRecordBeforeConfirmPasswordResetRequest(...tags: string[]): (hook.TaggedHook) + replaceModifers(data: _TygojaDict): _TygojaDict + } + interface Record { /** - * OnRecordAfterConfirmPasswordResetRequest hook is triggered after each - * successful confirm password reset API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Username returns the "username" auth record data value. */ - onRecordAfterConfirmPasswordResetRequest(...tags: string[]): (hook.TaggedHook) + username(): string + } + interface Record { /** - * OnRecordBeforeRequestVerificationRequest hook is triggered before each Record - * request verification API request (after request data load and before sending the verification email). + * SetUsername sets the "username" auth record data value. * - * Could be used to additionally validate the loaded request data or implement - * completely different verification behavior. + * This method doesn't check whether the provided value is a valid username. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordBeforeRequestVerificationRequest(...tags: string[]): (hook.TaggedHook) + setUsername(username: string): void + } + interface Record { /** - * OnRecordAfterRequestVerificationRequest hook is triggered after each - * successful request verification API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Email returns the "email" auth record data value. */ - onRecordAfterRequestVerificationRequest(...tags: string[]): (hook.TaggedHook) + email(): string + } + interface Record { /** - * OnRecordBeforeConfirmVerificationRequest hook is triggered before each Record - * confirm verification API request (after request data load and before persistence). + * SetEmail sets the "email" auth record data value. * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * This method doesn't check whether the provided value is a valid email. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordBeforeConfirmVerificationRequest(...tags: string[]): (hook.TaggedHook) + setEmail(email: string): void + } + interface Record { /** - * OnRecordAfterConfirmVerificationRequest hook is triggered after each - * successful confirm verification API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Verified returns the "emailVisibility" auth record data value. */ - onRecordAfterConfirmVerificationRequest(...tags: string[]): (hook.TaggedHook) + emailVisibility(): boolean + } + interface Record { /** - * OnRecordBeforeRequestEmailChangeRequest hook is triggered before each Record request email change API request - * (after request data load and before sending the email link to confirm the change). - * - * Could be used to additionally validate the request data or implement - * completely different request email change behavior. + * SetEmailVisibility sets the "emailVisibility" auth record data value. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordBeforeRequestEmailChangeRequest(...tags: string[]): (hook.TaggedHook) + setEmailVisibility(visible: boolean): void + } + interface Record { /** - * OnRecordAfterRequestEmailChangeRequest hook is triggered after each - * successful request email change API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Verified returns the "verified" auth record data value. */ - onRecordAfterRequestEmailChangeRequest(...tags: string[]): (hook.TaggedHook) + verified(): boolean + } + interface Record { /** - * OnRecordBeforeConfirmEmailChangeRequest hook is triggered before each Record - * confirm email change API request (after request data load and before persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * SetVerified sets the "verified" auth record data value. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordBeforeConfirmEmailChangeRequest(...tags: string[]): (hook.TaggedHook) + setVerified(verified: boolean): void + } + interface Record { /** - * OnRecordAfterConfirmEmailChangeRequest hook is triggered after each - * successful confirm email change API request. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * TokenKey returns the "tokenKey" auth record data value. */ - onRecordAfterConfirmEmailChangeRequest(...tags: string[]): (hook.TaggedHook) + tokenKey(): string + } + interface Record { /** - * OnRecordsListRequest hook is triggered on each API Records list request. - * - * Could be used to validate or modify the response before returning it to the client. + * SetTokenKey sets the "tokenKey" auth record data value. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordsListRequest(...tags: string[]): (hook.TaggedHook) + setTokenKey(key: string): void + } + interface Record { /** - * OnRecordViewRequest hook is triggered on each API Record view request. - * - * Could be used to validate or modify the response before returning it to the client. + * RefreshTokenKey generates and sets new random auth record "tokenKey". * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordViewRequest(...tags: string[]): (hook.TaggedHook) + refreshTokenKey(): void + } + interface Record { /** - * OnRecordBeforeCreateRequest hook is triggered before each API Record - * create request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * LastResetSentAt returns the "lastResentSentAt" auth record data value. */ - onRecordBeforeCreateRequest(...tags: string[]): (hook.TaggedHook) + lastResetSentAt(): types.DateTime + } + interface Record { /** - * OnRecordAfterCreateRequest hook is triggered after each - * successful API Record create request. + * SetLastResetSentAt sets the "lastResentSentAt" auth record data value. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordAfterCreateRequest(...tags: string[]): (hook.TaggedHook) + setLastResetSentAt(dateTime: types.DateTime): void + } + interface Record { /** - * OnRecordBeforeUpdateRequest hook is triggered before each API Record - * update request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * LastVerificationSentAt returns the "lastVerificationSentAt" auth record data value. */ - onRecordBeforeUpdateRequest(...tags: string[]): (hook.TaggedHook) + lastVerificationSentAt(): types.DateTime + } + interface Record { /** - * OnRecordAfterUpdateRequest hook is triggered after each - * successful API Record update request. + * SetLastVerificationSentAt sets an "lastVerificationSentAt" auth record data value. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns an error if the record is not from an auth collection. */ - onRecordAfterUpdateRequest(...tags: string[]): (hook.TaggedHook) + setLastVerificationSentAt(dateTime: types.DateTime): void + } + interface Record { /** - * OnRecordBeforeDeleteRequest hook is triggered before each API Record - * delete request (after model load and before actual deletion). - * - * Could be used to additionally validate the request data or implement - * completely different delete behavior. - * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * PasswordHash returns the "passwordHash" auth record data value. */ - onRecordBeforeDeleteRequest(...tags: string[]): (hook.TaggedHook) + passwordHash(): string + } + interface Record { /** - * OnRecordAfterDeleteRequest hook is triggered after each - * successful API Record delete request. + * ValidatePassword validates a plain password against the auth record password. * - * If the optional "tags" list (Collection ids or names) is specified, - * then all event handlers registered via the created hook will be - * triggered and called only if their event data origin matches the tags. + * Returns false if the password is incorrect or record is not from an auth collection. */ - onRecordAfterDeleteRequest(...tags: string[]): (hook.TaggedHook) + validatePassword(password: string): boolean + } + interface Record { /** - * OnCollectionsListRequest hook is triggered on each API Collections list request. + * SetPassword sets cryptographically secure string to the auth record "password" field. + * This method also resets the "lastResetSentAt" and the "tokenKey" fields. * - * Could be used to validate or modify the response before returning it to the client. + * Returns an error if the record is not from an auth collection or + * an empty password is provided. */ - onCollectionsListRequest(): (hook.Hook) + setPassword(password: string): void + } + /** + * RequestInfo defines a HTTP request data struct, usually used + * as part of the `@request.*` filter resolver. + */ + interface RequestInfo { + query: _TygojaDict + data: _TygojaDict + headers: _TygojaDict + authRecord?: Record + admin?: Admin + method: string + } + interface RequestInfo { /** - * OnCollectionViewRequest hook is triggered on each API Collection view request. - * - * Could be used to validate or modify the response before returning it to the client. + * HasModifierDataKeys loosely checks if the current struct has any modifier Data keys. */ - onCollectionViewRequest(): (hook.Hook) + hasModifierDataKeys(): boolean + } +} + +/** + * Package daos handles common PocketBase DB model manipulations. + * + * Think of daos as DB repository and service layer in one. + */ +namespace daos { + interface Dao { /** - * OnCollectionBeforeCreateRequest hook is triggered before each API Collection - * create request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * AdminQuery returns a new Admin select query. */ - onCollectionBeforeCreateRequest(): (hook.Hook) + adminQuery(): (dbx.SelectQuery) + } + interface Dao { /** - * OnCollectionAfterCreateRequest hook is triggered after each - * successful API Collection create request. + * FindAdminById finds the admin with the provided id. */ - onCollectionAfterCreateRequest(): (hook.Hook) + findAdminById(id: string): (models.Admin) + } + interface Dao { /** - * OnCollectionBeforeUpdateRequest hook is triggered before each API Collection - * update request (after request data load and before model persistence). - * - * Could be used to additionally validate the request data or implement - * completely different persistence behavior. + * FindAdminByEmail finds the admin with the provided email address. */ - onCollectionBeforeUpdateRequest(): (hook.Hook) + findAdminByEmail(email: string): (models.Admin) + } + interface Dao { /** - * OnCollectionAfterUpdateRequest hook is triggered after each - * successful API Collection update request. + * FindAdminByToken finds the admin associated with the provided JWT. + * + * Returns an error if the JWT is invalid or expired. */ - onCollectionAfterUpdateRequest(): (hook.Hook) + findAdminByToken(token: string, baseTokenKey: string): (models.Admin) + } + interface Dao { /** - * OnCollectionBeforeDeleteRequest hook is triggered before each API - * Collection delete request (after model load and before actual deletion). - * - * Could be used to additionally validate the request data or implement - * completely different delete behavior. + * TotalAdmins returns the number of existing admin records. */ - onCollectionBeforeDeleteRequest(): (hook.Hook) + totalAdmins(): number + } + interface Dao { /** - * OnCollectionAfterDeleteRequest hook is triggered after each - * successful API Collection delete request. + * IsAdminEmailUnique checks if the provided email address is not + * already in use by other admins. */ - onCollectionAfterDeleteRequest(): (hook.Hook) + isAdminEmailUnique(email: string, ...excludeIds: string[]): boolean + } + interface Dao { /** - * OnCollectionsBeforeImportRequest hook is triggered before each API - * collections import request (after request data load and before the actual import). + * DeleteAdmin deletes the provided Admin model. * - * Could be used to additionally validate the imported collections or - * to implement completely different import behavior. + * Returns an error if there is only 1 admin. */ - onCollectionsBeforeImportRequest(): (hook.Hook) + deleteAdmin(admin: models.Admin): void + } + interface Dao { /** - * OnCollectionsAfterImportRequest hook is triggered after each - * successful API collections import request. + * SaveAdmin upserts the provided Admin model. */ - onCollectionsAfterImportRequest(): (hook.Hook) + saveAdmin(admin: models.Admin): void } -} - -/** - * Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces. - * In addition to providing an interface, Cobra simultaneously provides a controller to organize your application code. - */ -namespace cobra { - interface Command { + /** + * Dao handles various db operations. + * + * You can think of Dao as a repository and service layer in one. + */ + interface Dao { /** - * GenBashCompletion generates bash completion file and writes to the passed writer. + * MaxLockRetries specifies the default max "database is locked" auto retry attempts. */ - genBashCompletion(w: io.Writer): void - } - interface Command { + maxLockRetries: number /** - * GenBashCompletionFile generates bash completion file. + * ModelQueryTimeout is the default max duration of a running ModelQuery(). + * + * This field has no effect if an explicit query context is already specified. */ - genBashCompletionFile(filename: string): void - } - interface Command { + modelQueryTimeout: time.Duration /** - * GenBashCompletionFileV2 generates Bash completion version 2. + * write hooks */ - genBashCompletionFileV2(filename: string, includeDesc: boolean): void + beforeCreateFunc: (eventDao: Dao, m: models.Model, action: () => void) => void + afterCreateFunc: (eventDao: Dao, m: models.Model) => void + beforeUpdateFunc: (eventDao: Dao, m: models.Model, action: () => void) => void + afterUpdateFunc: (eventDao: Dao, m: models.Model) => void + beforeDeleteFunc: (eventDao: Dao, m: models.Model, action: () => void) => void + afterDeleteFunc: (eventDao: Dao, m: models.Model) => void } - interface Command { + interface Dao { /** - * GenBashCompletionV2 generates Bash completion file version 2 - * and writes it to the passed writer. + * DB returns the default dao db builder (*dbx.DB or *dbx.TX). + * + * Currently the default db builder is dao.concurrentDB but that may change in the future. */ - genBashCompletionV2(w: io.Writer, includeDesc: boolean): void + db(): dbx.Builder } - // @ts-ignore - import flag = pflag - /** - * Command is just that, a command for your application. - * E.g. 'go run ...' - 'run' is the command. Cobra requires - * you to define the usage and description as part of your command - * definition to ensure usability. - */ - interface Command { + interface Dao { /** - * Use is the one-line usage message. - * Recommended syntax is as follows: - * ``` - * [ ] identifies an optional argument. Arguments that are not enclosed in brackets are required. - * ... indicates that you can specify multiple values for the previous argument. - * | indicates mutually exclusive information. You can use the argument to the left of the separator or the - * argument to the right of the separator. You cannot use both arguments in a single use of the command. - * { } delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are - * optional, they are enclosed in brackets ([ ]). - * ``` - * Example: add [-F file | -D dir]... [-f format] profile + * ConcurrentDB returns the dao concurrent (aka. multiple open connections) + * db builder (*dbx.DB or *dbx.TX). + * + * In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance. */ - use: string + concurrentDB(): dbx.Builder + } + interface Dao { /** - * Aliases is an array of aliases that can be used instead of the first word in Use. + * NonconcurrentDB returns the dao nonconcurrent (aka. single open connection) + * db builder (*dbx.DB or *dbx.TX). + * + * In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance. */ - aliases: Array + nonconcurrentDB(): dbx.Builder + } + interface Dao { /** - * SuggestFor is an array of command names for which this command will be suggested - - * similar to aliases but only suggests. + * Clone returns a new Dao with the same configuration options as the current one. */ - suggestFor: Array + clone(): (Dao) + } + interface Dao { /** - * Short is the short description shown in the 'help' output. + * WithoutHooks returns a new Dao with the same configuration options + * as the current one, but without create/update/delete hooks. */ - short: string + withoutHooks(): (Dao) + } + interface Dao { /** - * The group id under which this subcommand is grouped in the 'help' output of its parent. + * ModelQuery creates a new preconfigured select query with preset + * SELECT, FROM and other common fields based on the provided model. */ - groupID: string + modelQuery(m: models.Model): (dbx.SelectQuery) + } + interface Dao { /** - * Long is the long message shown in the 'help ' output. + * FindById finds a single db record with the specified id and + * scans the result into m. */ - long: string + findById(m: models.Model, id: string): void + } + interface Dao { /** - * Example is examples of how to use the command. + * RunInTransaction wraps fn into a transaction. + * + * It is safe to nest RunInTransaction calls as long as you use the txDao. */ - example: string + runInTransaction(fn: (txDao: Dao) => void): void + } + interface Dao { /** - * ValidArgs is list of all valid non-flag arguments that are accepted in shell completions + * Delete deletes the provided model. */ - validArgs: Array + delete(m: models.Model): void + } + interface Dao { /** - * ValidArgsFunction is an optional function that provides valid non-flag arguments for shell completion. - * It is a dynamic version of using ValidArgs. - * Only one of ValidArgs and ValidArgsFunction can be used for a command. + * Save persists the provided model in the database. + * + * If m.IsNew() is true, the method will perform a create, otherwise an update. + * To explicitly mark a model for update you can use m.MarkAsNotNew(). */ - validArgsFunction: (cmd: Command, args: Array, toComplete: string) => [Array, ShellCompDirective] + save(m: models.Model): void + } + interface Dao { /** - * Expected arguments + * CollectionQuery returns a new Collection select query. */ - args: PositionalArgs + collectionQuery(): (dbx.SelectQuery) + } + interface Dao { /** - * ArgAliases is List of aliases for ValidArgs. - * These are not suggested to the user in the shell completion, - * but accepted if entered manually. + * FindCollectionsByType finds all collections by the given type. */ - argAliases: Array + findCollectionsByType(collectionType: string): Array<(models.Collection | undefined)> + } + interface Dao { /** - * BashCompletionFunction is custom bash functions used by the legacy bash autocompletion generator. - * For portability with other shells, it is recommended to instead use ValidArgsFunction + * FindCollectionByNameOrId finds a single collection by its name (case insensitive) or id. */ - bashCompletionFunction: string + findCollectionByNameOrId(nameOrId: string): (models.Collection) + } + interface Dao { /** - * Deprecated defines, if this command is deprecated and should print this string when used. + * IsCollectionNameUnique checks that there is no existing collection + * with the provided name (case insensitive!). + * + * Note: case insensitive check because the name is used also as a table name for the records. */ - deprecated: string + isCollectionNameUnique(name: string, ...excludeIds: string[]): boolean + } + interface Dao { /** - * Annotations are key/value pairs that can be used by applications to identify or - * group commands or set special options. + * FindCollectionReferences returns information for all + * relation schema fields referencing the provided collection. + * + * If the provided collection has reference to itself then it will be + * also included in the result. To exclude it, pass the collection id + * as the excludeId argument. */ - annotations: _TygojaDict + findCollectionReferences(collection: models.Collection, ...excludeIds: string[]): _TygojaDict + } + interface Dao { /** - * Version defines the version for this command. If this value is non-empty and the command does not - * define a "version" flag, a "version" boolean flag will be added to the command and, if specified, - * will print content of the "Version" variable. A shorthand "v" flag will also be added if the - * command does not define one. + * DeleteCollection deletes the provided Collection model. + * This method automatically deletes the related collection records table. + * + * NB! The collection cannot be deleted, if: + * - is system collection (aka. collection.System is true) + * - is referenced as part of a relation field in another collection */ - version: string + deleteCollection(collection: models.Collection): void + } + interface Dao { /** - * The *Run functions are executed in the following order: - * ``` - * * PersistentPreRun() - * * PreRun() - * * Run() - * * PostRun() - * * PersistentPostRun() - * ``` - * All functions get the same args, the arguments after the command name. - * The *PreRun and *PostRun functions will only be executed if the Run function of the current - * command has been declared. + * SaveCollection persists the provided Collection model and updates + * its related records table schema. * - * PersistentPreRun: children of this command will inherit and execute. + * If collecction.IsNew() is true, the method will perform a create, otherwise an update. + * To explicitly mark a collection for update you can use collecction.MarkAsNotNew(). */ - persistentPreRun: (cmd: Command, args: Array) => void + saveCollection(collection: models.Collection): void + } + interface Dao { /** - * PersistentPreRunE: PersistentPreRun but returns an error. + * ImportCollections imports the provided collections list within a single transaction. + * + * NB1! If deleteMissing is set, all local collections and schema fields, that are not present + * in the imported configuration, WILL BE DELETED (including their related records data). + * + * NB2! This method doesn't perform validations on the imported collections data! + * If you need validations, use [forms.CollectionsImport]. */ - persistentPreRunE: (cmd: Command, args: Array) => void - /** - * PreRun: children of this command will not inherit. - */ - preRun: (cmd: Command, args: Array) => void + importCollections(importedCollections: Array<(models.Collection | undefined)>, deleteMissing: boolean, afterSync: (txDao: Dao, mappedImported: _TygojaDict) => void): void + } + interface Dao { /** - * PreRunE: PreRun but returns an error. + * ExternalAuthQuery returns a new ExternalAuth select query. */ - preRunE: (cmd: Command, args: Array) => void + externalAuthQuery(): (dbx.SelectQuery) + } + interface Dao { /** - * Run: Typically the actual work function. Most commands will only implement this. + * FindAllExternalAuthsByRecord returns all ExternalAuth models + * linked to the provided auth record. */ - run: (cmd: Command, args: Array) => void + findAllExternalAuthsByRecord(authRecord: models.Record): Array<(models.ExternalAuth | undefined)> + } + interface Dao { /** - * RunE: Run but returns an error. + * FindExternalAuthByRecordAndProvider returns the first available + * ExternalAuth model for the specified record data and provider. */ - runE: (cmd: Command, args: Array) => void + findExternalAuthByRecordAndProvider(authRecord: models.Record, provider: string): (models.ExternalAuth) + } + interface Dao { /** - * PostRun: run after the Run command. + * FindFirstExternalAuthByExpr returns the first available + * ExternalAuth model that satisfies the non-nil expression. */ - postRun: (cmd: Command, args: Array) => void + findFirstExternalAuthByExpr(expr: dbx.Expression): (models.ExternalAuth) + } + interface Dao { /** - * PostRunE: PostRun but returns an error. + * SaveExternalAuth upserts the provided ExternalAuth model. */ - postRunE: (cmd: Command, args: Array) => void + saveExternalAuth(model: models.ExternalAuth): void + } + interface Dao { /** - * PersistentPostRun: children of this command will inherit and execute after PostRun. + * DeleteExternalAuth deletes the provided ExternalAuth model. */ - persistentPostRun: (cmd: Command, args: Array) => void + deleteExternalAuth(model: models.ExternalAuth): void + } + interface Dao { /** - * PersistentPostRunE: PersistentPostRun but returns an error. + * LogQuery returns a new Log select query. */ - persistentPostRunE: (cmd: Command, args: Array) => void + logQuery(): (dbx.SelectQuery) + } + interface Dao { /** - * FParseErrWhitelist flag parse errors to be ignored + * FindLogById finds a single Log entry by its id. */ - fParseErrWhitelist: FParseErrWhitelist + findLogById(id: string): (models.Log) + } + interface Dao { /** - * CompletionOptions is a set of options to control the handling of shell completion + * LogsStats returns hourly grouped requests logs statistics. */ - completionOptions: CompletionOptions + logsStats(expr: dbx.Expression): Array<(LogsStatsItem | undefined)> + } + interface Dao { /** - * TraverseChildren parses flags on all parents before executing child command. + * DeleteOldLogs delete all requests that are created before createdBefore. */ - traverseChildren: boolean + deleteOldLogs(createdBefore: time.Time): void + } + interface Dao { /** - * Hidden defines, if this command is hidden and should NOT show up in the list of available commands. + * SaveLog upserts the provided Log model. */ - hidden: boolean + saveLog(log: models.Log): void + } + interface Dao { /** - * SilenceErrors is an option to quiet errors down stream. + * ParamQuery returns a new Param select query. */ - silenceErrors: boolean + paramQuery(): (dbx.SelectQuery) + } + interface Dao { /** - * SilenceUsage is an option to silence usage when an error occurs. + * FindParamByKey finds the first Param model with the provided key. */ - silenceUsage: boolean + findParamByKey(key: string): (models.Param) + } + interface Dao { /** - * DisableFlagParsing disables the flag parsing. - * If this is true all flags will be passed to the command as arguments. + * SaveParam creates or updates a Param model by the provided key-value pair. + * The value argument will be encoded as json string. + * + * If `optEncryptionKey` is provided it will encrypt the value before storing it. */ - disableFlagParsing: boolean + saveParam(key: string, value: any, ...optEncryptionKey: string[]): void + } + interface Dao { /** - * DisableAutoGenTag defines, if gen tag ("Auto generated by spf13/cobra...") - * will be printed by generating docs for this command. + * DeleteParam deletes the provided Param model. */ - disableAutoGenTag: boolean + deleteParam(param: models.Param): void + } + interface Dao { /** - * DisableFlagsInUseLine will disable the addition of [flags] to the usage - * line of a command when printing help or generating docs + * RecordQuery returns a new Record select query from a collection model, id or name. + * + * In case a collection id or name is provided and that collection doesn't + * actually exists, the generated query will be created with a cancelled context + * and will fail once an executor (Row(), One(), All(), etc.) is called. */ - disableFlagsInUseLine: boolean + recordQuery(collectionModelOrIdentifier: any): (dbx.SelectQuery) + } + interface Dao { /** - * DisableSuggestions disables the suggestions based on Levenshtein distance - * that go along with 'unknown command' messages. + * FindRecordById finds the Record model by its id. */ - disableSuggestions: boolean + findRecordById(collectionNameOrId: string, recordId: string, ...optFilters: ((q: dbx.SelectQuery) => void)[]): (models.Record) + } + interface Dao { /** - * SuggestionsMinimumDistance defines minimum levenshtein distance to display suggestions. - * Must be > 0. + * FindRecordsByIds finds all Record models by the provided ids. + * If no records are found, returns an empty slice. */ - suggestionsMinimumDistance: number + findRecordsByIds(collectionNameOrId: string, recordIds: Array, ...optFilters: ((q: dbx.SelectQuery) => void)[]): Array<(models.Record | undefined)> } - interface Command { + interface Dao { /** - * Context returns underlying command context. If command was executed - * with ExecuteContext or the context was set with SetContext, the - * previously set context will be returned. Otherwise, nil is returned. + * @todo consider to depricate as it may be easier to just use dao.RecordQuery() * - * Notice that a call to Execute and ExecuteC will replace a nil context of - * a command with a context.Background, so a background context will be - * returned by Context after one of these functions has been called. + * FindRecordsByExpr finds all records by the specified db expression. + * + * Returns all collection records if no expressions are provided. + * + * Returns an empty slice if no records are found. + * + * Example: + * + * ``` + * expr1 := dbx.HashExp{"email": "test@example.com"} + * expr2 := dbx.NewExp("LOWER(username) = {:username}", dbx.Params{"username": "test"}) + * dao.FindRecordsByExpr("example", expr1, expr2) + * ``` */ - context(): context.Context + findRecordsByExpr(collectionNameOrId: string, ...exprs: dbx.Expression[]): Array<(models.Record | undefined)> } - interface Command { + interface Dao { /** - * SetContext sets context for the command. This context will be overwritten by - * Command.ExecuteContext or Command.ExecuteContextC. + * FindFirstRecordByData returns the first found record matching + * the provided key-value pair. */ - setContext(ctx: context.Context): void + findFirstRecordByData(collectionNameOrId: string, key: string, value: any): (models.Record) } - interface Command { + interface Dao { /** - * SetArgs sets arguments for the command. It is set to os.Args[1:] by default, if desired, can be overridden - * particularly useful when testing. + * FindRecordsByFilter returns limit number of records matching the + * provided string filter. + * + * NB! Use the last "params" argument to bind untrusted user variables! + * + * The sort argument is optional and can be empty string OR the same format + * used in the web APIs, eg. "-created,title". + * + * If the limit argument is <= 0, no limit is applied to the query and + * all matching records are returned. + * + * Example: + * + * ``` + * dao.FindRecordsByFilter( + * "posts", + * "title ~ {:title} && visible = {:visible}", + * "-created", + * 10, + * 0, + * dbx.Params{"title": "lorem ipsum", "visible": true} + * ) + * ``` */ - setArgs(a: Array): void + findRecordsByFilter(collectionNameOrId: string, filter: string, sort: string, limit: number, offset: number, ...params: dbx.Params[]): Array<(models.Record | undefined)> } - interface Command { + interface Dao { /** - * SetOutput sets the destination for usage and error messages. - * If output is nil, os.Stderr is used. - * Deprecated: Use SetOut and/or SetErr instead + * FindFirstRecordByFilter returns the first available record matching the provided filter. + * + * NB! Use the last params argument to bind untrusted user variables! + * + * Example: + * + * ``` + * dao.FindFirstRecordByFilter("posts", "slug={:slug} && status='public'", dbx.Params{"slug": "test"}) + * ``` */ - setOutput(output: io.Writer): void + findFirstRecordByFilter(collectionNameOrId: string, filter: string, ...params: dbx.Params[]): (models.Record) } - interface Command { + interface Dao { /** - * SetOut sets the destination for usage messages. - * If newOut is nil, os.Stdout is used. + * IsRecordValueUnique checks if the provided key-value pair is a unique Record value. + * + * For correctness, if the collection is "auth" and the key is "username", + * the unique check will be case insensitive. + * + * NB! Array values (eg. from multiple select fields) are matched + * as a serialized json strings (eg. `["a","b"]`), so the value uniqueness + * depends on the elements order. Or in other words the following values + * are considered different: `[]string{"a","b"}` and `[]string{"b","a"}` */ - setOut(newOut: io.Writer): void + isRecordValueUnique(collectionNameOrId: string, key: string, value: any, ...excludeIds: string[]): boolean } - interface Command { + interface Dao { /** - * SetErr sets the destination for error messages. - * If newErr is nil, os.Stderr is used. + * FindAuthRecordByToken finds the auth record associated with the provided JWT. + * + * Returns an error if the JWT is invalid, expired or not associated to an auth collection record. */ - setErr(newErr: io.Writer): void + findAuthRecordByToken(token: string, baseTokenKey: string): (models.Record) } - interface Command { + interface Dao { /** - * SetIn sets the source for input data - * If newIn is nil, os.Stdin is used. + * FindAuthRecordByEmail finds the auth record associated with the provided email. + * + * Returns an error if it is not an auth collection or the record is not found. */ - setIn(newIn: io.Reader): void + findAuthRecordByEmail(collectionNameOrId: string, email: string): (models.Record) } - interface Command { + interface Dao { /** - * SetUsageFunc sets usage function. Usage can be defined by application. + * FindAuthRecordByUsername finds the auth record associated with the provided username (case insensitive). + * + * Returns an error if it is not an auth collection or the record is not found. */ - setUsageFunc(f: (_arg0: Command) => void): void + findAuthRecordByUsername(collectionNameOrId: string, username: string): (models.Record) } - interface Command { + interface Dao { /** - * SetUsageTemplate sets usage template. Can be defined by Application. + * SuggestUniqueAuthRecordUsername checks if the provided username is unique + * and return a new "unique" username with appended random numeric part + * (eg. "existingName" -> "existingName583"). + * + * The same username will be returned if the provided string is already unique. */ - setUsageTemplate(s: string): void + suggestUniqueAuthRecordUsername(collectionNameOrId: string, baseUsername: string, ...excludeIds: string[]): string } - interface Command { + interface Dao { /** - * SetFlagErrorFunc sets a function to generate an error when flag parsing - * fails. + * CanAccessRecord checks if a record is allowed to be accessed by the + * specified requestInfo and accessRule. + * + * Rule and db checks are ignored in case requestInfo.Admin is set. + * + * The returned error indicate that something unexpected happened during + * the check (eg. invalid rule or db error). + * + * The method always return false on invalid access rule or db error. + * + * Example: + * + * ``` + * requestInfo := apis.RequestInfo(c /* echo.Context *\/) + * record, _ := dao.FindRecordById("example", "RECORD_ID") + * rule := types.Pointer("@request.auth.id != '' || status = 'public'") + * // ... or use one of the record collection's rule, eg. record.Collection().ViewRule + * + * if ok, _ := dao.CanAccessRecord(record, requestInfo, rule); ok { ... } + * ``` */ - setFlagErrorFunc(f: (_arg0: Command, _arg1: Error) => void): void + canAccessRecord(record: models.Record, requestInfo: models.RequestInfo, accessRule: string): boolean } - interface Command { + interface Dao { /** - * SetHelpFunc sets help function. Can be defined by Application. + * SaveRecord persists the provided Record model in the database. + * + * If record.IsNew() is true, the method will perform a create, otherwise an update. + * To explicitly mark a record for update you can use record.MarkAsNotNew(). */ - setHelpFunc(f: (_arg0: Command, _arg1: Array) => void): void + saveRecord(record: models.Record): void } - interface Command { + interface Dao { /** - * SetHelpCommand sets help command. + * DeleteRecord deletes the provided Record model. + * + * This method will also cascade the delete operation to all linked + * relational records (delete or unset, depending on the rel settings). + * + * The delete operation may fail if the record is part of a required + * reference in another record (aka. cannot be deleted or unset). */ - setHelpCommand(cmd: Command): void + deleteRecord(record: models.Record): void } - interface Command { + interface Dao { /** - * SetHelpCommandGroupID sets the group id of the help command. + * ExpandRecord expands the relations of a single Record model. + * + * If optFetchFunc is not set, then a default function will be used + * that returns all relation records. + * + * Returns a map with the failed expand parameters and their errors. */ - setHelpCommandGroupID(groupID: string): void + expandRecord(record: models.Record, expands: Array, optFetchFunc: ExpandFetchFunc): _TygojaDict } - interface Command { + interface Dao { /** - * SetCompletionCommandGroupID sets the group id of the completion command. + * ExpandRecords expands the relations of the provided Record models list. + * + * If optFetchFunc is not set, then a default function will be used + * that returns all relation records. + * + * Returns a map with the failed expand parameters and their errors. */ - setCompletionCommandGroupID(groupID: string): void + expandRecords(records: Array<(models.Record | undefined)>, expands: Array, optFetchFunc: ExpandFetchFunc): _TygojaDict } - interface Command { + // @ts-ignore + import validation = ozzo_validation + interface Dao { /** - * SetHelpTemplate sets help template to be used. Application can use it to set custom template. + * SyncRecordTableSchema compares the two provided collections + * and applies the necessary related record table changes. + * + * If `oldCollection` is null, then only `newCollection` is used to create the record table. */ - setHelpTemplate(s: string): void + syncRecordTableSchema(newCollection: models.Collection, oldCollection: models.Collection): void } - interface Command { + interface Dao { /** - * SetVersionTemplate sets version template to be used. Application can use it to set custom template. + * FindSettings returns and decode the serialized app settings param value. + * + * The method will first try to decode the param value without decryption. + * If it fails and optEncryptionKey is set, it will try again by first + * decrypting the value and then decode it again. + * + * Returns an error if it fails to decode the stored serialized param value. */ - setVersionTemplate(s: string): void + findSettings(...optEncryptionKey: string[]): (settings.Settings) } - interface Command { + interface Dao { /** - * SetErrPrefix sets error message prefix to be used. Application can use it to set custom prefix. + * SaveSettings persists the specified settings configuration. + * + * If optEncryptionKey is set, then the stored serialized value will be encrypted with it. */ - setErrPrefix(s: string): void + saveSettings(newSettings: settings.Settings, ...optEncryptionKey: string[]): void } - interface Command { + interface Dao { /** - * SetGlobalNormalizationFunc sets a normalization function to all flag sets and also to child commands. - * The user should not have a cyclic dependency on commands. + * HasTable checks if a table (or view) with the provided name exists (case insensitive). */ - setGlobalNormalizationFunc(n: (f: any, name: string) => any): void + hasTable(tableName: string): boolean } - interface Command { + interface Dao { /** - * OutOrStdout returns output to stdout. + * TableColumns returns all column names of a single table by its name. */ - outOrStdout(): io.Writer + tableColumns(tableName: string): Array } - interface Command { + interface Dao { /** - * OutOrStderr returns output to stderr + * TableInfo returns the `table_info` pragma result for the specified table. */ - outOrStderr(): io.Writer + tableInfo(tableName: string): Array<(models.TableInfoRow | undefined)> } - interface Command { + interface Dao { /** - * ErrOrStderr returns output to stderr + * TableIndexes returns a name grouped map with all non empty index of the specified table. + * + * Note: This method doesn't return an error on nonexisting table. */ - errOrStderr(): io.Writer + tableIndexes(tableName: string): _TygojaDict } - interface Command { + interface Dao { /** - * InOrStdin returns input to stdin + * DeleteTable drops the specified table. + * + * This method is a no-op if a table with the provided name doesn't exist. + * + * Be aware that this method is vulnerable to SQL injection and the + * "tableName" argument must come only from trusted input! */ - inOrStdin(): io.Reader + deleteTable(tableName: string): void } - interface Command { + interface Dao { /** - * UsageFunc returns either the function set by SetUsageFunc for this command - * or a parent, or it returns a default usage function. + * Vacuum executes VACUUM on the current dao.DB() instance in order to + * reclaim unused db disk space. */ - usageFunc(): (_arg0: Command) => void + vacuum(): void } - interface Command { + interface Dao { /** - * Usage puts out the usage for the command. - * Used when a user provides invalid input. - * Can be defined by user by overriding UsageFunc. + * DeleteView drops the specified view name. + * + * This method is a no-op if a view with the provided name doesn't exist. + * + * Be aware that this method is vulnerable to SQL injection and the + * "name" argument must come only from trusted input! */ - usage(): void + deleteView(name: string): void } - interface Command { + interface Dao { /** - * HelpFunc returns either the function set by SetHelpFunc for this command - * or a parent, or it returns a function with default help behavior. + * SaveView creates (or updates already existing) persistent SQL view. + * + * Be aware that this method is vulnerable to SQL injection and the + * "selectQuery" argument must come only from trusted input! */ - helpFunc(): (_arg0: Command, _arg1: Array) => void + saveView(name: string, selectQuery: string): void } - interface Command { + interface Dao { /** - * Help puts out the help for the command. - * Used when a user calls help [command]. - * Can be defined by user by overriding HelpFunc. + * CreateViewSchema creates a new view schema from the provided select query. + * + * There are some caveats: + * - The select query must have an "id" column. + * - Wildcard ("*") columns are not supported to avoid accidentally leaking sensitive data. */ - help(): void + createViewSchema(selectQuery: string): schema.Schema } - interface Command { + interface Dao { /** - * UsageString returns usage string. + * FindRecordByViewFile returns the original models.Record of the + * provided view collection file. */ - usageString(): string + findRecordByViewFile(viewCollectionNameOrId: string, fileFieldName: string, filename: string): (models.Record) } - interface Command { +} + +/** + * Package core is the backbone of PocketBase. + * + * It defines the main PocketBase App interface and its base implementation. + */ +namespace core { + /** + * App defines the main PocketBase app interface. + */ + interface App { + [key:string]: any; /** - * FlagErrorFunc returns either the function set by SetFlagErrorFunc for this - * command or a parent, or it returns a function which returns the original - * error. + * Deprecated: + * This method may get removed in the near future. + * It is recommended to access the app db instance from app.Dao().DB() or + * if you want more flexibility - app.Dao().ConcurrentDB() and app.Dao().NonconcurrentDB(). + * + * DB returns the default app database instance. */ - flagErrorFunc(): (_arg0: Command, _arg1: Error) => void - } - interface Command { + db(): (dbx.DB) /** - * UsagePadding return padding for the usage. + * Dao returns the default app Dao instance. + * + * This Dao could operate only on the tables and models + * associated with the default app database. For example, + * trying to access the request logs table will result in error. */ - usagePadding(): number - } - interface Command { + dao(): (daos.Dao) /** - * CommandPathPadding return padding for the command path. + * Deprecated: + * This method may get removed in the near future. + * It is recommended to access the logs db instance from app.LogsDao().DB() or + * if you want more flexibility - app.LogsDao().ConcurrentDB() and app.LogsDao().NonconcurrentDB(). + * + * LogsDB returns the app logs database instance. */ - commandPathPadding(): number - } - interface Command { + logsDB(): (dbx.DB) /** - * NamePadding returns padding for the name. + * LogsDao returns the app logs Dao instance. + * + * This Dao could operate only on the tables and models + * associated with the logs database. For example, trying to access + * the users table from LogsDao will result in error. */ - namePadding(): number - } - interface Command { + logsDao(): (daos.Dao) /** - * UsageTemplate returns usage template for the command. + * Logger returns the active app logger. */ - usageTemplate(): string - } - interface Command { + logger(): (slog.Logger) /** - * HelpTemplate return help template for the command. + * DataDir returns the app data directory path. */ - helpTemplate(): string - } - interface Command { + dataDir(): string /** - * VersionTemplate return version template for the command. + * EncryptionEnv returns the name of the app secret env key + * (used for settings encryption). */ - versionTemplate(): string - } - interface Command { + encryptionEnv(): string /** - * ErrPrefix return error message prefix for the command + * IsDev returns whether the app is in dev mode. */ - errPrefix(): string - } - interface Command { + isDev(): boolean /** - * Find the target command given the args and command tree - * Meant to be run on the highest node. Only searches down. + * Settings returns the loaded app settings. */ - find(args: Array): [(Command), Array] - } - interface Command { + settings(): (settings.Settings) /** - * Traverse the command tree to find the command, and parse args for - * each parent. + * Deprecated: Use app.Store() instead. */ - traverse(args: Array): [(Command), Array] - } - interface Command { + cache(): (store.Store) /** - * SuggestionsFor provides suggestions for the typedName. + * Store returns the app runtime store. */ - suggestionsFor(typedName: string): Array - } - interface Command { + store(): (store.Store) /** - * VisitParents visits all parents of the command and invokes fn on each parent. + * SubscriptionsBroker returns the app realtime subscriptions broker instance. */ - visitParents(fn: (_arg0: Command) => void): void - } - interface Command { + subscriptionsBroker(): (subscriptions.Broker) /** - * Root finds root command. + * NewMailClient creates and returns a configured app mail client. */ - root(): (Command) - } - interface Command { + newMailClient(): mailer.Mailer /** - * ArgsLenAtDash will return the length of c.Flags().Args at the moment - * when a -- was found during args parsing. + * NewFilesystem creates and returns a configured filesystem.System instance + * for managing regular app files (eg. collection uploads). + * + * NB! Make sure to call Close() on the returned result + * after you are done working with it. */ - argsLenAtDash(): number - } - interface Command { + newFilesystem(): (filesystem.System) /** - * ExecuteContext is the same as Execute(), but sets the ctx on the command. - * Retrieve ctx by calling cmd.Context() inside your *Run lifecycle or ValidArgs - * functions. + * NewBackupsFilesystem creates and returns a configured filesystem.System instance + * for managing app backups. + * + * NB! Make sure to call Close() on the returned result + * after you are done working with it. */ - executeContext(ctx: context.Context): void - } - interface Command { + newBackupsFilesystem(): (filesystem.System) /** - * Execute uses the args (os.Args[1:] by default) - * and run through the command tree finding appropriate matches - * for commands and then corresponding flags. + * RefreshSettings reinitializes and reloads the stored application settings. */ - execute(): void - } - interface Command { + refreshSettings(): void /** - * ExecuteContextC is the same as ExecuteC(), but sets the ctx on the command. - * Retrieve ctx by calling cmd.Context() inside your *Run lifecycle or ValidArgs - * functions. + * IsBootstrapped checks if the application was initialized + * (aka. whether Bootstrap() was called). */ - executeContextC(ctx: context.Context): (Command) - } - interface Command { + isBootstrapped(): boolean /** - * ExecuteC executes the command. + * Bootstrap takes care for initializing the application + * (open db connections, load settings, etc.). + * + * It will call ResetBootstrapState() if the application was already bootstrapped. */ - executeC(): (Command) - } - interface Command { - validateArgs(args: Array): void - } - interface Command { + bootstrap(): void /** - * ValidateRequiredFlags validates all required flags are present and returns an error otherwise + * ResetBootstrapState takes care for releasing initialized app resources + * (eg. closing db connections). */ - validateRequiredFlags(): void - } - interface Command { + resetBootstrapState(): void /** - * InitDefaultHelpFlag adds default help flag to c. - * It is called automatically by executing the c or by calling help and usage. - * If c already has help flag, it will do nothing. + * CreateBackup creates a new backup of the current app pb_data directory. + * + * Backups can be stored on S3 if it is configured in app.Settings().Backups. + * + * Please refer to the godoc of the specific CoreApp implementation + * for details on the backup procedures. */ - initDefaultHelpFlag(): void - } - interface Command { + createBackup(ctx: context.Context, name: string): void /** - * InitDefaultVersionFlag adds default version flag to c. - * It is called automatically by executing the c. - * If c already has a version flag, it will do nothing. - * If c.Version is empty, it will do nothing. + * RestoreBackup restores the backup with the specified name and restarts + * the current running application process. + * + * The safely perform the restore it is recommended to have free disk space + * for at least 2x the size of the restored pb_data backup. + * + * Please refer to the godoc of the specific CoreApp implementation + * for details on the restore procedures. + * + * NB! This feature is experimental and currently is expected to work only on UNIX based systems. */ - initDefaultVersionFlag(): void - } - interface Command { + restoreBackup(ctx: context.Context, name: string): void /** - * InitDefaultHelpCmd adds default help command to c. - * It is called automatically by executing the c or by calling help and usage. - * If c already has help command or c has no subcommands, it will do nothing. + * Restart restarts the current running application process. + * + * Currently it is relying on execve so it is supported only on UNIX based systems. */ - initDefaultHelpCmd(): void - } - interface Command { + restart(): void /** - * ResetCommands delete parent, subcommand and help command from c. + * OnBeforeBootstrap hook is triggered before initializing the main + * application resources (eg. before db open and initial settings load). */ - resetCommands(): void - } - interface Command { + onBeforeBootstrap(): (hook.Hook) /** - * Commands returns a sorted slice of child commands. + * OnAfterBootstrap hook is triggered after initializing the main + * application resources (eg. after db open and initial settings load). */ - commands(): Array<(Command | undefined)> - } - interface Command { + onAfterBootstrap(): (hook.Hook) /** - * AddCommand adds one or more commands to this parent command. + * OnBeforeServe hook is triggered before serving the internal router (echo), + * allowing you to adjust its options and attach new routes or middlewares. */ - addCommand(...cmds: (Command | undefined)[]): void - } - interface Command { + onBeforeServe(): (hook.Hook) /** - * Groups returns a slice of child command groups. + * OnBeforeApiError hook is triggered right before sending an error API + * response to the client, allowing you to further modify the error data + * or to return a completely different API response. */ - groups(): Array<(Group | undefined)> - } - interface Command { + onBeforeApiError(): (hook.Hook) /** - * AllChildCommandsHaveGroup returns if all subcommands are assigned to a group + * OnAfterApiError hook is triggered right after sending an error API + * response to the client. + * It could be used to log the final API error in external services. */ - allChildCommandsHaveGroup(): boolean - } - interface Command { + onAfterApiError(): (hook.Hook) /** - * ContainsGroup return if groupID exists in the list of command groups. + * OnTerminate hook is triggered when the app is in the process + * of being terminated (eg. on SIGTERM signal). */ - containsGroup(groupID: string): boolean - } - interface Command { + onTerminate(): (hook.Hook) /** - * AddGroup adds one or more command groups to this parent command. + * OnModelBeforeCreate hook is triggered before inserting a new + * model in the DB, allowing you to modify or validate the stored data. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - addGroup(...groups: (Group | undefined)[]): void - } - interface Command { + onModelBeforeCreate(...tags: string[]): (hook.TaggedHook) /** - * RemoveCommand removes one or more commands from a parent command. + * OnModelAfterCreate hook is triggered after successfully + * inserting a new model in the DB. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - removeCommand(...cmds: (Command | undefined)[]): void - } - interface Command { + onModelAfterCreate(...tags: string[]): (hook.TaggedHook) /** - * Print is a convenience method to Print to the defined output, fallback to Stderr if not set. + * OnModelBeforeUpdate hook is triggered before updating existing + * model in the DB, allowing you to modify or validate the stored data. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - print(...i: { - }[]): void - } - interface Command { + onModelBeforeUpdate(...tags: string[]): (hook.TaggedHook) /** - * Println is a convenience method to Println to the defined output, fallback to Stderr if not set. + * OnModelAfterUpdate hook is triggered after successfully updating + * existing model in the DB. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - println(...i: { - }[]): void - } - interface Command { + onModelAfterUpdate(...tags: string[]): (hook.TaggedHook) /** - * Printf is a convenience method to Printf to the defined output, fallback to Stderr if not set. + * OnModelBeforeDelete hook is triggered before deleting an + * existing model from the DB. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - printf(format: string, ...i: { - }[]): void - } - interface Command { + onModelBeforeDelete(...tags: string[]): (hook.TaggedHook) /** - * PrintErr is a convenience method to Print to the defined Err output, fallback to Stderr if not set. + * OnModelAfterDelete hook is triggered after successfully deleting an + * existing model from the DB. + * + * If the optional "tags" list (table names and/or the Collection id for Record models) + * is specified, then all event handlers registered via the created hook + * will be triggered and called only if their event data origin matches the tags. */ - printErr(...i: { - }[]): void - } - interface Command { + onModelAfterDelete(...tags: string[]): (hook.TaggedHook) /** - * PrintErrln is a convenience method to Println to the defined Err output, fallback to Stderr if not set. + * OnMailerBeforeAdminResetPasswordSend hook is triggered right + * before sending a password reset email to an admin, allowing you + * to inspect and customize the email message that is being sent. */ - printErrln(...i: { - }[]): void - } - interface Command { + onMailerBeforeAdminResetPasswordSend(): (hook.Hook) /** - * PrintErrf is a convenience method to Printf to the defined Err output, fallback to Stderr if not set. + * OnMailerAfterAdminResetPasswordSend hook is triggered after + * admin password reset email was successfully sent. */ - printErrf(format: string, ...i: { - }[]): void - } - interface Command { + onMailerAfterAdminResetPasswordSend(): (hook.Hook) /** - * CommandPath returns the full path to this command. + * OnMailerBeforeRecordResetPasswordSend hook is triggered right + * before sending a password reset email to an auth record, allowing + * you to inspect and customize the email message that is being sent. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - commandPath(): string - } - interface Command { + onMailerBeforeRecordResetPasswordSend(...tags: string[]): (hook.TaggedHook) /** - * UseLine puts out the full usage for a given command (including parents). + * OnMailerAfterRecordResetPasswordSend hook is triggered after + * an auth record password reset email was successfully sent. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - useLine(): string - } - interface Command { + onMailerAfterRecordResetPasswordSend(...tags: string[]): (hook.TaggedHook) /** - * DebugFlags used to determine which flags have been assigned to which commands - * and which persist. - * nolint:goconst + * OnMailerBeforeRecordVerificationSend hook is triggered right + * before sending a verification email to an auth record, allowing + * you to inspect and customize the email message that is being sent. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - debugFlags(): void - } - interface Command { + onMailerBeforeRecordVerificationSend(...tags: string[]): (hook.TaggedHook) /** - * Name returns the command's name: the first word in the use line. + * OnMailerAfterRecordVerificationSend hook is triggered after a + * verification email was successfully sent to an auth record. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - name(): string - } - interface Command { + onMailerAfterRecordVerificationSend(...tags: string[]): (hook.TaggedHook) /** - * HasAlias determines if a given string is an alias of the command. + * OnMailerBeforeRecordChangeEmailSend hook is triggered right before + * sending a confirmation new address email to an auth record, allowing + * you to inspect and customize the email message that is being sent. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - hasAlias(s: string): boolean - } - interface Command { + onMailerBeforeRecordChangeEmailSend(...tags: string[]): (hook.TaggedHook) /** - * CalledAs returns the command name or alias that was used to invoke - * this command or an empty string if the command has not been called. + * OnMailerAfterRecordChangeEmailSend hook is triggered after a + * verification email was successfully sent to an auth record. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - calledAs(): string - } - interface Command { + onMailerAfterRecordChangeEmailSend(...tags: string[]): (hook.TaggedHook) /** - * NameAndAliases returns a list of the command name and all aliases + * OnRealtimeConnectRequest hook is triggered right before establishing + * the SSE client connection. */ - nameAndAliases(): string - } - interface Command { + onRealtimeConnectRequest(): (hook.Hook) /** - * HasExample determines if the command has example. + * OnRealtimeDisconnectRequest hook is triggered on disconnected/interrupted + * SSE client connection. */ - hasExample(): boolean - } - interface Command { + onRealtimeDisconnectRequest(): (hook.Hook) /** - * Runnable determines if the command is itself runnable. + * OnRealtimeBeforeMessageSend hook is triggered right before sending + * an SSE message to a client. + * + * Returning [hook.StopPropagation] will prevent sending the message. + * Returning any other non-nil error will close the realtime connection. */ - runnable(): boolean - } - interface Command { + onRealtimeBeforeMessageSend(): (hook.Hook) /** - * HasSubCommands determines if the command has children commands. + * OnRealtimeAfterMessageSend hook is triggered right after sending + * an SSE message to a client. */ - hasSubCommands(): boolean - } - interface Command { + onRealtimeAfterMessageSend(): (hook.Hook) /** - * IsAvailableCommand determines if a command is available as a non-help command - * (this includes all non deprecated/hidden commands). + * OnRealtimeBeforeSubscribeRequest hook is triggered before changing + * the client subscriptions, allowing you to further validate and + * modify the submitted change. */ - isAvailableCommand(): boolean - } - interface Command { + onRealtimeBeforeSubscribeRequest(): (hook.Hook) /** - * IsAdditionalHelpTopicCommand determines if a command is an additional - * help topic command; additional help topic command is determined by the - * fact that it is NOT runnable/hidden/deprecated, and has no sub commands that - * are runnable/hidden/deprecated. - * Concrete example: https://github.com/spf13/cobra/issues/393#issuecomment-282741924. + * OnRealtimeAfterSubscribeRequest hook is triggered after the client + * subscriptions were successfully changed. */ - isAdditionalHelpTopicCommand(): boolean - } - interface Command { + onRealtimeAfterSubscribeRequest(): (hook.Hook) /** - * HasHelpSubCommands determines if a command has any available 'help' sub commands - * that need to be shown in the usage/help default template under 'additional help - * topics'. + * OnSettingsListRequest hook is triggered on each successful + * API Settings list request. + * + * Could be used to validate or modify the response before + * returning it to the client. */ - hasHelpSubCommands(): boolean - } - interface Command { + onSettingsListRequest(): (hook.Hook) /** - * HasAvailableSubCommands determines if a command has available sub commands that - * need to be shown in the usage/help default template under 'available commands'. + * OnSettingsBeforeUpdateRequest hook is triggered before each API + * Settings update request (after request data load and before settings persistence). + * + * Could be used to additionally validate the request data or + * implement completely different persistence behavior. */ - hasAvailableSubCommands(): boolean - } - interface Command { + onSettingsBeforeUpdateRequest(): (hook.Hook) /** - * HasParent determines if the command is a child command. + * OnSettingsAfterUpdateRequest hook is triggered after each + * successful API Settings update request. */ - hasParent(): boolean - } - interface Command { + onSettingsAfterUpdateRequest(): (hook.Hook) /** - * GlobalNormalizationFunc returns the global normalization function or nil if it doesn't exist. + * OnFileDownloadRequest hook is triggered before each API File download request. + * + * Could be used to validate or modify the file response before + * returning it to the client. */ - globalNormalizationFunc(): (f: any, name: string) => any - } - interface Command { + onFileDownloadRequest(...tags: string[]): (hook.TaggedHook) /** - * Flags returns the complete FlagSet that applies - * to this command (local and persistent declared here and by all parents). + * OnFileBeforeTokenRequest hook is triggered before each file + * token API request. + * + * If no token or model was submitted, e.Model and e.Token will be empty, + * allowing you to implement your own custom model file auth implementation. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - flags(): (any) - } - interface Command { + onFileBeforeTokenRequest(...tags: string[]): (hook.TaggedHook) /** - * LocalNonPersistentFlags are flags specific to this command which will NOT persist to subcommands. + * OnFileAfterTokenRequest hook is triggered after each + * successful file token API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - localNonPersistentFlags(): (any) - } - interface Command { + onFileAfterTokenRequest(...tags: string[]): (hook.TaggedHook) /** - * LocalFlags returns the local FlagSet specifically set in the current command. + * OnAdminsListRequest hook is triggered on each API Admins list request. + * + * Could be used to validate or modify the response before returning it to the client. */ - localFlags(): (any) - } - interface Command { + onAdminsListRequest(): (hook.Hook) /** - * InheritedFlags returns all flags which were inherited from parent commands. + * OnAdminViewRequest hook is triggered on each API Admin view request. + * + * Could be used to validate or modify the response before returning it to the client. */ - inheritedFlags(): (any) - } - interface Command { + onAdminViewRequest(): (hook.Hook) /** - * NonInheritedFlags returns all flags which were not inherited from parent commands. + * OnAdminBeforeCreateRequest hook is triggered before each API + * Admin create request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. */ - nonInheritedFlags(): (any) - } - interface Command { + onAdminBeforeCreateRequest(): (hook.Hook) /** - * PersistentFlags returns the persistent FlagSet specifically set in the current command. + * OnAdminAfterCreateRequest hook is triggered after each + * successful API Admin create request. */ - persistentFlags(): (any) - } - interface Command { + onAdminAfterCreateRequest(): (hook.Hook) /** - * ResetFlags deletes all flags from command. + * OnAdminBeforeUpdateRequest hook is triggered before each API + * Admin update request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. */ - resetFlags(): void - } - interface Command { + onAdminBeforeUpdateRequest(): (hook.Hook) /** - * HasFlags checks if the command contains any flags (local plus persistent from the entire structure). + * OnAdminAfterUpdateRequest hook is triggered after each + * successful API Admin update request. */ - hasFlags(): boolean - } - interface Command { + onAdminAfterUpdateRequest(): (hook.Hook) /** - * HasPersistentFlags checks if the command contains persistent flags. - */ - hasPersistentFlags(): boolean - } - interface Command { - /** - * HasLocalFlags checks if the command has flags specifically declared locally. + * OnAdminBeforeDeleteRequest hook is triggered before each API + * Admin delete request (after model load and before actual deletion). + * + * Could be used to additionally validate the request data or implement + * completely different delete behavior. */ - hasLocalFlags(): boolean - } - interface Command { + onAdminBeforeDeleteRequest(): (hook.Hook) /** - * HasInheritedFlags checks if the command has flags inherited from its parent command. + * OnAdminAfterDeleteRequest hook is triggered after each + * successful API Admin delete request. */ - hasInheritedFlags(): boolean - } - interface Command { + onAdminAfterDeleteRequest(): (hook.Hook) /** - * HasAvailableFlags checks if the command contains any flags (local plus persistent from the entire - * structure) which are not hidden or deprecated. + * OnAdminAuthRequest hook is triggered on each successful API Admin + * authentication request (sign-in, token refresh, etc.). + * + * Could be used to additionally validate or modify the + * authenticated admin data and token. */ - hasAvailableFlags(): boolean - } - interface Command { + onAdminAuthRequest(): (hook.Hook) /** - * HasAvailablePersistentFlags checks if the command contains persistent flags which are not hidden or deprecated. + * OnAdminBeforeAuthWithPasswordRequest hook is triggered before each Admin + * auth with password API request (after request data load and before password validation). + * + * Could be used to implement for example a custom password validation + * or to locate a different Admin identity (by assigning [AdminAuthWithPasswordEvent.Admin]). */ - hasAvailablePersistentFlags(): boolean - } - interface Command { + onAdminBeforeAuthWithPasswordRequest(): (hook.Hook) /** - * HasAvailableLocalFlags checks if the command has flags specifically declared locally which are not hidden - * or deprecated. + * OnAdminAfterAuthWithPasswordRequest hook is triggered after each + * successful Admin auth with password API request. */ - hasAvailableLocalFlags(): boolean - } - interface Command { + onAdminAfterAuthWithPasswordRequest(): (hook.Hook) /** - * HasAvailableInheritedFlags checks if the command has flags inherited from its parent command which are - * not hidden or deprecated. + * OnAdminBeforeAuthRefreshRequest hook is triggered before each Admin + * auth refresh API request (right before generating a new auth token). + * + * Could be used to additionally validate the request data or implement + * completely different auth refresh behavior. */ - hasAvailableInheritedFlags(): boolean - } - interface Command { + onAdminBeforeAuthRefreshRequest(): (hook.Hook) /** - * Flag climbs up the command tree looking for matching flag. + * OnAdminAfterAuthRefreshRequest hook is triggered after each + * successful auth refresh API request (right after generating a new auth token). */ - flag(name: string): (any) - } - interface Command { + onAdminAfterAuthRefreshRequest(): (hook.Hook) /** - * ParseFlags parses persistent flag tree and local flags. + * OnAdminBeforeRequestPasswordResetRequest hook is triggered before each Admin + * request password reset API request (after request data load and before sending the reset email). + * + * Could be used to additionally validate the request data or implement + * completely different password reset behavior. */ - parseFlags(args: Array): void - } - interface Command { + onAdminBeforeRequestPasswordResetRequest(): (hook.Hook) /** - * Parent returns a commands parent command. + * OnAdminAfterRequestPasswordResetRequest hook is triggered after each + * successful request password reset API request. */ - parent(): (Command) - } - interface Command { + onAdminAfterRequestPasswordResetRequest(): (hook.Hook) /** - * RegisterFlagCompletionFunc should be called to register a function to provide completion for a flag. + * OnAdminBeforeConfirmPasswordResetRequest hook is triggered before each Admin + * confirm password reset API request (after request data load and before persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. */ - registerFlagCompletionFunc(flagName: string, f: (cmd: Command, args: Array, toComplete: string) => [Array, ShellCompDirective]): void - } - interface Command { + onAdminBeforeConfirmPasswordResetRequest(): (hook.Hook) /** - * GetFlagCompletionFunc returns the completion function for the given flag of the command, if available. + * OnAdminAfterConfirmPasswordResetRequest hook is triggered after each + * successful confirm password reset API request. */ - getFlagCompletionFunc(flagName: string): [(_arg0: Command, _arg1: Array, _arg2: string) => [Array, ShellCompDirective], boolean] - } - interface Command { + onAdminAfterConfirmPasswordResetRequest(): (hook.Hook) /** - * InitDefaultCompletionCmd adds a default 'completion' command to c. - * This function will do nothing if any of the following is true: - * 1- the feature has been explicitly disabled by the program, - * 2- c has no subcommands (to avoid creating one), - * 3- c already has a 'completion' command provided by the program. + * OnRecordAuthRequest hook is triggered on each successful API + * record authentication request (sign-in, token refresh, etc.). + * + * Could be used to additionally validate or modify the authenticated + * record data and token. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - initDefaultCompletionCmd(): void - } - interface Command { + onRecordAuthRequest(...tags: string[]): (hook.TaggedHook) /** - * GenFishCompletion generates fish completion file and writes to the passed writer. + * OnRecordBeforeAuthWithPasswordRequest hook is triggered before each Record + * auth with password API request (after request data load and before password validation). + * + * Could be used to implement for example a custom password validation + * or to locate a different Record model (by reassigning [RecordAuthWithPasswordEvent.Record]). + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genFishCompletion(w: io.Writer, includeDesc: boolean): void - } - interface Command { + onRecordBeforeAuthWithPasswordRequest(...tags: string[]): (hook.TaggedHook) /** - * GenFishCompletionFile generates fish completion file. + * OnRecordAfterAuthWithPasswordRequest hook is triggered after each + * successful Record auth with password API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genFishCompletionFile(filename: string, includeDesc: boolean): void - } - interface Command { + onRecordAfterAuthWithPasswordRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagsRequiredTogether marks the given flags with annotations so that Cobra errors - * if the command is invoked with a subset (but not all) of the given flags. + * OnRecordBeforeAuthWithOAuth2Request hook is triggered before each Record + * OAuth2 sign-in/sign-up API request (after token exchange and before external provider linking). + * + * If the [RecordAuthWithOAuth2Event.Record] is not set, then the OAuth2 + * request will try to create a new auth Record. + * + * To assign or link a different existing record model you can + * change the [RecordAuthWithOAuth2Event.Record] field. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagsRequiredTogether(...flagNames: string[]): void - } - interface Command { + onRecordBeforeAuthWithOAuth2Request(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagsOneRequired marks the given flags with annotations so that Cobra errors - * if the command is invoked without at least one flag from the given set of flags. + * OnRecordAfterAuthWithOAuth2Request hook is triggered after each + * successful Record OAuth2 API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagsOneRequired(...flagNames: string[]): void - } - interface Command { + onRecordAfterAuthWithOAuth2Request(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagsMutuallyExclusive marks the given flags with annotations so that Cobra errors - * if the command is invoked with more than one flag from the given set of flags. + * OnRecordBeforeAuthRefreshRequest hook is triggered before each Record + * auth refresh API request (right before generating a new auth token). + * + * Could be used to additionally validate the request data or implement + * completely different auth refresh behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagsMutuallyExclusive(...flagNames: string[]): void - } - interface Command { + onRecordBeforeAuthRefreshRequest(...tags: string[]): (hook.TaggedHook) /** - * ValidateFlagGroups validates the mutuallyExclusive/oneRequired/requiredAsGroup logic and returns the - * first error encountered. + * OnRecordAfterAuthRefreshRequest hook is triggered after each + * successful auth refresh API request (right after generating a new auth token). + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - validateFlagGroups(): void - } - interface Command { + onRecordAfterAuthRefreshRequest(...tags: string[]): (hook.TaggedHook) /** - * GenPowerShellCompletionFile generates powershell completion file without descriptions. + * OnRecordListExternalAuthsRequest hook is triggered on each API record external auths list request. + * + * Could be used to validate or modify the response before returning it to the client. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genPowerShellCompletionFile(filename: string): void - } - interface Command { + onRecordListExternalAuthsRequest(...tags: string[]): (hook.TaggedHook) /** - * GenPowerShellCompletion generates powershell completion file without descriptions - * and writes it to the passed writer. + * OnRecordBeforeUnlinkExternalAuthRequest hook is triggered before each API record + * external auth unlink request (after models load and before the actual relation deletion). + * + * Could be used to additionally validate the request data or implement + * completely different delete behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genPowerShellCompletion(w: io.Writer): void - } - interface Command { + onRecordBeforeUnlinkExternalAuthRequest(...tags: string[]): (hook.TaggedHook) /** - * GenPowerShellCompletionFileWithDesc generates powershell completion file with descriptions. + * OnRecordAfterUnlinkExternalAuthRequest hook is triggered after each + * successful API record external auth unlink request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genPowerShellCompletionFileWithDesc(filename: string): void - } - interface Command { + onRecordAfterUnlinkExternalAuthRequest(...tags: string[]): (hook.TaggedHook) /** - * GenPowerShellCompletionWithDesc generates powershell completion file with descriptions - * and writes it to the passed writer. + * OnRecordBeforeRequestPasswordResetRequest hook is triggered before each Record + * request password reset API request (after request data load and before sending the reset email). + * + * Could be used to additionally validate the request data or implement + * completely different password reset behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genPowerShellCompletionWithDesc(w: io.Writer): void - } - interface Command { + onRecordBeforeRequestPasswordResetRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagRequired instructs the various shell completion implementations to - * prioritize the named flag when performing completion, - * and causes your command to report an error if invoked without the flag. + * OnRecordAfterRequestPasswordResetRequest hook is triggered after each + * successful request password reset API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagRequired(name: string): void - } - interface Command { + onRecordAfterRequestPasswordResetRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkPersistentFlagRequired instructs the various shell completion implementations to - * prioritize the named persistent flag when performing completion, - * and causes your command to report an error if invoked without the flag. + * OnRecordBeforeConfirmPasswordResetRequest hook is triggered before each Record + * confirm password reset API request (after request data load and before persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markPersistentFlagRequired(name: string): void - } - interface Command { + onRecordBeforeConfirmPasswordResetRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagFilename instructs the various shell completion implementations to - * limit completions for the named flag to the specified file extensions. + * OnRecordAfterConfirmPasswordResetRequest hook is triggered after each + * successful confirm password reset API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagFilename(name: string, ...extensions: string[]): void - } - interface Command { + onRecordAfterConfirmPasswordResetRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists. - * The bash completion script will call the bash function f for the flag. + * OnRecordBeforeRequestVerificationRequest hook is triggered before each Record + * request verification API request (after request data load and before sending the verification email). * - * This will only work for bash completion. - * It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows - * to register a Go function which will work across all shells. + * Could be used to additionally validate the loaded request data or implement + * completely different verification behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagCustom(name: string, f: string): void - } - interface Command { + onRecordBeforeRequestVerificationRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkPersistentFlagFilename instructs the various shell completion - * implementations to limit completions for the named persistent flag to the - * specified file extensions. + * OnRecordAfterRequestVerificationRequest hook is triggered after each + * successful request verification API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markPersistentFlagFilename(name: string, ...extensions: string[]): void - } - interface Command { + onRecordAfterRequestVerificationRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkFlagDirname instructs the various shell completion implementations to - * limit completions for the named flag to directory names. + * OnRecordBeforeConfirmVerificationRequest hook is triggered before each Record + * confirm verification API request (after request data load and before persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markFlagDirname(name: string): void - } - interface Command { + onRecordBeforeConfirmVerificationRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkPersistentFlagDirname instructs the various shell completion - * implementations to limit completions for the named persistent flag to - * directory names. + * OnRecordAfterConfirmVerificationRequest hook is triggered after each + * successful confirm verification API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markPersistentFlagDirname(name: string): void - } - interface Command { + onRecordAfterConfirmVerificationRequest(...tags: string[]): (hook.TaggedHook) /** - * GenZshCompletionFile generates zsh completion file including descriptions. + * OnRecordBeforeRequestEmailChangeRequest hook is triggered before each Record request email change API request + * (after request data load and before sending the email link to confirm the change). + * + * Could be used to additionally validate the request data or implement + * completely different request email change behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genZshCompletionFile(filename: string): void - } - interface Command { + onRecordBeforeRequestEmailChangeRequest(...tags: string[]): (hook.TaggedHook) /** - * GenZshCompletion generates zsh completion file including descriptions - * and writes it to the passed writer. + * OnRecordAfterRequestEmailChangeRequest hook is triggered after each + * successful request email change API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genZshCompletion(w: io.Writer): void - } - interface Command { + onRecordAfterRequestEmailChangeRequest(...tags: string[]): (hook.TaggedHook) /** - * GenZshCompletionFileNoDesc generates zsh completion file without descriptions. + * OnRecordBeforeConfirmEmailChangeRequest hook is triggered before each Record + * confirm email change API request (after request data load and before persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genZshCompletionFileNoDesc(filename: string): void - } - interface Command { + onRecordBeforeConfirmEmailChangeRequest(...tags: string[]): (hook.TaggedHook) /** - * GenZshCompletionNoDesc generates zsh completion file without descriptions - * and writes it to the passed writer. + * OnRecordAfterConfirmEmailChangeRequest hook is triggered after each + * successful confirm email change API request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - genZshCompletionNoDesc(w: io.Writer): void - } - interface Command { + onRecordAfterConfirmEmailChangeRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkZshCompPositionalArgumentFile only worked for zsh and its behavior was - * not consistent with Bash completion. It has therefore been disabled. - * Instead, when no other completion is specified, file completion is done by - * default for every argument. One can disable file completion on a per-argument - * basis by using ValidArgsFunction and ShellCompDirectiveNoFileComp. - * To achieve file extension filtering, one can use ValidArgsFunction and - * ShellCompDirectiveFilterFileExt. + * OnRecordsListRequest hook is triggered on each API Records list request. * - * Deprecated + * Could be used to validate or modify the response before returning it to the client. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markZshCompPositionalArgumentFile(argPosition: number, ...patterns: string[]): void - } - interface Command { + onRecordsListRequest(...tags: string[]): (hook.TaggedHook) /** - * MarkZshCompPositionalArgumentWords only worked for zsh. It has therefore - * been disabled. - * To achieve the same behavior across all shells, one can use - * ValidArgs (for the first argument only) or ValidArgsFunction for - * any argument (can include the first one also). + * OnRecordViewRequest hook is triggered on each API Record view request. * - * Deprecated + * Could be used to validate or modify the response before returning it to the client. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. */ - markZshCompPositionalArgumentWords(argPosition: number, ...words: string[]): void - } -} - -/** - * Package io provides basic interfaces to I/O primitives. - * Its primary job is to wrap existing implementations of such primitives, - * such as those in package os, into shared public interfaces that - * abstract the functionality, plus some other related primitives. - * - * Because these interfaces and primitives wrap lower-level operations with - * various implementations, unless otherwise informed clients should not - * assume they are safe for parallel execution. - */ -namespace io { - /** - * Writer is the interface that wraps the basic Write method. - * - * Write writes len(p) bytes from p to the underlying data stream. - * It returns the number of bytes written from p (0 <= n <= len(p)) - * and any error encountered that caused the write to stop early. - * Write must return a non-nil error if it returns n < len(p). - * Write must not modify the slice data, even temporarily. - * - * Implementations must not retain p. - */ - interface Writer { - [key:string]: any; - write(p: string|Array): number - } - /** - * ReadCloser is the interface that groups the basic Read and Close methods. - */ - interface ReadCloser { - [key:string]: any; - } - /** - * WriteCloser is the interface that groups the basic Write and Close methods. - */ - interface WriteCloser { - [key:string]: any; - } -} - -/** - * Package syscall contains an interface to the low-level operating system - * primitives. The details vary depending on the underlying system, and - * by default, godoc will display the syscall documentation for the current - * system. If you want godoc to display syscall documentation for another - * system, set $GOOS and $GOARCH to the desired system. For example, if - * you want to view documentation for freebsd/arm on linux/amd64, set $GOOS - * to freebsd and $GOARCH to arm. - * The primary use of syscall is inside other packages that provide a more - * portable interface to the system, such as "os", "time" and "net". Use - * those packages rather than this one if you can. - * For details of the functions and data types in this package consult - * the manuals for the appropriate operating system. - * These calls return err == nil to indicate success; otherwise - * err is an operating system error describing the failure. - * On most systems, that error has type syscall.Errno. - * - * Deprecated: this package is locked down. Callers should use the - * corresponding package in the golang.org/x/sys repository instead. - * That is also where updates required by new systems or versions - * should be applied. See https://golang.org/s/go1.4-syscall for more - * information. - */ -namespace syscall { - /** - * SysProcIDMap holds Container ID to Host ID mappings used for User Namespaces in Linux. - * See user_namespaces(7). - */ - interface SysProcIDMap { - containerID: number // Container ID. - hostID: number // Host ID. - size: number // Size. - } + onRecordViewRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordBeforeCreateRequest hook is triggered before each API Record + * create request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordBeforeCreateRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordAfterCreateRequest hook is triggered after each + * successful API Record create request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordAfterCreateRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordBeforeUpdateRequest hook is triggered before each API Record + * update request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordBeforeUpdateRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordAfterUpdateRequest hook is triggered after each + * successful API Record update request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordAfterUpdateRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordBeforeDeleteRequest hook is triggered before each API Record + * delete request (after model load and before actual deletion). + * + * Could be used to additionally validate the request data or implement + * completely different delete behavior. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordBeforeDeleteRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnRecordAfterDeleteRequest hook is triggered after each + * successful API Record delete request. + * + * If the optional "tags" list (Collection ids or names) is specified, + * then all event handlers registered via the created hook will be + * triggered and called only if their event data origin matches the tags. + */ + onRecordAfterDeleteRequest(...tags: string[]): (hook.TaggedHook) + /** + * OnCollectionsListRequest hook is triggered on each API Collections list request. + * + * Could be used to validate or modify the response before returning it to the client. + */ + onCollectionsListRequest(): (hook.Hook) + /** + * OnCollectionViewRequest hook is triggered on each API Collection view request. + * + * Could be used to validate or modify the response before returning it to the client. + */ + onCollectionViewRequest(): (hook.Hook) + /** + * OnCollectionBeforeCreateRequest hook is triggered before each API Collection + * create request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + */ + onCollectionBeforeCreateRequest(): (hook.Hook) + /** + * OnCollectionAfterCreateRequest hook is triggered after each + * successful API Collection create request. + */ + onCollectionAfterCreateRequest(): (hook.Hook) + /** + * OnCollectionBeforeUpdateRequest hook is triggered before each API Collection + * update request (after request data load and before model persistence). + * + * Could be used to additionally validate the request data or implement + * completely different persistence behavior. + */ + onCollectionBeforeUpdateRequest(): (hook.Hook) + /** + * OnCollectionAfterUpdateRequest hook is triggered after each + * successful API Collection update request. + */ + onCollectionAfterUpdateRequest(): (hook.Hook) + /** + * OnCollectionBeforeDeleteRequest hook is triggered before each API + * Collection delete request (after model load and before actual deletion). + * + * Could be used to additionally validate the request data or implement + * completely different delete behavior. + */ + onCollectionBeforeDeleteRequest(): (hook.Hook) + /** + * OnCollectionAfterDeleteRequest hook is triggered after each + * successful API Collection delete request. + */ + onCollectionAfterDeleteRequest(): (hook.Hook) + /** + * OnCollectionsBeforeImportRequest hook is triggered before each API + * collections import request (after request data load and before the actual import). + * + * Could be used to additionally validate the imported collections or + * to implement completely different import behavior. + */ + onCollectionsBeforeImportRequest(): (hook.Hook) + /** + * OnCollectionsAfterImportRequest hook is triggered after each + * successful API collections import request. + */ + onCollectionsAfterImportRequest(): (hook.Hook) + } +} + +/** + * Package io provides basic interfaces to I/O primitives. + * Its primary job is to wrap existing implementations of such primitives, + * such as those in package os, into shared public interfaces that + * abstract the functionality, plus some other related primitives. + * + * Because these interfaces and primitives wrap lower-level operations with + * various implementations, unless otherwise informed clients should not + * assume they are safe for parallel execution. + */ +namespace io { + /** + * Writer is the interface that wraps the basic Write method. + * + * Write writes len(p) bytes from p to the underlying data stream. + * It returns the number of bytes written from p (0 <= n <= len(p)) + * and any error encountered that caused the write to stop early. + * Write must return a non-nil error if it returns n < len(p). + * Write must not modify the slice data, even temporarily. + * + * Implementations must not retain p. + */ + interface Writer { + [key:string]: any; + write(p: string|Array): number + } + /** + * ReadCloser is the interface that groups the basic Read and Close methods. + */ + interface ReadCloser { + [key:string]: any; + } + /** + * WriteCloser is the interface that groups the basic Write and Close methods. + */ + interface WriteCloser { + [key:string]: any; + } +} + +/** + * Package syscall contains an interface to the low-level operating system + * primitives. The details vary depending on the underlying system, and + * by default, godoc will display the syscall documentation for the current + * system. If you want godoc to display syscall documentation for another + * system, set $GOOS and $GOARCH to the desired system. For example, if + * you want to view documentation for freebsd/arm on linux/amd64, set $GOOS + * to freebsd and $GOARCH to arm. + * The primary use of syscall is inside other packages that provide a more + * portable interface to the system, such as "os", "time" and "net". Use + * those packages rather than this one if you can. + * For details of the functions and data types in this package consult + * the manuals for the appropriate operating system. + * These calls return err == nil to indicate success; otherwise + * err is an operating system error describing the failure. + * On most systems, that error has type syscall.Errno. + * + * Deprecated: this package is locked down. Callers should use the + * corresponding package in the golang.org/x/sys repository instead. + * That is also where updates required by new systems or versions + * should be applied. See https://golang.org/s/go1.4-syscall for more + * information. + */ +namespace syscall { + /** + * SysProcIDMap holds Container ID to Host ID mappings used for User Namespaces in Linux. + * See user_namespaces(7). + */ + interface SysProcIDMap { + containerID: number // Container ID. + hostID: number // Host ID. + size: number // Size. + } // @ts-ignore import errorspkg = errors /** @@ -14627,6 +14647,14 @@ namespace time { } } +/** + * Package fs defines basic interfaces to a file system. + * A file system can be provided by the host operating system + * but also by other packages. + */ +namespace fs { +} + /** * Package context defines the Context type, which carries deadlines, * cancellation signals, and other request-scoped values across API boundaries @@ -14684,233 +14712,9 @@ namespace context { } /** - * Package fs defines basic interfaces to a file system. - * A file system can be provided by the host operating system - * but also by other packages. - */ -namespace fs { -} - -/** - * Package sql provides a generic interface around SQL (or SQL-like) - * databases. - * - * The sql package must be used in conjunction with a database driver. - * See https://golang.org/s/sqldrivers for a list of drivers. - * - * Drivers that do not support context cancellation will not return until - * after the query is completed. - * - * For usage examples, see the wiki page at - * https://golang.org/s/sqlwiki. + * Package url parses URLs and implements query escaping. */ -namespace sql { - /** - * IsolationLevel is the transaction isolation level used in TxOptions. - */ - interface IsolationLevel extends Number{} - interface IsolationLevel { - /** - * String returns the name of the transaction isolation level. - */ - string(): string - } - /** - * DBStats contains database statistics. - */ - interface DBStats { - maxOpenConnections: number // Maximum number of open connections to the database. - /** - * Pool Status - */ - openConnections: number // The number of established connections both in use and idle. - inUse: number // The number of connections currently in use. - idle: number // The number of idle connections. - /** - * Counters - */ - waitCount: number // The total number of connections waited for. - waitDuration: time.Duration // The total time blocked waiting for a new connection. - maxIdleClosed: number // The total number of connections closed due to SetMaxIdleConns. - maxIdleTimeClosed: number // The total number of connections closed due to SetConnMaxIdleTime. - maxLifetimeClosed: number // The total number of connections closed due to SetConnMaxLifetime. - } - /** - * Conn represents a single database connection rather than a pool of database - * connections. Prefer running queries from DB unless there is a specific - * need for a continuous single database connection. - * - * A Conn must call Close to return the connection to the database pool - * and may do so concurrently with a running query. - * - * After a call to Close, all operations on the - * connection fail with ErrConnDone. - */ - interface Conn { - } - interface Conn { - /** - * PingContext verifies the connection to the database is still alive. - */ - pingContext(ctx: context.Context): void - } - interface Conn { - /** - * ExecContext executes a query without returning any rows. - * The args are for any placeholder parameters in the query. - */ - execContext(ctx: context.Context, query: string, ...args: any[]): Result - } - interface Conn { - /** - * QueryContext executes a query that returns rows, typically a SELECT. - * The args are for any placeholder parameters in the query. - */ - queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) - } - interface Conn { - /** - * QueryRowContext executes a query that is expected to return at most one row. - * QueryRowContext always returns a non-nil value. Errors are deferred until - * Row's Scan method is called. - * If the query selects no rows, the *Row's Scan will return ErrNoRows. - * Otherwise, the *Row's Scan scans the first selected row and discards - * the rest. - */ - queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) - } - interface Conn { - /** - * PrepareContext creates a prepared statement for later queries or executions. - * Multiple queries or executions may be run concurrently from the - * returned statement. - * The caller must call the statement's Close method - * when the statement is no longer needed. - * - * The provided context is used for the preparation of the statement, not for the - * execution of the statement. - */ - prepareContext(ctx: context.Context, query: string): (Stmt) - } - interface Conn { - /** - * Raw executes f exposing the underlying driver connection for the - * duration of f. The driverConn must not be used outside of f. - * - * Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable - * until Conn.Close is called. - */ - raw(f: (driverConn: any) => void): void - } - interface Conn { - /** - * BeginTx starts a transaction. - * - * The provided context is used until the transaction is committed or rolled back. - * If the context is canceled, the sql package will roll back - * the transaction. Tx.Commit will return an error if the context provided to - * BeginTx is canceled. - * - * The provided TxOptions is optional and may be nil if defaults should be used. - * If a non-default isolation level is used that the driver doesn't support, - * an error will be returned. - */ - beginTx(ctx: context.Context, opts: TxOptions): (Tx) - } - interface Conn { - /** - * Close returns the connection to the connection pool. - * All operations after a Close will return with ErrConnDone. - * Close is safe to call concurrently with other operations and will - * block until all other operations finish. It may be useful to first - * cancel any used context and then call close directly after. - */ - close(): void - } - /** - * ColumnType contains the name and type of a column. - */ - interface ColumnType { - } - interface ColumnType { - /** - * Name returns the name or alias of the column. - */ - name(): string - } - interface ColumnType { - /** - * Length returns the column type length for variable length column types such - * as text and binary field types. If the type length is unbounded the value will - * be math.MaxInt64 (any database limits will still apply). - * If the column type is not variable length, such as an int, or if not supported - * by the driver ok is false. - */ - length(): [number, boolean] - } - interface ColumnType { - /** - * DecimalSize returns the scale and precision of a decimal type. - * If not applicable or if not supported ok is false. - */ - decimalSize(): [number, boolean] - } - interface ColumnType { - /** - * ScanType returns a Go type suitable for scanning into using Rows.Scan. - * If a driver does not support this property ScanType will return - * the type of an empty interface. - */ - scanType(): any - } - interface ColumnType { - /** - * Nullable reports whether the column may be null. - * If a driver does not support this property ok will be false. - */ - nullable(): boolean - } - interface ColumnType { - /** - * DatabaseTypeName returns the database system name of the column type. If an empty - * string is returned, then the driver type name is not supported. - * Consult your driver documentation for a list of driver data types. Length specifiers - * are not included. - * Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL", - * "INT", and "BIGINT". - */ - databaseTypeName(): string - } - /** - * Row is the result of calling QueryRow to select a single row. - */ - interface Row { - } - interface Row { - /** - * Scan copies the columns from the matched row into the values - * pointed at by dest. See the documentation on Rows.Scan for details. - * If more than one row matches the query, - * Scan uses the first row and discards the rest. If no row matches - * the query, Scan returns ErrNoRows. - */ - scan(...dest: any[]): void - } - interface Row { - /** - * Err provides a way for wrapping packages to check for - * query errors without calling Scan. - * Err returns the error, if any, that was encountered while running the query. - * If this error is not nil, this error will also be returned from Scan. - */ - err(): void - } -} - -/** - * Package url parses URLs and implements query escaping. - */ -namespace url { +namespace url { /** * A URL represents a parsed URL (technically, a URI reference). * @@ -15317,6 +15121,65 @@ namespace net { } } +/** + * Package types implements some commonly used db serializable types + * like datetime, json, etc. + */ +namespace types { + /** + * DateTime represents a [time.Time] instance in UTC that is wrapped + * and serialized using the app default date layout. + */ + interface DateTime { + } + interface DateTime { + /** + * Time returns the internal [time.Time] instance. + */ + time(): time.Time + } + interface DateTime { + /** + * IsZero checks whether the current DateTime instance has zero time value. + */ + isZero(): boolean + } + interface DateTime { + /** + * String serializes the current DateTime instance into a formatted + * UTC date string. + * + * The zero value is serialized to an empty string. + */ + string(): string + } + interface DateTime { + /** + * MarshalJSON implements the [json.Marshaler] interface. + */ + marshalJSON(): string|Array + } + interface DateTime { + /** + * UnmarshalJSON implements the [json.Unmarshaler] interface. + */ + unmarshalJSON(b: string|Array): void + } + interface DateTime { + /** + * Value implements the [driver.Valuer] interface. + */ + value(): any + } + interface DateTime { + /** + * Scan implements [sql.Scanner] interface to scan the provided value + * into the current DateTime instance. + */ + scan(value: any): void + } +} + /** * Package textproto implements generic support for text-based request/response * protocols in the style of HTTP, NNTP, and SMTP. @@ -15911,7 +15774,102 @@ namespace http { } } -namespace store { +/** + * Package oauth2 provides support for making + * OAuth2 authorized and authenticated HTTP requests, + * as specified in RFC 6749. + * It can additionally grant authorization with Bearer JWT. + */ +/** + * Copyright 2023 The Go Authors. All rights reserved. + * Use of this source code is governed by a BSD-style + * license that can be found in the LICENSE file. + */ +namespace oauth2 { + /** + * An AuthCodeOption is passed to Config.AuthCodeURL. + */ + interface AuthCodeOption { + [key:string]: any; + } + /** + * Token represents the credentials used to authorize + * the requests to access protected resources on the OAuth 2.0 + * provider's backend. + * + * Most users of this package should not access fields of Token + * directly. They're exported mostly for use by related packages + * implementing derivative OAuth2 flows. + */ + interface Token { + /** + * AccessToken is the token that authorizes and authenticates + * the requests. + */ + accessToken: string + /** + * TokenType is the type of token. + * The Type method returns either this or "Bearer", the default. + */ + tokenType: string + /** + * RefreshToken is a token that's used by the application + * (as opposed to the user) to refresh the access token + * if it expires. + */ + refreshToken: string + /** + * Expiry is the optional expiration time of the access token. + * + * If zero, TokenSource implementations will reuse the same + * token forever and RefreshToken or equivalent + * mechanisms for that TokenSource will not be used. + */ + expiry: time.Time + } + interface Token { + /** + * Type returns t.TokenType if non-empty, else "Bearer". + */ + type(): string + } + interface Token { + /** + * SetAuthHeader sets the Authorization header to r using the access + * token in t. + * + * This method is unnecessary when using Transport or an HTTP Client + * returned by this package. + */ + setAuthHeader(r: http.Request): void + } + interface Token { + /** + * WithExtra returns a new Token that's a clone of t, but using the + * provided raw extra map. This is only intended for use by packages + * implementing derivative OAuth2 flows. + */ + withExtra(extra: { + }): (Token) + } + interface Token { + /** + * Extra returns an extra field. + * Extra fields are key-value pairs returned by the server as a + * part of the token retrieval response. + */ + extra(key: string): { + } + } + interface Token { + /** + * Valid reports whether t is non-nil, has an AccessToken, and is not expired. + */ + valid(): boolean + } +} + +namespace store { /** * Store defines a concurrent safe in memory key-value data store. */ @@ -15982,1042 +15940,1104 @@ namespace store { } } +namespace mailer { + /** + * Mailer defines a base mail client interface. + */ + interface Mailer { + [key:string]: any; + /** + * Send sends an email with the provided Message. + */ + send(message: Message): void + } +} + /** - * Package types implements some commonly used db serializable types - * like datetime, json, etc. + * Package echo implements high performance, minimalist Go web framework. + * + * Example: + * + * ``` + * package main + * + * import ( + * "github.com/labstack/echo/v5" + * "github.com/labstack/echo/v5/middleware" + * "log" + * "net/http" + * ) + * + * // Handler + * func hello(c echo.Context) error { + * return c.String(http.StatusOK, "Hello, World!") + * } + * + * func main() { + * // Echo instance + * e := echo.New() + * + * // Middleware + * e.Use(middleware.Logger()) + * e.Use(middleware.Recover()) + * + * // Routes + * e.GET("/", hello) + * + * // Start server + * if err := e.Start(":8080"); err != http.ErrServerClosed { + * log.Fatal(err) + * } + * } + * ``` + * + * Learn more at https://echo.labstack.com */ -namespace types { +namespace echo { /** - * DateTime represents a [time.Time] instance in UTC that is wrapped - * and serialized using the app default date layout. + * Binder is the interface that wraps the Bind method. */ - interface DateTime { + interface Binder { + [key:string]: any; + bind(c: Context, i: { + }): void } - interface DateTime { + /** + * ServableContext is interface that Echo context implementation must implement to be usable in middleware/handlers and + * be able to be routed by Router. + */ + interface ServableContext { + [key:string]: any; /** - * Time returns the internal [time.Time] instance. + * Reset resets the context after request completes. It must be called along + * with `Echo#AcquireContext()` and `Echo#ReleaseContext()`. + * See `Echo#ServeHTTP()` */ - time(): time.Time + reset(r: http.Request, w: http.ResponseWriter): void } - interface DateTime { + // @ts-ignore + import stdContext = context + /** + * JSONSerializer is the interface that encodes and decodes JSON to and from interfaces. + */ + interface JSONSerializer { + [key:string]: any; + serialize(c: Context, i: { + }, indent: string): void + deserialize(c: Context, i: { + }): void + } + /** + * HTTPErrorHandler is a centralized HTTP error handler. + */ + interface HTTPErrorHandler {(c: Context, err: Error): void } + /** + * Validator is the interface that wraps the Validate function. + */ + interface Validator { + [key:string]: any; + validate(i: { + }): void + } + /** + * Renderer is the interface that wraps the Render function. + */ + interface Renderer { + [key:string]: any; + render(_arg0: io.Writer, _arg1: string, _arg2: { + }, _arg3: Context): void + } + /** + * Group is a set of sub-routes for a specified route. It can be used for inner + * routes that share a common middleware or functionality that should be separate + * from the parent echo instance while still inheriting from it. + */ + interface Group { + } + interface Group { /** - * IsZero checks whether the current DateTime instance has zero time value. + * Use implements `Echo#Use()` for sub-routes within the Group. + * Group middlewares are not executed on request when there is no matching route found. */ - isZero(): boolean + use(...middleware: MiddlewareFunc[]): void } - interface DateTime { + interface Group { /** - * String serializes the current DateTime instance into a formatted - * UTC date string. - * - * The zero value is serialized to an empty string. + * CONNECT implements `Echo#CONNECT()` for sub-routes within the Group. Panics on error. */ - string(): string + connect(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface DateTime { + interface Group { /** - * MarshalJSON implements the [json.Marshaler] interface. + * DELETE implements `Echo#DELETE()` for sub-routes within the Group. Panics on error. */ - marshalJSON(): string|Array + delete(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface DateTime { + interface Group { /** - * UnmarshalJSON implements the [json.Unmarshaler] interface. + * GET implements `Echo#GET()` for sub-routes within the Group. Panics on error. */ - unmarshalJSON(b: string|Array): void + get(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface DateTime { + interface Group { /** - * Value implements the [driver.Valuer] interface. + * HEAD implements `Echo#HEAD()` for sub-routes within the Group. Panics on error. */ - value(): any + head(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface DateTime { + interface Group { /** - * Scan implements [sql.Scanner] interface to scan the provided value - * into the current DateTime instance. + * OPTIONS implements `Echo#OPTIONS()` for sub-routes within the Group. Panics on error. */ - scan(value: any): void + options(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } -} - -/** - * Package schema implements custom Schema and SchemaField datatypes - * for handling the Collection schema definitions. - */ -namespace schema { - // @ts-ignore - import validation = ozzo_validation - /** - * SchemaField defines a single schema field structure. - */ - interface SchemaField { - system: boolean - id: string - name: string - type: string - required: boolean + interface Group { /** - * Presentable indicates whether the field is suitable for - * visualization purposes (eg. in the Admin UI relation views). + * PATCH implements `Echo#PATCH()` for sub-routes within the Group. Panics on error. */ - presentable: boolean + patch(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + } + interface Group { /** - * Deprecated: This field is no-op and will be removed in future versions. - * Please use the collection.Indexes field to define a unique constraint. + * POST implements `Echo#POST()` for sub-routes within the Group. Panics on error. */ - unique: boolean - options: any + post(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * ColDefinition returns the field db column type definition as string. + * PUT implements `Echo#PUT()` for sub-routes within the Group. Panics on error. */ - colDefinition(): string + put(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * String serializes and returns the current field as string. + * TRACE implements `Echo#TRACE()` for sub-routes within the Group. Panics on error. */ - string(): string + trace(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * MarshalJSON implements the [json.Marshaler] interface. + * Any implements `Echo#Any()` for sub-routes within the Group. Panics on error. */ - marshalJSON(): string|Array + any(path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes } - interface SchemaField { + interface Group { /** - * UnmarshalJSON implements the [json.Unmarshaler] interface. + * Match implements `Echo#Match()` for sub-routes within the Group. Panics on error. + */ + match(methods: Array, path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes + } + interface Group { + /** + * Group creates a new sub-group with prefix and optional sub-group-level middleware. + * Important! Group middlewares are only executed in case there was exact route match and not + * for 404 (not found) or 405 (method not allowed) cases. If this kind of behaviour is needed then add + * a catch-all route `/*` for the group which handler returns always 404 + */ + group(prefix: string, ...middleware: MiddlewareFunc[]): (Group) + } + interface Group { + /** + * Static implements `Echo#Static()` for sub-routes within the Group. + */ + static(pathPrefix: string): RouteInfo + } + interface Group { + /** + * StaticFS implements `Echo#StaticFS()` for sub-routes within the Group. * - * The schema field options are auto initialized on success. + * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary + * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths + * including `assets/images` as their prefix. */ - unmarshalJSON(data: string|Array): void + staticFS(pathPrefix: string, filesystem: fs.FS): RouteInfo } - interface SchemaField { + interface Group { /** - * Validate makes `SchemaField` validatable by implementing [validation.Validatable] interface. + * FileFS implements `Echo#FileFS()` for sub-routes within the Group. */ - validate(): void + fileFS(path: string, filesystem: fs.FS, ...m: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * InitOptions initializes the current field options based on its type. + * File implements `Echo#File()` for sub-routes within the Group. Panics on error. + */ + file(path: string, ...middleware: MiddlewareFunc[]): RouteInfo + } + interface Group { + /** + * RouteNotFound implements `Echo#RouteNotFound()` for sub-routes within the Group. * - * Returns error on unknown field type. + * Example: `g.RouteNotFound("/*", func(c echo.Context) error { return c.NoContent(http.StatusNotFound) })` */ - initOptions(): void + routeNotFound(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * PrepareValue returns normalized and properly formatted field value. + * Add implements `Echo#Add()` for sub-routes within the Group. Panics on error. */ - prepareValue(value: any): any + add(method: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): RouteInfo } - interface SchemaField { + interface Group { /** - * PrepareValueWithModifier returns normalized and properly formatted field value - * by "merging" baseValue with the modifierValue based on the specified modifier (+ or -). + * AddRoute registers a new Routable with Router */ - prepareValueWithModifier(baseValue: any, modifier: string, modifierValue: any): any + addRoute(route: Routable): RouteInfo } -} - -/** - * Package models implements all PocketBase DB models and DTOs. - */ -namespace models { /** - * Model defines an interface with common methods that all db models should have. + * IPExtractor is a function to extract IP addr from http.Request. + * Set appropriate one to Echo#IPExtractor. + * See https://echo.labstack.com/guide/ip-address for more details. */ - interface Model { + interface IPExtractor {(_arg0: http.Request): string } + /** + * Logger defines the logging interface that Echo uses internally in few places. + * For logging in handlers use your own logger instance (dependency injected or package/public variable) from logging framework of your choice. + */ + interface Logger { [key:string]: any; - tableName(): string - isNew(): boolean - markAsNew(): void - markAsNotNew(): void - hasId(): boolean - getId(): string - setId(id: string): void - getCreated(): types.DateTime - getUpdated(): types.DateTime - refreshId(): void - refreshCreated(): void - refreshUpdated(): void + /** + * Write provides writer interface for http.Server `ErrorLog` and for logging startup messages. + * `http.Server.ErrorLog` logs errors from accepting connections, unexpected behavior from handlers, + * and underlying FileSystem errors. + * `logger` middleware will use this method to write its JSON payload. + */ + write(p: string|Array): number + /** + * Error logs the error + */ + error(err: Error): void } /** - * BaseModel defines common fields and methods used by all other models. + * Response wraps an http.ResponseWriter and implements its interface to be used + * by an HTTP handler to construct an HTTP response. + * See: https://golang.org/pkg/net/http/#ResponseWriter */ - interface BaseModel { - id: string - created: types.DateTime - updated: types.DateTime + interface Response { + writer: http.ResponseWriter + status: number + size: number + committed: boolean } - interface BaseModel { + interface Response { /** - * HasId returns whether the model has a nonzero id. + * Header returns the header map for the writer that will be sent by + * WriteHeader. Changing the header after a call to WriteHeader (or Write) has + * no effect unless the modified headers were declared as trailers by setting + * the "Trailer" header before the call to WriteHeader (see example) + * To suppress implicit response headers, set their value to nil. + * Example: https://golang.org/pkg/net/http/#example_ResponseWriter_trailers */ - hasId(): boolean + header(): http.Header } - interface BaseModel { + interface Response { /** - * GetId returns the model id. + * Before registers a function which is called just before the response is written. */ - getId(): string + before(fn: () => void): void } - interface BaseModel { + interface Response { /** - * SetId sets the model id to the provided string value. + * After registers a function which is called just after the response is written. + * If the `Content-Length` is unknown, none of the after function is executed. */ - setId(id: string): void + after(fn: () => void): void } - interface BaseModel { + interface Response { /** - * MarkAsNew marks the model as "new" (aka. enforces m.IsNew() to be true). + * WriteHeader sends an HTTP response header with status code. If WriteHeader is + * not called explicitly, the first call to Write will trigger an implicit + * WriteHeader(http.StatusOK). Thus explicit calls to WriteHeader are mainly + * used to send error codes. */ - markAsNew(): void + writeHeader(code: number): void } - interface BaseModel { + interface Response { /** - * MarkAsNotNew marks the model as "not new" (aka. enforces m.IsNew() to be false) + * Write writes the data to the connection as part of an HTTP reply. */ - markAsNotNew(): void + write(b: string|Array): number } - interface BaseModel { + interface Response { /** - * IsNew indicates what type of db query (insert or update) - * should be used with the model instance. + * Flush implements the http.Flusher interface to allow an HTTP handler to flush + * buffered data to the client. + * See [http.Flusher](https://golang.org/pkg/net/http/#Flusher) */ - isNew(): boolean + flush(): void } - interface BaseModel { + interface Response { /** - * GetCreated returns the model Created datetime. + * Hijack implements the http.Hijacker interface to allow an HTTP handler to + * take over the connection. + * See [http.Hijacker](https://golang.org/pkg/net/http/#Hijacker) */ - getCreated(): types.DateTime + hijack(): [net.Conn, (bufio.ReadWriter)] } - interface BaseModel { + interface Response { /** - * GetUpdated returns the model Updated datetime. + * Unwrap returns the original http.ResponseWriter. + * ResponseController can be used to access the original http.ResponseWriter. + * See [https://go.dev/blog/go1.20] */ - getUpdated(): types.DateTime + unwrap(): http.ResponseWriter } - interface BaseModel { + interface Routes { /** - * RefreshId generates and sets a new model id. - * - * The generated id is a cryptographically random 15 characters length string. + * Reverse reverses route to URL string by replacing path parameters with given params values. */ - refreshId(): void + reverse(name: string, ...params: { + }[]): string } - interface BaseModel { + interface Routes { /** - * RefreshCreated updates the model Created field with the current datetime. + * FindByMethodPath searched for matching route info by method and path */ - refreshCreated(): void + findByMethodPath(method: string, path: string): RouteInfo } - interface BaseModel { + interface Routes { /** - * RefreshUpdated updates the model Updated field with the current datetime. + * FilterByMethod searched for matching route info by method */ - refreshUpdated(): void + filterByMethod(method: string): Routes } - interface BaseModel { + interface Routes { /** - * PostScan implements the [dbx.PostScanner] interface. - * - * It is executed right after the model was populated with the db row values. + * FilterByPath searched for matching route info by path */ - postScan(): void - } - // @ts-ignore - import validation = ozzo_validation - /** - * CollectionBaseOptions defines the "base" Collection.Options fields. - */ - interface CollectionBaseOptions { + filterByPath(path: string): Routes } - interface CollectionBaseOptions { + interface Routes { /** - * Validate implements [validation.Validatable] interface. + * FilterByName searched for matching route info by name */ - validate(): void + filterByName(name: string): Routes } /** - * CollectionAuthOptions defines the "auth" Collection.Options fields. + * Router is interface for routing request contexts to registered routes. + * + * Contract between Echo/Context instance and the router: + * ``` + * - all routes must be added through methods on echo.Echo instance. + * Reason: Echo instance uses RouteInfo.Params() length to allocate slice for paths parameters (see `Echo.contextPathParamAllocSize`). + * - Router must populate Context during Router.Route call with: + * - RoutableContext.SetPath + * - RoutableContext.SetRawPathParams (IMPORTANT! with same slice pointer that c.RawPathParams() returns) + * - RoutableContext.SetRouteInfo + * And optionally can set additional information to Context with RoutableContext.Set + * ``` */ - interface CollectionAuthOptions { - manageRule?: string - allowOAuth2Auth: boolean - allowUsernameAuth: boolean - allowEmailAuth: boolean - requireEmail: boolean - exceptEmailDomains: Array - onlyVerified: boolean - onlyEmailDomains: Array - minPasswordLength: number - } - interface CollectionAuthOptions { + interface Router { + [key:string]: any; /** - * Validate implements [validation.Validatable] interface. + * Add registers Routable with the Router and returns registered RouteInfo */ - validate(): void + add(routable: Routable): RouteInfo + /** + * Remove removes route from the Router + */ + remove(method: string, path: string): void + /** + * Routes returns information about all registered routes + */ + routes(): Routes + /** + * Route searches Router for matching route and applies it to the given context. In case when no matching method + * was not found (405) or no matching route exists for path (404), router will return its implementation of 405/404 + * handler function. + */ + route(c: RoutableContext): HandlerFunc } /** - * CollectionViewOptions defines the "view" Collection.Options fields. + * Routable is interface for registering Route with Router. During route registration process the Router will + * convert Routable to RouteInfo with ToRouteInfo method. By creating custom implementation of Routable additional + * information about registered route can be stored in Routes (i.e. privileges used with route etc.) */ - interface CollectionViewOptions { - query: string - } - interface CollectionViewOptions { + interface Routable { + [key:string]: any; /** - * Validate implements [validation.Validatable] interface. + * ToRouteInfo converts Routable to RouteInfo + * + * This method is meant to be used by Router after it parses url for path parameters, to store information about + * route just added. */ - validate(): void - } - type _subJyPpQ = BaseModel - interface Log extends _subJyPpQ { - data: types.JsonMap - message: string - level: number - } - interface Log { - tableName(): string - } - type _subsZwLm = BaseModel - interface Param extends _subsZwLm { - key: string - value: types.JsonRaw + toRouteInfo(params: Array): RouteInfo + /** + * ToRoute converts Routable to Route which Router uses to register the method handler for path. + * + * This method is meant to be used by Router to get fields (including handler and middleware functions) needed to + * add Route to Router. + */ + toRoute(): Route + /** + * ForGroup recreates routable with added group prefix and group middlewares it is grouped to. + * + * Is necessary for Echo.Group to be able to add/register Routable with Router and having group prefix and group + * middlewares included in actually registered Route. + */ + forGroup(pathPrefix: string, middlewares: Array): Routable } - interface Param { - tableName(): string + /** + * Routes is collection of RouteInfo instances with various helper methods. + */ + interface Routes extends Array{} + /** + * RouteInfo describes registered route base fields. + * Method+Path pair uniquely identifies the Route. Name can have duplicates. + */ + interface RouteInfo { + [key:string]: any; + method(): string + path(): string + name(): string + params(): Array + /** + * Reverse reverses route to URL string by replacing path parameters with given params values. + */ + reverse(...params: { + }[]): string } - interface TableInfoRow { + /** + * PathParams is collections of PathParam instances with various helper methods + */ + interface PathParams extends Array{} + interface PathParams { /** - * the `db:"pk"` tag has special semantic so we cannot rename - * the original field without specifying a custom mapper + * Get returns path parameter value for given name or default value. */ - pk: number - index: number - name: string - type: string - notNull: boolean - defaultValue: types.JsonRaw + get(name: string, defaultValue: string): string } } /** - * Package oauth2 provides support for making - * OAuth2 authorized and authenticated HTTP requests, - * as specified in RFC 6749. - * It can additionally grant authorization with Bearer JWT. - */ -/** - * Copyright 2023 The Go Authors. All rights reserved. - * Use of this source code is governed by a BSD-style - * license that can be found in the LICENSE file. + * Package sql provides a generic interface around SQL (or SQL-like) + * databases. + * + * The sql package must be used in conjunction with a database driver. + * See https://golang.org/s/sqldrivers for a list of drivers. + * + * Drivers that do not support context cancellation will not return until + * after the query is completed. + * + * For usage examples, see the wiki page at + * https://golang.org/s/sqlwiki. */ -namespace oauth2 { +namespace sql { /** - * An AuthCodeOption is passed to Config.AuthCodeURL. + * IsolationLevel is the transaction isolation level used in TxOptions. */ - interface AuthCodeOption { - [key:string]: any; + interface IsolationLevel extends Number{} + interface IsolationLevel { + /** + * String returns the name of the transaction isolation level. + */ + string(): string } /** - * Token represents the credentials used to authorize - * the requests to access protected resources on the OAuth 2.0 - * provider's backend. - * - * Most users of this package should not access fields of Token - * directly. They're exported mostly for use by related packages - * implementing derivative OAuth2 flows. + * DBStats contains database statistics. */ - interface Token { + interface DBStats { + maxOpenConnections: number // Maximum number of open connections to the database. /** - * AccessToken is the token that authorizes and authenticates - * the requests. + * Pool Status */ - accessToken: string + openConnections: number // The number of established connections both in use and idle. + inUse: number // The number of connections currently in use. + idle: number // The number of idle connections. /** - * TokenType is the type of token. - * The Type method returns either this or "Bearer", the default. + * Counters */ - tokenType: string + waitCount: number // The total number of connections waited for. + waitDuration: time.Duration // The total time blocked waiting for a new connection. + maxIdleClosed: number // The total number of connections closed due to SetMaxIdleConns. + maxIdleTimeClosed: number // The total number of connections closed due to SetConnMaxIdleTime. + maxLifetimeClosed: number // The total number of connections closed due to SetConnMaxLifetime. + } + /** + * Conn represents a single database connection rather than a pool of database + * connections. Prefer running queries from DB unless there is a specific + * need for a continuous single database connection. + * + * A Conn must call Close to return the connection to the database pool + * and may do so concurrently with a running query. + * + * After a call to Close, all operations on the + * connection fail with ErrConnDone. + */ + interface Conn { + } + interface Conn { /** - * RefreshToken is a token that's used by the application - * (as opposed to the user) to refresh the access token - * if it expires. + * PingContext verifies the connection to the database is still alive. */ - refreshToken: string + pingContext(ctx: context.Context): void + } + interface Conn { /** - * Expiry is the optional expiration time of the access token. - * - * If zero, TokenSource implementations will reuse the same - * token forever and RefreshToken or equivalent - * mechanisms for that TokenSource will not be used. + * ExecContext executes a query without returning any rows. + * The args are for any placeholder parameters in the query. */ - expiry: time.Time + execContext(ctx: context.Context, query: string, ...args: any[]): Result } - interface Token { + interface Conn { /** - * Type returns t.TokenType if non-empty, else "Bearer". + * QueryContext executes a query that returns rows, typically a SELECT. + * The args are for any placeholder parameters in the query. */ - type(): string + queryContext(ctx: context.Context, query: string, ...args: any[]): (Rows) } - interface Token { + interface Conn { /** - * SetAuthHeader sets the Authorization header to r using the access - * token in t. - * - * This method is unnecessary when using Transport or an HTTP Client - * returned by this package. + * QueryRowContext executes a query that is expected to return at most one row. + * QueryRowContext always returns a non-nil value. Errors are deferred until + * Row's Scan method is called. + * If the query selects no rows, the *Row's Scan will return ErrNoRows. + * Otherwise, the *Row's Scan scans the first selected row and discards + * the rest. */ - setAuthHeader(r: http.Request): void + queryRowContext(ctx: context.Context, query: string, ...args: any[]): (Row) } - interface Token { + interface Conn { /** - * WithExtra returns a new Token that's a clone of t, but using the - * provided raw extra map. This is only intended for use by packages - * implementing derivative OAuth2 flows. + * PrepareContext creates a prepared statement for later queries or executions. + * Multiple queries or executions may be run concurrently from the + * returned statement. + * The caller must call the statement's Close method + * when the statement is no longer needed. + * + * The provided context is used for the preparation of the statement, not for the + * execution of the statement. */ - withExtra(extra: { - }): (Token) + prepareContext(ctx: context.Context, query: string): (Stmt) } - interface Token { + interface Conn { /** - * Extra returns an extra field. - * Extra fields are key-value pairs returned by the server as a - * part of the token retrieval response. + * Raw executes f exposing the underlying driver connection for the + * duration of f. The driverConn must not be used outside of f. + * + * Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable + * until Conn.Close is called. */ - extra(key: string): { - } + raw(f: (driverConn: any) => void): void } - interface Token { + interface Conn { /** - * Valid reports whether t is non-nil, has an AccessToken, and is not expired. + * BeginTx starts a transaction. + * + * The provided context is used until the transaction is committed or rolled back. + * If the context is canceled, the sql package will roll back + * the transaction. Tx.Commit will return an error if the context provided to + * BeginTx is canceled. + * + * The provided TxOptions is optional and may be nil if defaults should be used. + * If a non-default isolation level is used that the driver doesn't support, + * an error will be returned. */ - valid(): boolean + beginTx(ctx: context.Context, opts: TxOptions): (Tx) } -} - -namespace mailer { - /** - * Mailer defines a base mail client interface. - */ - interface Mailer { - [key:string]: any; + interface Conn { /** - * Send sends an email with the provided Message. + * Close returns the connection to the connection pool. + * All operations after a Close will return with ErrConnDone. + * Close is safe to call concurrently with other operations and will + * block until all other operations finish. It may be useful to first + * cancel any used context and then call close directly after. */ - send(message: Message): void + close(): void } -} - -/** - * Package echo implements high performance, minimalist Go web framework. - * - * Example: - * - * ``` - * package main - * - * import ( - * "github.com/labstack/echo/v5" - * "github.com/labstack/echo/v5/middleware" - * "log" - * "net/http" - * ) - * - * // Handler - * func hello(c echo.Context) error { - * return c.String(http.StatusOK, "Hello, World!") - * } - * - * func main() { - * // Echo instance - * e := echo.New() - * - * // Middleware - * e.Use(middleware.Logger()) - * e.Use(middleware.Recover()) - * - * // Routes - * e.GET("/", hello) - * - * // Start server - * if err := e.Start(":8080"); err != http.ErrServerClosed { - * log.Fatal(err) - * } - * } - * ``` - * - * Learn more at https://echo.labstack.com - */ -namespace echo { /** - * Binder is the interface that wraps the Bind method. + * ColumnType contains the name and type of a column. */ - interface Binder { - [key:string]: any; - bind(c: Context, i: { - }): void + interface ColumnType { } - /** - * ServableContext is interface that Echo context implementation must implement to be usable in middleware/handlers and - * be able to be routed by Router. - */ - interface ServableContext { - [key:string]: any; + interface ColumnType { /** - * Reset resets the context after request completes. It must be called along - * with `Echo#AcquireContext()` and `Echo#ReleaseContext()`. - * See `Echo#ServeHTTP()` + * Name returns the name or alias of the column. */ - reset(r: http.Request, w: http.ResponseWriter): void - } - // @ts-ignore - import stdContext = context - /** - * JSONSerializer is the interface that encodes and decodes JSON to and from interfaces. - */ - interface JSONSerializer { - [key:string]: any; - serialize(c: Context, i: { - }, indent: string): void - deserialize(c: Context, i: { - }): void - } - /** - * HTTPErrorHandler is a centralized HTTP error handler. - */ - interface HTTPErrorHandler {(c: Context, err: Error): void } - /** - * Validator is the interface that wraps the Validate function. - */ - interface Validator { - [key:string]: any; - validate(i: { - }): void - } - /** - * Renderer is the interface that wraps the Render function. - */ - interface Renderer { - [key:string]: any; - render(_arg0: io.Writer, _arg1: string, _arg2: { - }, _arg3: Context): void - } - /** - * Group is a set of sub-routes for a specified route. It can be used for inner - * routes that share a common middleware or functionality that should be separate - * from the parent echo instance while still inheriting from it. - */ - interface Group { + name(): string } - interface Group { + interface ColumnType { /** - * Use implements `Echo#Use()` for sub-routes within the Group. - * Group middlewares are not executed on request when there is no matching route found. + * Length returns the column type length for variable length column types such + * as text and binary field types. If the type length is unbounded the value will + * be math.MaxInt64 (any database limits will still apply). + * If the column type is not variable length, such as an int, or if not supported + * by the driver ok is false. */ - use(...middleware: MiddlewareFunc[]): void + length(): [number, boolean] } - interface Group { + interface ColumnType { /** - * CONNECT implements `Echo#CONNECT()` for sub-routes within the Group. Panics on error. + * DecimalSize returns the scale and precision of a decimal type. + * If not applicable or if not supported ok is false. */ - connect(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + decimalSize(): [number, boolean] } - interface Group { + interface ColumnType { /** - * DELETE implements `Echo#DELETE()` for sub-routes within the Group. Panics on error. + * ScanType returns a Go type suitable for scanning into using Rows.Scan. + * If a driver does not support this property ScanType will return + * the type of an empty interface. */ - delete(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + scanType(): any } - interface Group { + interface ColumnType { /** - * GET implements `Echo#GET()` for sub-routes within the Group. Panics on error. + * Nullable reports whether the column may be null. + * If a driver does not support this property ok will be false. */ - get(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + nullable(): boolean } - interface Group { + interface ColumnType { /** - * HEAD implements `Echo#HEAD()` for sub-routes within the Group. Panics on error. + * DatabaseTypeName returns the database system name of the column type. If an empty + * string is returned, then the driver type name is not supported. + * Consult your driver documentation for a list of driver data types. Length specifiers + * are not included. + * Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL", + * "INT", and "BIGINT". */ - head(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + databaseTypeName(): string } - interface Group { + /** + * Row is the result of calling QueryRow to select a single row. + */ + interface Row { + } + interface Row { /** - * OPTIONS implements `Echo#OPTIONS()` for sub-routes within the Group. Panics on error. + * Scan copies the columns from the matched row into the values + * pointed at by dest. See the documentation on Rows.Scan for details. + * If more than one row matches the query, + * Scan uses the first row and discards the rest. If no row matches + * the query, Scan returns ErrNoRows. */ - options(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + scan(...dest: any[]): void } - interface Group { + interface Row { /** - * PATCH implements `Echo#PATCH()` for sub-routes within the Group. Panics on error. + * Err provides a way for wrapping packages to check for + * query errors without calling Scan. + * Err returns the error, if any, that was encountered while running the query. + * If this error is not nil, this error will also be returned from Scan. */ - patch(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + err(): void } - interface Group { +} + +namespace settings { + // @ts-ignore + import validation = ozzo_validation + interface TokenConfig { + secret: string + duration: number + } + interface TokenConfig { /** - * POST implements `Echo#POST()` for sub-routes within the Group. Panics on error. + * Validate makes TokenConfig validatable by implementing [validation.Validatable] interface. */ - post(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + validate(): void } - interface Group { + interface SmtpConfig { + enabled: boolean + host: string + port: number + username: string + password: string /** - * PUT implements `Echo#PUT()` for sub-routes within the Group. Panics on error. + * SMTP AUTH - PLAIN (default) or LOGIN */ - put(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Group { + authMethod: string /** - * TRACE implements `Echo#TRACE()` for sub-routes within the Group. Panics on error. + * Whether to enforce TLS encryption for the mail server connection. + * + * When set to false StartTLS command is send, leaving the server + * to decide whether to upgrade the connection or not. */ - trace(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo - } - interface Group { + tls: boolean /** - * Any implements `Echo#Any()` for sub-routes within the Group. Panics on error. + * LocalName is optional domain name or IP address used for the + * EHLO/HELO exchange (if not explicitly set, defaults to "localhost"). + * + * This is required only by some SMTP servers, such as Gmail SMTP-relay. */ - any(path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes + localName: string } - interface Group { + interface SmtpConfig { /** - * Match implements `Echo#Match()` for sub-routes within the Group. Panics on error. + * Validate makes SmtpConfig validatable by implementing [validation.Validatable] interface. */ - match(methods: Array, path: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): Routes + validate(): void } - interface Group { - /** - * Group creates a new sub-group with prefix and optional sub-group-level middleware. - * Important! Group middlewares are only executed in case there was exact route match and not - * for 404 (not found) or 405 (method not allowed) cases. If this kind of behaviour is needed then add - * a catch-all route `/*` for the group which handler returns always 404 - */ - group(prefix: string, ...middleware: MiddlewareFunc[]): (Group) + interface S3Config { + enabled: boolean + bucket: string + region: string + endpoint: string + accessKey: string + secret: string + forcePathStyle: boolean } - interface Group { + interface S3Config { /** - * Static implements `Echo#Static()` for sub-routes within the Group. + * Validate makes S3Config validatable by implementing [validation.Validatable] interface. */ - static(pathPrefix: string): RouteInfo + validate(): void } - interface Group { + interface BackupsConfig { /** - * StaticFS implements `Echo#StaticFS()` for sub-routes within the Group. + * Cron is a cron expression to schedule auto backups, eg. "* * * * *". * - * When dealing with `embed.FS` use `fs := echo.MustSubFS(fs, "rootDirectory") to create sub fs which uses necessary - * prefix for directory path. This is necessary as `//go:embed assets/images` embeds files with paths - * including `assets/images` as their prefix. + * Leave it empty to disable the auto backups functionality. */ - staticFS(pathPrefix: string, filesystem: fs.FS): RouteInfo - } - interface Group { + cron: string /** - * FileFS implements `Echo#FileFS()` for sub-routes within the Group. + * CronMaxKeep is the the max number of cron generated backups to + * keep before removing older entries. + * + * This field works only when the cron config has valid cron expression. */ - fileFS(path: string, filesystem: fs.FS, ...m: MiddlewareFunc[]): RouteInfo - } - interface Group { + cronMaxKeep: number /** - * File implements `Echo#File()` for sub-routes within the Group. Panics on error. + * S3 is an optional S3 storage config specifying where to store the app backups. */ - file(path: string, ...middleware: MiddlewareFunc[]): RouteInfo + s3: S3Config } - interface Group { + interface BackupsConfig { /** - * RouteNotFound implements `Echo#RouteNotFound()` for sub-routes within the Group. - * - * Example: `g.RouteNotFound("/*", func(c echo.Context) error { return c.NoContent(http.StatusNotFound) })` + * Validate makes BackupsConfig validatable by implementing [validation.Validatable] interface. */ - routeNotFound(path: string, h: HandlerFunc, ...m: MiddlewareFunc[]): RouteInfo + validate(): void } - interface Group { + interface MetaConfig { + appName: string + appUrl: string + hideControls: boolean + senderName: string + senderAddress: string + verificationTemplate: EmailTemplate + resetPasswordTemplate: EmailTemplate + confirmEmailChangeTemplate: EmailTemplate + } + interface MetaConfig { /** - * Add implements `Echo#Add()` for sub-routes within the Group. Panics on error. + * Validate makes MetaConfig validatable by implementing [validation.Validatable] interface. */ - add(method: string, handler: HandlerFunc, ...middleware: MiddlewareFunc[]): RouteInfo + validate(): void } - interface Group { + interface LogsConfig { + maxDays: number + minLevel: number + logIp: boolean + } + interface LogsConfig { /** - * AddRoute registers a new Routable with Router + * Validate makes LogsConfig validatable by implementing [validation.Validatable] interface. */ - addRoute(route: Routable): RouteInfo + validate(): void } - /** - * IPExtractor is a function to extract IP addr from http.Request. - * Set appropriate one to Echo#IPExtractor. - * See https://echo.labstack.com/guide/ip-address for more details. - */ - interface IPExtractor {(_arg0: http.Request): string } - /** - * Logger defines the logging interface that Echo uses internally in few places. - * For logging in handlers use your own logger instance (dependency injected or package/public variable) from logging framework of your choice. - */ - interface Logger { - [key:string]: any; + interface AuthProviderConfig { + enabled: boolean + clientId: string + clientSecret: string + authUrl: string + tokenUrl: string + userApiUrl: string + displayName: string + pkce?: boolean + } + interface AuthProviderConfig { /** - * Write provides writer interface for http.Server `ErrorLog` and for logging startup messages. - * `http.Server.ErrorLog` logs errors from accepting connections, unexpected behavior from handlers, - * and underlying FileSystem errors. - * `logger` middleware will use this method to write its JSON payload. + * Validate makes `ProviderConfig` validatable by implementing [validation.Validatable] interface. */ - write(p: string|Array): number + validate(): void + } + interface AuthProviderConfig { /** - * Error logs the error + * SetupProvider loads the current AuthProviderConfig into the specified provider. */ - error(err: Error): void + setupProvider(provider: auth.Provider): void } /** - * Response wraps an http.ResponseWriter and implements its interface to be used - * by an HTTP handler to construct an HTTP response. - * See: https://golang.org/pkg/net/http/#ResponseWriter + * Deprecated: Will be removed in v0.9+ */ - interface Response { - writer: http.ResponseWriter - status: number - size: number - committed: boolean - } - interface Response { - /** - * Header returns the header map for the writer that will be sent by - * WriteHeader. Changing the header after a call to WriteHeader (or Write) has - * no effect unless the modified headers were declared as trailers by setting - * the "Trailer" header before the call to WriteHeader (see example) - * To suppress implicit response headers, set their value to nil. - * Example: https://golang.org/pkg/net/http/#example_ResponseWriter_trailers - */ - header(): http.Header + interface EmailAuthConfig { + enabled: boolean + exceptDomains: Array + onlyDomains: Array + minPasswordLength: number } - interface Response { + interface EmailAuthConfig { /** - * Before registers a function which is called just before the response is written. + * Deprecated: Will be removed in v0.9+ */ - before(fn: () => void): void + validate(): void } - interface Response { +} + +/** + * Package schema implements custom Schema and SchemaField datatypes + * for handling the Collection schema definitions. + */ +namespace schema { + // @ts-ignore + import validation = ozzo_validation + /** + * SchemaField defines a single schema field structure. + */ + interface SchemaField { + system: boolean + id: string + name: string + type: string + required: boolean /** - * After registers a function which is called just after the response is written. - * If the `Content-Length` is unknown, none of the after function is executed. + * Presentable indicates whether the field is suitable for + * visualization purposes (eg. in the Admin UI relation views). */ - after(fn: () => void): void - } - interface Response { + presentable: boolean /** - * WriteHeader sends an HTTP response header with status code. If WriteHeader is - * not called explicitly, the first call to Write will trigger an implicit - * WriteHeader(http.StatusOK). Thus explicit calls to WriteHeader are mainly - * used to send error codes. + * Deprecated: This field is no-op and will be removed in future versions. + * Please use the collection.Indexes field to define a unique constraint. */ - writeHeader(code: number): void + unique: boolean + options: any } - interface Response { + interface SchemaField { /** - * Write writes the data to the connection as part of an HTTP reply. + * ColDefinition returns the field db column type definition as string. */ - write(b: string|Array): number + colDefinition(): string } - interface Response { + interface SchemaField { /** - * Flush implements the http.Flusher interface to allow an HTTP handler to flush - * buffered data to the client. - * See [http.Flusher](https://golang.org/pkg/net/http/#Flusher) + * String serializes and returns the current field as string. */ - flush(): void + string(): string } - interface Response { + interface SchemaField { /** - * Hijack implements the http.Hijacker interface to allow an HTTP handler to - * take over the connection. - * See [http.Hijacker](https://golang.org/pkg/net/http/#Hijacker) + * MarshalJSON implements the [json.Marshaler] interface. */ - hijack(): [net.Conn, (bufio.ReadWriter)] + marshalJSON(): string|Array } - interface Response { + interface SchemaField { /** - * Unwrap returns the original http.ResponseWriter. - * ResponseController can be used to access the original http.ResponseWriter. - * See [https://go.dev/blog/go1.20] + * UnmarshalJSON implements the [json.Unmarshaler] interface. + * + * The schema field options are auto initialized on success. */ - unwrap(): http.ResponseWriter + unmarshalJSON(data: string|Array): void } - interface Routes { + interface SchemaField { /** - * Reverse reverses route to URL string by replacing path parameters with given params values. + * Validate makes `SchemaField` validatable by implementing [validation.Validatable] interface. */ - reverse(name: string, ...params: { - }[]): string + validate(): void } - interface Routes { + interface SchemaField { /** - * FindByMethodPath searched for matching route info by method and path + * InitOptions initializes the current field options based on its type. + * + * Returns error on unknown field type. */ - findByMethodPath(method: string, path: string): RouteInfo + initOptions(): void } - interface Routes { + interface SchemaField { /** - * FilterByMethod searched for matching route info by method + * PrepareValue returns normalized and properly formatted field value. */ - filterByMethod(method: string): Routes + prepareValue(value: any): any } - interface Routes { + interface SchemaField { /** - * FilterByPath searched for matching route info by path + * PrepareValueWithModifier returns normalized and properly formatted field value + * by "merging" baseValue with the modifierValue based on the specified modifier (+ or -). */ - filterByPath(path: string): Routes - } - interface Routes { - /** - * FilterByName searched for matching route info by name - */ - filterByName(name: string): Routes + prepareValueWithModifier(baseValue: any, modifier: string, modifierValue: any): any } +} + +/** + * Package models implements all PocketBase DB models and DTOs. + */ +namespace models { /** - * Router is interface for routing request contexts to registered routes. - * - * Contract between Echo/Context instance and the router: - * ``` - * - all routes must be added through methods on echo.Echo instance. - * Reason: Echo instance uses RouteInfo.Params() length to allocate slice for paths parameters (see `Echo.contextPathParamAllocSize`). - * - Router must populate Context during Router.Route call with: - * - RoutableContext.SetPath - * - RoutableContext.SetRawPathParams (IMPORTANT! with same slice pointer that c.RawPathParams() returns) - * - RoutableContext.SetRouteInfo - * And optionally can set additional information to Context with RoutableContext.Set - * ``` + * Model defines an interface with common methods that all db models should have. */ - interface Router { + interface Model { [key:string]: any; - /** - * Add registers Routable with the Router and returns registered RouteInfo - */ - add(routable: Routable): RouteInfo - /** - * Remove removes route from the Router - */ - remove(method: string, path: string): void - /** - * Routes returns information about all registered routes - */ - routes(): Routes - /** - * Route searches Router for matching route and applies it to the given context. In case when no matching method - * was not found (405) or no matching route exists for path (404), router will return its implementation of 405/404 - * handler function. - */ - route(c: RoutableContext): HandlerFunc + tableName(): string + isNew(): boolean + markAsNew(): void + markAsNotNew(): void + hasId(): boolean + getId(): string + setId(id: string): void + getCreated(): types.DateTime + getUpdated(): types.DateTime + refreshId(): void + refreshCreated(): void + refreshUpdated(): void } /** - * Routable is interface for registering Route with Router. During route registration process the Router will - * convert Routable to RouteInfo with ToRouteInfo method. By creating custom implementation of Routable additional - * information about registered route can be stored in Routes (i.e. privileges used with route etc.) + * BaseModel defines common fields and methods used by all other models. */ - interface Routable { - [key:string]: any; + interface BaseModel { + id: string + created: types.DateTime + updated: types.DateTime + } + interface BaseModel { /** - * ToRouteInfo converts Routable to RouteInfo - * - * This method is meant to be used by Router after it parses url for path parameters, to store information about - * route just added. + * HasId returns whether the model has a nonzero id. */ - toRouteInfo(params: Array): RouteInfo + hasId(): boolean + } + interface BaseModel { /** - * ToRoute converts Routable to Route which Router uses to register the method handler for path. - * - * This method is meant to be used by Router to get fields (including handler and middleware functions) needed to - * add Route to Router. + * GetId returns the model id. */ - toRoute(): Route + getId(): string + } + interface BaseModel { /** - * ForGroup recreates routable with added group prefix and group middlewares it is grouped to. - * - * Is necessary for Echo.Group to be able to add/register Routable with Router and having group prefix and group - * middlewares included in actually registered Route. + * SetId sets the model id to the provided string value. */ - forGroup(pathPrefix: string, middlewares: Array): Routable + setId(id: string): void } - /** - * Routes is collection of RouteInfo instances with various helper methods. - */ - interface Routes extends Array{} - /** - * RouteInfo describes registered route base fields. - * Method+Path pair uniquely identifies the Route. Name can have duplicates. - */ - interface RouteInfo { - [key:string]: any; - method(): string - path(): string - name(): string - params(): Array + interface BaseModel { /** - * Reverse reverses route to URL string by replacing path parameters with given params values. + * MarkAsNew marks the model as "new" (aka. enforces m.IsNew() to be true). */ - reverse(...params: { - }[]): string + markAsNew(): void } - /** - * PathParams is collections of PathParam instances with various helper methods - */ - interface PathParams extends Array{} - interface PathParams { + interface BaseModel { /** - * Get returns path parameter value for given name or default value. + * MarkAsNotNew marks the model as "not new" (aka. enforces m.IsNew() to be false) */ - get(name: string, defaultValue: string): string - } -} - -namespace settings { - // @ts-ignore - import validation = ozzo_validation - interface TokenConfig { - secret: string - duration: number + markAsNotNew(): void } - interface TokenConfig { + interface BaseModel { /** - * Validate makes TokenConfig validatable by implementing [validation.Validatable] interface. + * IsNew indicates what type of db query (insert or update) + * should be used with the model instance. */ - validate(): void + isNew(): boolean } - interface SmtpConfig { - enabled: boolean - host: string - port: number - username: string - password: string + interface BaseModel { /** - * SMTP AUTH - PLAIN (default) or LOGIN + * GetCreated returns the model Created datetime. */ - authMethod: string + getCreated(): types.DateTime + } + interface BaseModel { /** - * Whether to enforce TLS encryption for the mail server connection. - * - * When set to false StartTLS command is send, leaving the server - * to decide whether to upgrade the connection or not. + * GetUpdated returns the model Updated datetime. */ - tls: boolean + getUpdated(): types.DateTime + } + interface BaseModel { /** - * LocalName is optional domain name or IP address used for the - * EHLO/HELO exchange (if not explicitly set, defaults to "localhost"). + * RefreshId generates and sets a new model id. * - * This is required only by some SMTP servers, such as Gmail SMTP-relay. + * The generated id is a cryptographically random 15 characters length string. */ - localName: string + refreshId(): void } - interface SmtpConfig { + interface BaseModel { /** - * Validate makes SmtpConfig validatable by implementing [validation.Validatable] interface. + * RefreshCreated updates the model Created field with the current datetime. */ - validate(): void - } - interface S3Config { - enabled: boolean - bucket: string - region: string - endpoint: string - accessKey: string - secret: string - forcePathStyle: boolean + refreshCreated(): void } - interface S3Config { + interface BaseModel { /** - * Validate makes S3Config validatable by implementing [validation.Validatable] interface. + * RefreshUpdated updates the model Updated field with the current datetime. */ - validate(): void + refreshUpdated(): void } - interface BackupsConfig { - /** - * Cron is a cron expression to schedule auto backups, eg. "* * * * *". - * - * Leave it empty to disable the auto backups functionality. - */ - cron: string + interface BaseModel { /** - * CronMaxKeep is the the max number of cron generated backups to - * keep before removing older entries. + * PostScan implements the [dbx.PostScanner] interface. * - * This field works only when the cron config has valid cron expression. - */ - cronMaxKeep: number - /** - * S3 is an optional S3 storage config specifying where to store the app backups. + * It is executed right after the model was populated with the db row values. */ - s3: S3Config + postScan(): void } - interface BackupsConfig { + // @ts-ignore + import validation = ozzo_validation + /** + * CollectionBaseOptions defines the "base" Collection.Options fields. + */ + interface CollectionBaseOptions { + } + interface CollectionBaseOptions { /** - * Validate makes BackupsConfig validatable by implementing [validation.Validatable] interface. + * Validate implements [validation.Validatable] interface. */ validate(): void } - interface MetaConfig { - appName: string - appUrl: string - hideControls: boolean - senderName: string - senderAddress: string - verificationTemplate: EmailTemplate - resetPasswordTemplate: EmailTemplate - confirmEmailChangeTemplate: EmailTemplate + /** + * CollectionAuthOptions defines the "auth" Collection.Options fields. + */ + interface CollectionAuthOptions { + manageRule?: string + allowOAuth2Auth: boolean + allowUsernameAuth: boolean + allowEmailAuth: boolean + requireEmail: boolean + exceptEmailDomains: Array + onlyVerified: boolean + onlyEmailDomains: Array + minPasswordLength: number } - interface MetaConfig { + interface CollectionAuthOptions { /** - * Validate makes MetaConfig validatable by implementing [validation.Validatable] interface. + * Validate implements [validation.Validatable] interface. */ validate(): void } - interface LogsConfig { - maxDays: number - minLevel: number - logIp: boolean + /** + * CollectionViewOptions defines the "view" Collection.Options fields. + */ + interface CollectionViewOptions { + query: string } - interface LogsConfig { + interface CollectionViewOptions { /** - * Validate makes LogsConfig validatable by implementing [validation.Validatable] interface. + * Validate implements [validation.Validatable] interface. */ validate(): void } - interface AuthProviderConfig { - enabled: boolean - clientId: string - clientSecret: string - authUrl: string - tokenUrl: string - userApiUrl: string - displayName: string - pkce?: boolean + type _subhrWXI = BaseModel + interface Log extends _subhrWXI { + data: types.JsonMap + message: string + level: number } - interface AuthProviderConfig { - /** - * Validate makes `ProviderConfig` validatable by implementing [validation.Validatable] interface. - */ - validate(): void + interface Log { + tableName(): string } - interface AuthProviderConfig { - /** - * SetupProvider loads the current AuthProviderConfig into the specified provider. - */ - setupProvider(provider: auth.Provider): void + type _subGSloU = BaseModel + interface Param extends _subGSloU { + key: string + value: types.JsonRaw } - /** - * Deprecated: Will be removed in v0.9+ - */ - interface EmailAuthConfig { - enabled: boolean - exceptDomains: Array - onlyDomains: Array - minPasswordLength: number + interface Param { + tableName(): string } - interface EmailAuthConfig { + interface TableInfoRow { /** - * Deprecated: Will be removed in v0.9+ + * the `db:"pk"` tag has special semantic so we cannot rename + * the original field without specifying a custom mapper */ - validate(): void + pk: number + index: number + name: string + type: string + notNull: boolean + defaultValue: types.JsonRaw } } @@ -17092,8 +17112,8 @@ namespace hook { * TaggedHook defines a proxy hook which register handlers that are triggered only * if the TaggedHook.tags are empty or includes at least one of the event data tag(s). */ - type _subyoEUx = mainHook - interface TaggedHook extends _subyoEUx { + type _subWIsLS = mainHook + interface TaggedHook extends _subWIsLS { } interface TaggedHook { /** @@ -17120,63 +17140,6 @@ namespace hook { } } -namespace migrate { - interface Migration { - file: string - up: (db: dbx.Builder) => void - down: (db: dbx.Builder) => void - } -} - -/** - * Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces. - * In addition to providing an interface, Cobra simultaneously provides a controller to organize your application code. - */ -namespace cobra { - interface PositionalArgs {(cmd: Command, args: Array): void } - // @ts-ignore - import flag = pflag - /** - * FParseErrWhitelist configures Flag parse errors to be ignored - */ - interface FParseErrWhitelist extends _TygojaAny{} - /** - * Group Structure to manage groups for commands - */ - interface Group { - id: string - title: string - } - /** - * ShellCompDirective is a bit map representing the different behaviors the shell - * can be instructed to have once completions have been provided. - */ - interface ShellCompDirective extends Number{} - /** - * CompletionOptions are the options to control shell completion - */ - interface CompletionOptions { - /** - * DisableDefaultCmd prevents Cobra from creating a default 'completion' command - */ - disableDefaultCmd: boolean - /** - * DisableNoDescFlag prevents Cobra from creating the '--no-descriptions' flag - * for shells that support completion descriptions - */ - disableNoDescFlag: boolean - /** - * DisableDescriptions turns off all completion descriptions for shells - * that support them - */ - disableDescriptions: boolean - /** - * HiddenDefaultCmd makes the default 'completion' command hidden - */ - hiddenDefaultCmd: boolean - } -} - /** * Package slog provides structured logging, * in which log records include a message, @@ -17725,12 +17688,12 @@ namespace core { httpContext: echo.Context error: Error } - type _suboxQNF = BaseModelEvent - interface ModelEvent extends _suboxQNF { + type _subNQtmT = BaseModelEvent + interface ModelEvent extends _subNQtmT { dao?: daos.Dao } - type _subNnoVy = BaseCollectionEvent - interface MailerRecordEvent extends _subNnoVy { + type _subPreQB = BaseCollectionEvent + interface MailerRecordEvent extends _subPreQB { mailClient: mailer.Mailer message?: mailer.Message record?: models.Record @@ -17770,50 +17733,50 @@ namespace core { oldSettings?: settings.Settings newSettings?: settings.Settings } - type _subnhCIk = BaseCollectionEvent - interface RecordsListEvent extends _subnhCIk { + type _subWhnvy = BaseCollectionEvent + interface RecordsListEvent extends _subWhnvy { httpContext: echo.Context records: Array<(models.Record | undefined)> result?: search.Result } - type _subvKEpg = BaseCollectionEvent - interface RecordViewEvent extends _subvKEpg { + type _subRsnOH = BaseCollectionEvent + interface RecordViewEvent extends _subRsnOH { httpContext: echo.Context record?: models.Record } - type _subZcKDl = BaseCollectionEvent - interface RecordCreateEvent extends _subZcKDl { + type _subMxLdO = BaseCollectionEvent + interface RecordCreateEvent extends _subMxLdO { httpContext: echo.Context record?: models.Record uploadedFiles: _TygojaDict } - type _subqOISc = BaseCollectionEvent - interface RecordUpdateEvent extends _subqOISc { + type _subYqTMc = BaseCollectionEvent + interface RecordUpdateEvent extends _subYqTMc { httpContext: echo.Context record?: models.Record uploadedFiles: _TygojaDict } - type _subcnTSG = BaseCollectionEvent - interface RecordDeleteEvent extends _subcnTSG { + type _subHEvOB = BaseCollectionEvent + interface RecordDeleteEvent extends _subHEvOB { httpContext: echo.Context record?: models.Record } - type _subUQeQA = BaseCollectionEvent - interface RecordAuthEvent extends _subUQeQA { + type _subNJbGa = BaseCollectionEvent + interface RecordAuthEvent extends _subNJbGa { httpContext: echo.Context record?: models.Record token: string meta: any } - type _subeGkpi = BaseCollectionEvent - interface RecordAuthWithPasswordEvent extends _subeGkpi { + type _subYIAsl = BaseCollectionEvent + interface RecordAuthWithPasswordEvent extends _subYIAsl { httpContext: echo.Context record?: models.Record identity: string password: string } - type _subscnCN = BaseCollectionEvent - interface RecordAuthWithOAuth2Event extends _subscnCN { + type _subqPBfc = BaseCollectionEvent + interface RecordAuthWithOAuth2Event extends _subqPBfc { httpContext: echo.Context providerName: string providerClient: auth.Provider @@ -17821,49 +17784,49 @@ namespace core { oAuth2User?: auth.AuthUser isNewRecord: boolean } - type _subsdpfO = BaseCollectionEvent - interface RecordAuthRefreshEvent extends _subsdpfO { + type _subfHqNn = BaseCollectionEvent + interface RecordAuthRefreshEvent extends _subfHqNn { httpContext: echo.Context record?: models.Record } - type _subOOQvK = BaseCollectionEvent - interface RecordRequestPasswordResetEvent extends _subOOQvK { + type _subEEQvo = BaseCollectionEvent + interface RecordRequestPasswordResetEvent extends _subEEQvo { httpContext: echo.Context record?: models.Record } - type _subFAlqp = BaseCollectionEvent - interface RecordConfirmPasswordResetEvent extends _subFAlqp { + type _subOnHAd = BaseCollectionEvent + interface RecordConfirmPasswordResetEvent extends _subOnHAd { httpContext: echo.Context record?: models.Record } - type _subVMPNv = BaseCollectionEvent - interface RecordRequestVerificationEvent extends _subVMPNv { + type _subyQkZe = BaseCollectionEvent + interface RecordRequestVerificationEvent extends _subyQkZe { httpContext: echo.Context record?: models.Record } - type _subtDtfj = BaseCollectionEvent - interface RecordConfirmVerificationEvent extends _subtDtfj { + type _subEYLJV = BaseCollectionEvent + interface RecordConfirmVerificationEvent extends _subEYLJV { httpContext: echo.Context record?: models.Record } - type _subJcqOl = BaseCollectionEvent - interface RecordRequestEmailChangeEvent extends _subJcqOl { + type _subUiZui = BaseCollectionEvent + interface RecordRequestEmailChangeEvent extends _subUiZui { httpContext: echo.Context record?: models.Record } - type _subQBIpB = BaseCollectionEvent - interface RecordConfirmEmailChangeEvent extends _subQBIpB { + type _subORfFa = BaseCollectionEvent + interface RecordConfirmEmailChangeEvent extends _subORfFa { httpContext: echo.Context record?: models.Record } - type _subuhTfu = BaseCollectionEvent - interface RecordListExternalAuthsEvent extends _subuhTfu { + type _subyksbK = BaseCollectionEvent + interface RecordListExternalAuthsEvent extends _subyksbK { httpContext: echo.Context record?: models.Record externalAuths: Array<(models.ExternalAuth | undefined)> } - type _subwotFj = BaseCollectionEvent - interface RecordUnlinkExternalAuthEvent extends _subwotFj { + type _subgmReu = BaseCollectionEvent + interface RecordUnlinkExternalAuthEvent extends _subgmReu { httpContext: echo.Context record?: models.Record externalAuth?: models.ExternalAuth @@ -17917,33 +17880,33 @@ namespace core { collections: Array<(models.Collection | undefined)> result?: search.Result } - type _subtkVRc = BaseCollectionEvent - interface CollectionViewEvent extends _subtkVRc { + type _subNKoJU = BaseCollectionEvent + interface CollectionViewEvent extends _subNKoJU { httpContext: echo.Context } - type _subCjDlH = BaseCollectionEvent - interface CollectionCreateEvent extends _subCjDlH { + type _subIJGdN = BaseCollectionEvent + interface CollectionCreateEvent extends _subIJGdN { httpContext: echo.Context } - type _subyxTfj = BaseCollectionEvent - interface CollectionUpdateEvent extends _subyxTfj { + type _subvMBZb = BaseCollectionEvent + interface CollectionUpdateEvent extends _subvMBZb { httpContext: echo.Context } - type _subByycP = BaseCollectionEvent - interface CollectionDeleteEvent extends _subByycP { + type _subYEbNP = BaseCollectionEvent + interface CollectionDeleteEvent extends _subYEbNP { httpContext: echo.Context } interface CollectionsImportEvent { httpContext: echo.Context collections: Array<(models.Collection | undefined)> } - type _subnKiiL = BaseModelEvent - interface FileTokenEvent extends _subnKiiL { + type _subFqOIc = BaseModelEvent + interface FileTokenEvent extends _subFqOIc { httpContext: echo.Context token: string } - type _subZOoGq = BaseCollectionEvent - interface FileDownloadEvent extends _subZOoGq { + type _subUxgNn = BaseCollectionEvent + interface FileDownloadEvent extends _subUxgNn { httpContext: echo.Context record?: models.Record fileField?: schema.SchemaField @@ -17952,6 +17915,63 @@ namespace core { } } +/** + * Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces. + * In addition to providing an interface, Cobra simultaneously provides a controller to organize your application code. + */ +namespace cobra { + interface PositionalArgs {(cmd: Command, args: Array): void } + // @ts-ignore + import flag = pflag + /** + * FParseErrWhitelist configures Flag parse errors to be ignored + */ + interface FParseErrWhitelist extends _TygojaAny{} + /** + * Group Structure to manage groups for commands + */ + interface Group { + id: string + title: string + } + /** + * ShellCompDirective is a bit map representing the different behaviors the shell + * can be instructed to have once completions have been provided. + */ + interface ShellCompDirective extends Number{} + /** + * CompletionOptions are the options to control shell completion + */ + interface CompletionOptions { + /** + * DisableDefaultCmd prevents Cobra from creating a default 'completion' command + */ + disableDefaultCmd: boolean + /** + * DisableNoDescFlag prevents Cobra from creating the '--no-descriptions' flag + * for shells that support completion descriptions + */ + disableNoDescFlag: boolean + /** + * DisableDescriptions turns off all completion descriptions for shells + * that support them + */ + disableDescriptions: boolean + /** + * HiddenDefaultCmd makes the default 'completion' command hidden + */ + hiddenDefaultCmd: boolean + } +} + +namespace migrate { + interface Migration { + file: string + up: (db: dbx.Builder) => void + down: (db: dbx.Builder) => void + } +} + /** * Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer * object, creating another object (Reader or Writer) that also implements @@ -17962,8 +17982,8 @@ namespace bufio { * ReadWriter stores pointers to a Reader and a Writer. * It implements io.ReadWriter. */ - type _subdjTan = Reader&Writer - interface ReadWriter extends _subdjTan { + type _subnROWM = Reader&Writer + interface ReadWriter extends _subnROWM { } } @@ -18066,6 +18086,39 @@ namespace net { } } +/** + * Package url parses URLs and implements query escaping. + */ +namespace url { + /** + * The Userinfo type is an immutable encapsulation of username and + * password details for a URL. An existing Userinfo value is guaranteed + * to have a username set (potentially empty, as allowed by RFC 2396), + * and optionally a password. + */ + interface Userinfo { + } + interface Userinfo { + /** + * Username returns the username. + */ + username(): string + } + interface Userinfo { + /** + * Password returns the password in case it is set, and whether it is set. + */ + password(): [string, boolean] + } + interface Userinfo { + /** + * String returns the encoded userinfo information in the standard form + * of "username[:password]". + */ + string(): string + } +} + /** * Package multipart implements MIME multipart parsing, as defined in RFC * 2046. @@ -18132,237 +18185,662 @@ namespace multipart { } } -namespace store { -} - /** - * Package slog provides structured logging, - * in which log records include a message, - * a severity level, and various other attributes - * expressed as key-value pairs. - * - * It defines a type, [Logger], - * which provides several methods (such as [Logger.Info] and [Logger.Error]) - * for reporting events of interest. - * - * Each Logger is associated with a [Handler]. - * A Logger output method creates a [Record] from the method arguments - * and passes it to the Handler, which decides how to handle it. - * There is a default Logger accessible through top-level functions - * (such as [Info] and [Error]) that call the corresponding Logger methods. + * Package http provides HTTP client and server implementations. * - * A log record consists of a time, a level, a message, and a set of key-value - * pairs, where the keys are strings and the values may be of any type. - * As an example, + * Get, Head, Post, and PostForm make HTTP (or HTTPS) requests: * * ``` - * slog.Info("hello", "count", 3) + * resp, err := http.Get("http://example.com/") + * ... + * resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf) + * ... + * resp, err := http.PostForm("http://example.com/form", + * url.Values{"key": {"Value"}, "id": {"123"}}) * ``` * - * creates a record containing the time of the call, - * a level of Info, the message "hello", and a single - * pair with key "count" and value 3. - * - * The [Info] top-level function calls the [Logger.Info] method on the default Logger. - * In addition to [Logger.Info], there are methods for Debug, Warn and Error levels. - * Besides these convenience methods for common levels, - * there is also a [Logger.Log] method which takes the level as an argument. - * Each of these methods has a corresponding top-level function that uses the - * default logger. - * - * The default handler formats the log record's message, time, level, and attributes - * as a string and passes it to the [log] package. + * The caller must close the response body when finished with it: * * ``` - * 2022/11/08 15:28:26 INFO hello count=3 + * resp, err := http.Get("http://example.com/") + * if err != nil { + * // handle error + * } + * defer resp.Body.Close() + * body, err := io.ReadAll(resp.Body) + * // ... * ``` * - * For more control over the output format, create a logger with a different handler. - * This statement uses [New] to create a new logger with a TextHandler - * that writes structured records in text form to standard error: - * - * ``` - * logger := slog.New(slog.NewTextHandler(os.Stderr, nil)) - * ``` + * # Clients and Transports * - * [TextHandler] output is a sequence of key=value pairs, easily and unambiguously - * parsed by machine. This statement: + * For control over HTTP client headers, redirect policy, and other + * settings, create a Client: * * ``` - * logger.Info("hello", "count", 3) - * ``` + * client := &http.Client{ + * CheckRedirect: redirectPolicyFunc, + * } * - * produces this output: + * resp, err := client.Get("http://example.com") + * // ... * - * ``` - * time=2022-11-08T15:28:26.000-05:00 level=INFO msg=hello count=3 + * req, err := http.NewRequest("GET", "http://example.com", nil) + * // ... + * req.Header.Add("If-None-Match", `W/"wyzzy"`) + * resp, err := client.Do(req) + * // ... * ``` * - * The package also provides [JSONHandler], whose output is line-delimited JSON: + * For control over proxies, TLS configuration, keep-alives, + * compression, and other settings, create a Transport: * * ``` - * logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) - * logger.Info("hello", "count", 3) + * tr := &http.Transport{ + * MaxIdleConns: 10, + * IdleConnTimeout: 30 * time.Second, + * DisableCompression: true, + * } + * client := &http.Client{Transport: tr} + * resp, err := client.Get("https://example.com") * ``` * - * produces this output: - * - * ``` - * {"time":"2022-11-08T15:28:26.000000000-05:00","level":"INFO","msg":"hello","count":3} - * ``` + * Clients and Transports are safe for concurrent use by multiple + * goroutines and for efficiency should only be created once and re-used. * - * Both [TextHandler] and [JSONHandler] can be configured with [HandlerOptions]. - * There are options for setting the minimum level (see Levels, below), - * displaying the source file and line of the log call, and - * modifying attributes before they are logged. + * # Servers * - * Setting a logger as the default with + * ListenAndServe starts an HTTP server with a given address and handler. + * The handler is usually nil, which means to use DefaultServeMux. + * Handle and HandleFunc add handlers to DefaultServeMux: * * ``` - * slog.SetDefault(logger) - * ``` - * - * will cause the top-level functions like [Info] to use it. - * [SetDefault] also updates the default logger used by the [log] package, - * so that existing applications that use [log.Printf] and related functions - * will send log records to the logger's handler without needing to be rewritten. + * http.Handle("/foo", fooHandler) * - * Some attributes are common to many log calls. - * For example, you may wish to include the URL or trace identifier of a server request - * with all log events arising from the request. - * Rather than repeat the attribute with every log call, you can use [Logger.With] - * to construct a new Logger containing the attributes: + * http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) { + * fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path)) + * }) * + * log.Fatal(http.ListenAndServe(":8080", nil)) * ``` - * logger2 := logger.With("url", r.URL) - * ``` - * - * The arguments to With are the same key-value pairs used in [Logger.Info]. - * The result is a new Logger with the same handler as the original, but additional - * attributes that will appear in the output of every call. - * - * # Levels - * - * A [Level] is an integer representing the importance or severity of a log event. - * The higher the level, the more severe the event. - * This package defines constants for the most common levels, - * but any int can be used as a level. - * - * In an application, you may wish to log messages only at a certain level or greater. - * One common configuration is to log messages at Info or higher levels, - * suppressing debug logging until it is needed. - * The built-in handlers can be configured with the minimum level to output by - * setting [HandlerOptions.Level]. - * The program's `main` function typically does this. - * The default value is LevelInfo. * - * Setting the [HandlerOptions.Level] field to a [Level] value - * fixes the handler's minimum level throughout its lifetime. - * Setting it to a [LevelVar] allows the level to be varied dynamically. - * A LevelVar holds a Level and is safe to read or write from multiple - * goroutines. - * To vary the level dynamically for an entire program, first initialize - * a global LevelVar: + * More control over the server's behavior is available by creating a + * custom Server: * * ``` - * var programLevel = new(slog.LevelVar) // Info by default + * s := &http.Server{ + * Addr: ":8080", + * Handler: myHandler, + * ReadTimeout: 10 * time.Second, + * WriteTimeout: 10 * time.Second, + * MaxHeaderBytes: 1 << 20, + * } + * log.Fatal(s.ListenAndServe()) * ``` * - * Then use the LevelVar to construct a handler, and make it the default: - * - * ``` - * h := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: programLevel}) - * slog.SetDefault(slog.New(h)) - * ``` + * # HTTP/2 * - * Now the program can change its logging level with a single statement: + * Starting with Go 1.6, the http package has transparent support for the + * HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2 + * can do so by setting Transport.TLSNextProto (for clients) or + * Server.TLSNextProto (for servers) to a non-nil, empty + * map. Alternatively, the following GODEBUG settings are + * currently supported: * * ``` - * programLevel.Set(slog.LevelDebug) + * GODEBUG=http2client=0 # disable HTTP/2 client support + * GODEBUG=http2server=0 # disable HTTP/2 server support + * GODEBUG=http2debug=1 # enable verbose HTTP/2 debug logs + * GODEBUG=http2debug=2 # ... even more verbose, with frame dumps * ``` * - * # Groups + * Please report any issues before disabling HTTP/2 support: https://golang.org/s/http2bug * - * Attributes can be collected into groups. - * A group has a name that is used to qualify the names of its attributes. - * How this qualification is displayed depends on the handler. - * [TextHandler] separates the group and attribute names with a dot. - * [JSONHandler] treats each group as a separate JSON object, with the group name as the key. + * The http package's Transport and Server both automatically enable + * HTTP/2 support for simple configurations. To enable HTTP/2 for more + * complex configurations, to use lower-level HTTP/2 features, or to use + * a newer version of Go's http2 package, import "golang.org/x/net/http2" + * directly and use its ConfigureTransport and/or ConfigureServer + * functions. Manually configuring HTTP/2 via the golang.org/x/net/http2 + * package takes precedence over the net/http package's built-in HTTP/2 + * support. + */ +namespace http { + /** + * SameSite allows a server to define a cookie attribute making it impossible for + * the browser to send this cookie along with cross-site requests. The main + * goal is to mitigate the risk of cross-origin information leakage, and provide + * some protection against cross-site request forgery attacks. + * + * See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 for details. + */ + interface SameSite extends Number{} + // @ts-ignore + import mathrand = rand + // @ts-ignore + import urlpkg = url +} + +/** + * Package types implements some commonly used db serializable types + * like datetime, json, etc. + */ +namespace types { + /** + * JsonRaw defines a json value type that is safe for db read/write. + */ + interface JsonRaw extends Array{} + interface JsonRaw { + /** + * String returns the current JsonRaw instance as a json encoded string. + */ + string(): string + } + interface JsonRaw { + /** + * MarshalJSON implements the [json.Marshaler] interface. + */ + marshalJSON(): string|Array + } + interface JsonRaw { + /** + * UnmarshalJSON implements the [json.Unmarshaler] interface. + */ + unmarshalJSON(b: string|Array): void + } + interface JsonRaw { + /** + * Value implements the [driver.Valuer] interface. + */ + value(): any + } + interface JsonRaw { + /** + * Scan implements [sql.Scanner] interface to scan the provided value + * into the current JsonRaw instance. + */ + scan(value: any): void + } +} + +namespace store { +} + +namespace mailer { + /** + * Message defines a generic email message struct. + */ + interface Message { + from: mail.Address + to: Array + bcc: Array + cc: Array + subject: string + html: string + text: string + headers: _TygojaDict + attachments: _TygojaDict + } +} + +/** + * Package echo implements high performance, minimalist Go web framework. * - * Use [Group] to create a Group attribute from a name and a list of key-value pairs: + * Example: * * ``` - * slog.Group("request", - * "method", r.Method, - * "url", r.URL) - * ``` - * - * TextHandler would display this group as + * package main * - * ``` - * request.method=GET request.url=http://example.com - * ``` + * import ( + * "github.com/labstack/echo/v5" + * "github.com/labstack/echo/v5/middleware" + * "log" + * "net/http" + * ) * - * JSONHandler would display it as + * // Handler + * func hello(c echo.Context) error { + * return c.String(http.StatusOK, "Hello, World!") + * } * - * ``` - * "request":{"method":"GET","url":"http://example.com"} - * ``` + * func main() { + * // Echo instance + * e := echo.New() * - * Use [Logger.WithGroup] to qualify all of a Logger's output - * with a group name. Calling WithGroup on a Logger results in a - * new Logger with the same Handler as the original, but with all - * its attributes qualified by the group name. + * // Middleware + * e.Use(middleware.Logger()) + * e.Use(middleware.Recover()) * - * This can help prevent duplicate attribute keys in large systems, - * where subsystems might use the same keys. - * Pass each subsystem a different Logger with its own group name so that - * potential duplicates are qualified: + * // Routes + * e.GET("/", hello) * + * // Start server + * if err := e.Start(":8080"); err != http.ErrServerClosed { + * log.Fatal(err) + * } + * } * ``` - * logger := slog.Default().With("id", systemID) - * parserLogger := logger.WithGroup("parser") - * parseInput(input, parserLogger) - * ``` - * - * When parseInput logs with parserLogger, its keys will be qualified with "parser", - * so even if it uses the common key "id", the log line will have distinct keys. * - * # Contexts + * Learn more at https://echo.labstack.com + */ +namespace echo { + // @ts-ignore + import stdContext = context + /** + * Route contains information to adding/registering new route with the router. + * Method+Path pair uniquely identifies the Route. It is mandatory to provide Method+Path+Handler fields. + */ + interface Route { + method: string + path: string + handler: HandlerFunc + middlewares: Array + name: string + } + interface Route { + /** + * ToRouteInfo converts Route to RouteInfo + */ + toRouteInfo(params: Array): RouteInfo + } + interface Route { + /** + * ToRoute returns Route which Router uses to register the method handler for path. + */ + toRoute(): Route + } + interface Route { + /** + * ForGroup recreates Route with added group prefix and group middlewares it is grouped to. + */ + forGroup(pathPrefix: string, middlewares: Array): Routable + } + /** + * RoutableContext is additional interface that structures implementing Context must implement. Methods inside this + * interface are meant for request routing purposes and should not be used in middlewares. + */ + interface RoutableContext { + [key:string]: any; + /** + * Request returns `*http.Request`. + */ + request(): (http.Request) + /** + * RawPathParams returns raw path pathParams value. Allocation of PathParams is handled by Context. + */ + rawPathParams(): (PathParams) + /** + * SetRawPathParams replaces any existing param values with new values for this context lifetime (request). + * Do not set any other value than what you got from RawPathParams as allocation of PathParams is handled by Context. + */ + setRawPathParams(params: PathParams): void + /** + * SetPath sets the registered path for the handler. + */ + setPath(p: string): void + /** + * SetRouteInfo sets the route info of this request to the context. + */ + setRouteInfo(ri: RouteInfo): void + /** + * Set saves data in the context. Allows router to store arbitrary (that only router has access to) data in context + * for later use in middlewares/handler. + */ + set(key: string, val: { + }): void + } + /** + * PathParam is tuple pf path parameter name and its value in request path + */ + interface PathParam { + name: string + value: string + } +} + +namespace search { + /** + * Result defines the returned search result structure. + */ + interface Result { + page: number + perPage: number + totalItems: number + totalPages: number + items: any + } +} + +namespace settings { + // @ts-ignore + import validation = ozzo_validation + interface EmailTemplate { + body: string + subject: string + actionUrl: string + } + interface EmailTemplate { + /** + * Validate makes EmailTemplate validatable by implementing [validation.Validatable] interface. + */ + validate(): void + } + interface EmailTemplate { + /** + * Resolve replaces the placeholder parameters in the current email + * template and returns its components as ready-to-use strings. + */ + resolve(appName: string, appUrl: string): string + } +} + +namespace subscriptions { + /** + * Message defines a client's channel data. + */ + interface Message { + name: string + data: string|Array + } + /** + * Client is an interface for a generic subscription client. + */ + interface Client { + [key:string]: any; + /** + * Id Returns the unique id of the client. + */ + id(): string + /** + * Channel returns the client's communication channel. + */ + channel(): undefined + /** + * Subscriptions returns a shallow copy of the the client subscriptions matching the prefixes. + * If no prefix is specified, returns all subscriptions. + */ + subscriptions(...prefixes: string[]): _TygojaDict + /** + * Subscribe subscribes the client to the provided subscriptions list. + * + * Each subscription can also have "options" (json serialized SubscriptionOptions) as query parameter. + * + * Example: + * + * ``` + * Subscribe( + * "subscriptionA", + * `subscriptionB?options={"query":{"a":1},"headers":{"x_token":"abc"}}`, + * ) + * ``` + */ + subscribe(...subs: string[]): void + /** + * Unsubscribe unsubscribes the client from the provided subscriptions list. + */ + unsubscribe(...subs: string[]): void + /** + * HasSubscription checks if the client is subscribed to `sub`. + */ + hasSubscription(sub: string): boolean + /** + * Set stores any value to the client's context. + */ + set(key: string, value: any): void + /** + * Unset removes a single value from the client's context. + */ + unset(key: string): void + /** + * Get retrieves the key value from the client's context. + */ + get(key: string): any + /** + * Discard marks the client as "discarded", meaning that it + * shouldn't be used anymore for sending new messages. + * + * It is safe to call Discard() multiple times. + */ + discard(): void + /** + * IsDiscarded indicates whether the client has been "discarded" + * and should no longer be used. + */ + isDiscarded(): boolean + /** + * Send sends the specified message to the client's channel (if not discarded). + */ + send(m: Message): void + } +} + +/** + * Package slog provides structured logging, + * in which log records include a message, + * a severity level, and various other attributes + * expressed as key-value pairs. * - * Some handlers may wish to include information from the [context.Context] that is - * available at the call site. One example of such information - * is the identifier for the current span when tracing is enabled. + * It defines a type, [Logger], + * which provides several methods (such as [Logger.Info] and [Logger.Error]) + * for reporting events of interest. * - * The [Logger.Log] and [Logger.LogAttrs] methods take a context as a first - * argument, as do their corresponding top-level functions. + * Each Logger is associated with a [Handler]. + * A Logger output method creates a [Record] from the method arguments + * and passes it to the Handler, which decides how to handle it. + * There is a default Logger accessible through top-level functions + * (such as [Info] and [Error]) that call the corresponding Logger methods. * - * Although the convenience methods on Logger (Info and so on) and the - * corresponding top-level functions do not take a context, the alternatives ending - * in "Context" do. For example, + * A log record consists of a time, a level, a message, and a set of key-value + * pairs, where the keys are strings and the values may be of any type. + * As an example, * * ``` - * slog.InfoContext(ctx, "message") + * slog.Info("hello", "count", 3) * ``` * - * It is recommended to pass a context to an output method if one is available. + * creates a record containing the time of the call, + * a level of Info, the message "hello", and a single + * pair with key "count" and value 3. * - * # Attrs and Values + * The [Info] top-level function calls the [Logger.Info] method on the default Logger. + * In addition to [Logger.Info], there are methods for Debug, Warn and Error levels. + * Besides these convenience methods for common levels, + * there is also a [Logger.Log] method which takes the level as an argument. + * Each of these methods has a corresponding top-level function that uses the + * default logger. * - * An [Attr] is a key-value pair. The Logger output methods accept Attrs as well as - * alternating keys and values. The statement + * The default handler formats the log record's message, time, level, and attributes + * as a string and passes it to the [log] package. * * ``` - * slog.Info("hello", slog.Int("count", 3)) + * 2022/11/08 15:28:26 INFO hello count=3 * ``` * - * behaves the same as + * For more control over the output format, create a logger with a different handler. + * This statement uses [New] to create a new logger with a TextHandler + * that writes structured records in text form to standard error: * * ``` - * slog.Info("hello", "count", 3) + * logger := slog.New(slog.NewTextHandler(os.Stderr, nil)) * ``` * - * There are convenience constructors for [Attr] such as [Int], [String], and [Bool] + * [TextHandler] output is a sequence of key=value pairs, easily and unambiguously + * parsed by machine. This statement: + * + * ``` + * logger.Info("hello", "count", 3) + * ``` + * + * produces this output: + * + * ``` + * time=2022-11-08T15:28:26.000-05:00 level=INFO msg=hello count=3 + * ``` + * + * The package also provides [JSONHandler], whose output is line-delimited JSON: + * + * ``` + * logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) + * logger.Info("hello", "count", 3) + * ``` + * + * produces this output: + * + * ``` + * {"time":"2022-11-08T15:28:26.000000000-05:00","level":"INFO","msg":"hello","count":3} + * ``` + * + * Both [TextHandler] and [JSONHandler] can be configured with [HandlerOptions]. + * There are options for setting the minimum level (see Levels, below), + * displaying the source file and line of the log call, and + * modifying attributes before they are logged. + * + * Setting a logger as the default with + * + * ``` + * slog.SetDefault(logger) + * ``` + * + * will cause the top-level functions like [Info] to use it. + * [SetDefault] also updates the default logger used by the [log] package, + * so that existing applications that use [log.Printf] and related functions + * will send log records to the logger's handler without needing to be rewritten. + * + * Some attributes are common to many log calls. + * For example, you may wish to include the URL or trace identifier of a server request + * with all log events arising from the request. + * Rather than repeat the attribute with every log call, you can use [Logger.With] + * to construct a new Logger containing the attributes: + * + * ``` + * logger2 := logger.With("url", r.URL) + * ``` + * + * The arguments to With are the same key-value pairs used in [Logger.Info]. + * The result is a new Logger with the same handler as the original, but additional + * attributes that will appear in the output of every call. + * + * # Levels + * + * A [Level] is an integer representing the importance or severity of a log event. + * The higher the level, the more severe the event. + * This package defines constants for the most common levels, + * but any int can be used as a level. + * + * In an application, you may wish to log messages only at a certain level or greater. + * One common configuration is to log messages at Info or higher levels, + * suppressing debug logging until it is needed. + * The built-in handlers can be configured with the minimum level to output by + * setting [HandlerOptions.Level]. + * The program's `main` function typically does this. + * The default value is LevelInfo. + * + * Setting the [HandlerOptions.Level] field to a [Level] value + * fixes the handler's minimum level throughout its lifetime. + * Setting it to a [LevelVar] allows the level to be varied dynamically. + * A LevelVar holds a Level and is safe to read or write from multiple + * goroutines. + * To vary the level dynamically for an entire program, first initialize + * a global LevelVar: + * + * ``` + * var programLevel = new(slog.LevelVar) // Info by default + * ``` + * + * Then use the LevelVar to construct a handler, and make it the default: + * + * ``` + * h := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: programLevel}) + * slog.SetDefault(slog.New(h)) + * ``` + * + * Now the program can change its logging level with a single statement: + * + * ``` + * programLevel.Set(slog.LevelDebug) + * ``` + * + * # Groups + * + * Attributes can be collected into groups. + * A group has a name that is used to qualify the names of its attributes. + * How this qualification is displayed depends on the handler. + * [TextHandler] separates the group and attribute names with a dot. + * [JSONHandler] treats each group as a separate JSON object, with the group name as the key. + * + * Use [Group] to create a Group attribute from a name and a list of key-value pairs: + * + * ``` + * slog.Group("request", + * "method", r.Method, + * "url", r.URL) + * ``` + * + * TextHandler would display this group as + * + * ``` + * request.method=GET request.url=http://example.com + * ``` + * + * JSONHandler would display it as + * + * ``` + * "request":{"method":"GET","url":"http://example.com"} + * ``` + * + * Use [Logger.WithGroup] to qualify all of a Logger's output + * with a group name. Calling WithGroup on a Logger results in a + * new Logger with the same Handler as the original, but with all + * its attributes qualified by the group name. + * + * This can help prevent duplicate attribute keys in large systems, + * where subsystems might use the same keys. + * Pass each subsystem a different Logger with its own group name so that + * potential duplicates are qualified: + * + * ``` + * logger := slog.Default().With("id", systemID) + * parserLogger := logger.WithGroup("parser") + * parseInput(input, parserLogger) + * ``` + * + * When parseInput logs with parserLogger, its keys will be qualified with "parser", + * so even if it uses the common key "id", the log line will have distinct keys. + * + * # Contexts + * + * Some handlers may wish to include information from the [context.Context] that is + * available at the call site. One example of such information + * is the identifier for the current span when tracing is enabled. + * + * The [Logger.Log] and [Logger.LogAttrs] methods take a context as a first + * argument, as do their corresponding top-level functions. + * + * Although the convenience methods on Logger (Info and so on) and the + * corresponding top-level functions do not take a context, the alternatives ending + * in "Context" do. For example, + * + * ``` + * slog.InfoContext(ctx, "message") + * ``` + * + * It is recommended to pass a context to an output method if one is available. + * + * # Attrs and Values + * + * An [Attr] is a key-value pair. The Logger output methods accept Attrs as well as + * alternating keys and values. The statement + * + * ``` + * slog.Info("hello", slog.Int("count", 3)) + * ``` + * + * behaves the same as + * + * ``` + * slog.Info("hello", "count", 3) + * ``` + * + * There are convenience constructors for [Attr] such as [Int], [String], and [Bool] * for common types, as well as the function [Any] for constructing Attrs of any * type. * @@ -18499,938 +18977,215 @@ namespace store { * Now computeExpensiveValue will only be called when the line is enabled. * * The built-in handlers acquire a lock before calling [io.Writer.Write] - * to ensure that each record is written in one piece. User-defined - * handlers are responsible for their own locking. - * - * # Writing a handler - * - * For a guide to writing a custom handler, see https://golang.org/s/slog-handler-guide. - */ -namespace slog { - /** - * An Attr is a key-value pair. - */ - interface Attr { - key: string - value: Value - } - interface Attr { - /** - * Equal reports whether a and b have equal keys and values. - */ - equal(b: Attr): boolean - } - interface Attr { - string(): string - } - /** - * A Handler handles log records produced by a Logger.. - * - * A typical handler may print log records to standard error, - * or write them to a file or database, or perhaps augment them - * with additional attributes and pass them on to another handler. - * - * Any of the Handler's methods may be called concurrently with itself - * or with other methods. It is the responsibility of the Handler to - * manage this concurrency. - * - * Users of the slog package should not invoke Handler methods directly. - * They should use the methods of [Logger] instead. - */ - interface Handler { - [key:string]: any; - /** - * Enabled reports whether the handler handles records at the given level. - * The handler ignores records whose level is lower. - * It is called early, before any arguments are processed, - * to save effort if the log event should be discarded. - * If called from a Logger method, the first argument is the context - * passed to that method, or context.Background() if nil was passed - * or the method does not take a context. - * The context is passed so Enabled can use its values - * to make a decision. - */ - enabled(_arg0: context.Context, _arg1: Level): boolean - /** - * Handle handles the Record. - * It will only be called when Enabled returns true. - * The Context argument is as for Enabled. - * It is present solely to provide Handlers access to the context's values. - * Canceling the context should not affect record processing. - * (Among other things, log messages may be necessary to debug a - * cancellation-related problem.) - * - * Handle methods that produce output should observe the following rules: - * ``` - * - If r.Time is the zero time, ignore the time. - * - If r.PC is zero, ignore it. - * - Attr's values should be resolved. - * - If an Attr's key and value are both the zero value, ignore the Attr. - * This can be tested with attr.Equal(Attr{}). - * - If a group's key is empty, inline the group's Attrs. - * - If a group has no Attrs (even if it has a non-empty key), - * ignore it. - * ``` - */ - handle(_arg0: context.Context, _arg1: Record): void - /** - * WithAttrs returns a new Handler whose attributes consist of - * both the receiver's attributes and the arguments. - * The Handler owns the slice: it may retain, modify or discard it. - */ - withAttrs(attrs: Array): Handler - /** - * WithGroup returns a new Handler with the given group appended to - * the receiver's existing groups. - * The keys of all subsequent attributes, whether added by With or in a - * Record, should be qualified by the sequence of group names. - * - * How this qualification happens is up to the Handler, so long as - * this Handler's attribute keys differ from those of another Handler - * with a different sequence of group names. - * - * A Handler should treat WithGroup as starting a Group of Attrs that ends - * at the end of the log event. That is, - * - * ``` - * logger.WithGroup("s").LogAttrs(level, msg, slog.Int("a", 1), slog.Int("b", 2)) - * ``` - * - * should behave like - * - * ``` - * logger.LogAttrs(level, msg, slog.Group("s", slog.Int("a", 1), slog.Int("b", 2))) - * ``` - * - * If the name is empty, WithGroup returns the receiver. - */ - withGroup(name: string): Handler - } - /** - * A Level is the importance or severity of a log event. - * The higher the level, the more important or severe the event. - */ - interface Level extends Number{} - interface Level { - /** - * String returns a name for the level. - * If the level has a name, then that name - * in uppercase is returned. - * If the level is between named values, then - * an integer is appended to the uppercased name. - * Examples: - * - * ``` - * LevelWarn.String() => "WARN" - * (LevelInfo+2).String() => "INFO+2" - * ``` - */ - string(): string - } - interface Level { - /** - * MarshalJSON implements [encoding/json.Marshaler] - * by quoting the output of [Level.String]. - */ - marshalJSON(): string|Array - } - interface Level { - /** - * UnmarshalJSON implements [encoding/json.Unmarshaler] - * It accepts any string produced by [Level.MarshalJSON], - * ignoring case. - * It also accepts numeric offsets that would result in a different string on - * output. For example, "Error-8" would marshal as "INFO". - */ - unmarshalJSON(data: string|Array): void - } - interface Level { - /** - * MarshalText implements [encoding.TextMarshaler] - * by calling [Level.String]. - */ - marshalText(): string|Array - } - interface Level { - /** - * UnmarshalText implements [encoding.TextUnmarshaler]. - * It accepts any string produced by [Level.MarshalText], - * ignoring case. - * It also accepts numeric offsets that would result in a different string on - * output. For example, "Error-8" would marshal as "INFO". - */ - unmarshalText(data: string|Array): void - } - interface Level { - /** - * Level returns the receiver. - * It implements Leveler. - */ - level(): Level - } - // @ts-ignore - import loginternal = internal -} - -/** - * Package url parses URLs and implements query escaping. - */ -namespace url { - /** - * The Userinfo type is an immutable encapsulation of username and - * password details for a URL. An existing Userinfo value is guaranteed - * to have a username set (potentially empty, as allowed by RFC 2396), - * and optionally a password. - */ - interface Userinfo { - } - interface Userinfo { - /** - * Username returns the username. - */ - username(): string - } - interface Userinfo { - /** - * Password returns the password in case it is set, and whether it is set. - */ - password(): [string, boolean] - } - interface Userinfo { - /** - * String returns the encoded userinfo information in the standard form - * of "username[:password]". - */ - string(): string - } -} - -namespace hook { - /** - * Handler defines a hook handler function. - */ - interface Handler {(e: T): void } - /** - * wrapped local Hook embedded struct to limit the public API surface. - */ - type _subyqpey = Hook - interface mainHook extends _subyqpey { - } -} - -/** - * Package types implements some commonly used db serializable types - * like datetime, json, etc. - */ -namespace types { - /** - * JsonRaw defines a json value type that is safe for db read/write. - */ - interface JsonRaw extends Array{} - interface JsonRaw { - /** - * String returns the current JsonRaw instance as a json encoded string. - */ - string(): string - } - interface JsonRaw { - /** - * MarshalJSON implements the [json.Marshaler] interface. - */ - marshalJSON(): string|Array - } - interface JsonRaw { - /** - * UnmarshalJSON implements the [json.Unmarshaler] interface. - */ - unmarshalJSON(b: string|Array): void - } - interface JsonRaw { - /** - * Value implements the [driver.Valuer] interface. - */ - value(): any - } - interface JsonRaw { - /** - * Scan implements [sql.Scanner] interface to scan the provided value - * into the current JsonRaw instance. - */ - scan(value: any): void - } -} - -namespace search { - /** - * Result defines the returned search result structure. - */ - interface Result { - page: number - perPage: number - totalItems: number - totalPages: number - items: any - } -} - -/** - * Package http provides HTTP client and server implementations. - * - * Get, Head, Post, and PostForm make HTTP (or HTTPS) requests: - * - * ``` - * resp, err := http.Get("http://example.com/") - * ... - * resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf) - * ... - * resp, err := http.PostForm("http://example.com/form", - * url.Values{"key": {"Value"}, "id": {"123"}}) - * ``` - * - * The caller must close the response body when finished with it: - * - * ``` - * resp, err := http.Get("http://example.com/") - * if err != nil { - * // handle error - * } - * defer resp.Body.Close() - * body, err := io.ReadAll(resp.Body) - * // ... - * ``` - * - * # Clients and Transports - * - * For control over HTTP client headers, redirect policy, and other - * settings, create a Client: - * - * ``` - * client := &http.Client{ - * CheckRedirect: redirectPolicyFunc, - * } - * - * resp, err := client.Get("http://example.com") - * // ... - * - * req, err := http.NewRequest("GET", "http://example.com", nil) - * // ... - * req.Header.Add("If-None-Match", `W/"wyzzy"`) - * resp, err := client.Do(req) - * // ... - * ``` - * - * For control over proxies, TLS configuration, keep-alives, - * compression, and other settings, create a Transport: - * - * ``` - * tr := &http.Transport{ - * MaxIdleConns: 10, - * IdleConnTimeout: 30 * time.Second, - * DisableCompression: true, - * } - * client := &http.Client{Transport: tr} - * resp, err := client.Get("https://example.com") - * ``` - * - * Clients and Transports are safe for concurrent use by multiple - * goroutines and for efficiency should only be created once and re-used. - * - * # Servers - * - * ListenAndServe starts an HTTP server with a given address and handler. - * The handler is usually nil, which means to use DefaultServeMux. - * Handle and HandleFunc add handlers to DefaultServeMux: - * - * ``` - * http.Handle("/foo", fooHandler) - * - * http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) { - * fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path)) - * }) - * - * log.Fatal(http.ListenAndServe(":8080", nil)) - * ``` - * - * More control over the server's behavior is available by creating a - * custom Server: - * - * ``` - * s := &http.Server{ - * Addr: ":8080", - * Handler: myHandler, - * ReadTimeout: 10 * time.Second, - * WriteTimeout: 10 * time.Second, - * MaxHeaderBytes: 1 << 20, - * } - * log.Fatal(s.ListenAndServe()) - * ``` - * - * # HTTP/2 - * - * Starting with Go 1.6, the http package has transparent support for the - * HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2 - * can do so by setting Transport.TLSNextProto (for clients) or - * Server.TLSNextProto (for servers) to a non-nil, empty - * map. Alternatively, the following GODEBUG settings are - * currently supported: - * - * ``` - * GODEBUG=http2client=0 # disable HTTP/2 client support - * GODEBUG=http2server=0 # disable HTTP/2 server support - * GODEBUG=http2debug=1 # enable verbose HTTP/2 debug logs - * GODEBUG=http2debug=2 # ... even more verbose, with frame dumps - * ``` - * - * Please report any issues before disabling HTTP/2 support: https://golang.org/s/http2bug - * - * The http package's Transport and Server both automatically enable - * HTTP/2 support for simple configurations. To enable HTTP/2 for more - * complex configurations, to use lower-level HTTP/2 features, or to use - * a newer version of Go's http2 package, import "golang.org/x/net/http2" - * directly and use its ConfigureTransport and/or ConfigureServer - * functions. Manually configuring HTTP/2 via the golang.org/x/net/http2 - * package takes precedence over the net/http package's built-in HTTP/2 - * support. - */ -namespace http { - /** - * SameSite allows a server to define a cookie attribute making it impossible for - * the browser to send this cookie along with cross-site requests. The main - * goal is to mitigate the risk of cross-origin information leakage, and provide - * some protection against cross-site request forgery attacks. - * - * See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 for details. - */ - interface SameSite extends Number{} - // @ts-ignore - import mathrand = rand - // @ts-ignore - import urlpkg = url -} - -namespace mailer { - /** - * Message defines a generic email message struct. - */ - interface Message { - from: mail.Address - to: Array - bcc: Array - cc: Array - subject: string - html: string - text: string - headers: _TygojaDict - attachments: _TygojaDict - } -} - -/** - * Package echo implements high performance, minimalist Go web framework. - * - * Example: - * - * ``` - * package main - * - * import ( - * "github.com/labstack/echo/v5" - * "github.com/labstack/echo/v5/middleware" - * "log" - * "net/http" - * ) - * - * // Handler - * func hello(c echo.Context) error { - * return c.String(http.StatusOK, "Hello, World!") - * } - * - * func main() { - * // Echo instance - * e := echo.New() - * - * // Middleware - * e.Use(middleware.Logger()) - * e.Use(middleware.Recover()) - * - * // Routes - * e.GET("/", hello) - * - * // Start server - * if err := e.Start(":8080"); err != http.ErrServerClosed { - * log.Fatal(err) - * } - * } - * ``` - * - * Learn more at https://echo.labstack.com - */ -namespace echo { - // @ts-ignore - import stdContext = context - /** - * Route contains information to adding/registering new route with the router. - * Method+Path pair uniquely identifies the Route. It is mandatory to provide Method+Path+Handler fields. - */ - interface Route { - method: string - path: string - handler: HandlerFunc - middlewares: Array - name: string - } - interface Route { - /** - * ToRouteInfo converts Route to RouteInfo - */ - toRouteInfo(params: Array): RouteInfo - } - interface Route { - /** - * ToRoute returns Route which Router uses to register the method handler for path. - */ - toRoute(): Route - } - interface Route { - /** - * ForGroup recreates Route with added group prefix and group middlewares it is grouped to. - */ - forGroup(pathPrefix: string, middlewares: Array): Routable - } - /** - * RoutableContext is additional interface that structures implementing Context must implement. Methods inside this - * interface are meant for request routing purposes and should not be used in middlewares. - */ - interface RoutableContext { - [key:string]: any; - /** - * Request returns `*http.Request`. - */ - request(): (http.Request) - /** - * RawPathParams returns raw path pathParams value. Allocation of PathParams is handled by Context. - */ - rawPathParams(): (PathParams) - /** - * SetRawPathParams replaces any existing param values with new values for this context lifetime (request). - * Do not set any other value than what you got from RawPathParams as allocation of PathParams is handled by Context. - */ - setRawPathParams(params: PathParams): void - /** - * SetPath sets the registered path for the handler. - */ - setPath(p: string): void - /** - * SetRouteInfo sets the route info of this request to the context. - */ - setRouteInfo(ri: RouteInfo): void - /** - * Set saves data in the context. Allows router to store arbitrary (that only router has access to) data in context - * for later use in middlewares/handler. - */ - set(key: string, val: { - }): void - } - /** - * PathParam is tuple pf path parameter name and its value in request path - */ - interface PathParam { - name: string - value: string - } -} - -namespace settings { - // @ts-ignore - import validation = ozzo_validation - interface EmailTemplate { - body: string - subject: string - actionUrl: string - } - interface EmailTemplate { - /** - * Validate makes EmailTemplate validatable by implementing [validation.Validatable] interface. - */ - validate(): void - } - interface EmailTemplate { - /** - * Resolve replaces the placeholder parameters in the current email - * template and returns its components as ready-to-use strings. - */ - resolve(appName: string, appUrl: string): string - } -} - -namespace subscriptions { - /** - * Message defines a client's channel data. - */ - interface Message { - name: string - data: string|Array - } - /** - * Client is an interface for a generic subscription client. - */ - interface Client { - [key:string]: any; - /** - * Id Returns the unique id of the client. - */ - id(): string - /** - * Channel returns the client's communication channel. - */ - channel(): undefined - /** - * Subscriptions returns a shallow copy of the the client subscriptions matching the prefixes. - * If no prefix is specified, returns all subscriptions. - */ - subscriptions(...prefixes: string[]): _TygojaDict - /** - * Subscribe subscribes the client to the provided subscriptions list. - * - * Each subscription can also have "options" (json serialized SubscriptionOptions) as query parameter. - * - * Example: - * - * ``` - * Subscribe( - * "subscriptionA", - * `subscriptionB?options={"query":{"a":1},"headers":{"x_token":"abc"}}`, - * ) - * ``` - */ - subscribe(...subs: string[]): void - /** - * Unsubscribe unsubscribes the client from the provided subscriptions list. - */ - unsubscribe(...subs: string[]): void - /** - * HasSubscription checks if the client is subscribed to `sub`. - */ - hasSubscription(sub: string): boolean - /** - * Set stores any value to the client's context. - */ - set(key: string, value: any): void - /** - * Unset removes a single value from the client's context. - */ - unset(key: string): void - /** - * Get retrieves the key value from the client's context. - */ - get(key: string): any - /** - * Discard marks the client as "discarded", meaning that it - * shouldn't be used anymore for sending new messages. - * - * It is safe to call Discard() multiple times. - */ - discard(): void - /** - * IsDiscarded indicates whether the client has been "discarded" - * and should no longer be used. - */ - isDiscarded(): boolean - /** - * Send sends the specified message to the client's channel (if not discarded). - */ - send(m: Message): void - } -} - -/** - * Package core is the backbone of PocketBase. - * - * It defines the main PocketBase App interface and its base implementation. - */ -namespace core { - interface BaseModelEvent { - model: models.Model - } - interface BaseModelEvent { - tags(): Array - } - interface BaseCollectionEvent { - collection?: models.Collection - } - interface BaseCollectionEvent { - tags(): Array - } -} - -namespace subscriptions { -} - -/** - * Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer - * object, creating another object (Reader or Writer) that also implements - * the interface but provides buffering and some help for textual I/O. - */ -namespace bufio { - /** - * Reader implements buffering for an io.Reader object. - */ - interface Reader { - } - interface Reader { - /** - * Size returns the size of the underlying buffer in bytes. - */ - size(): number - } - interface Reader { - /** - * Reset discards any buffered data, resets all state, and switches - * the buffered reader to read from r. - * Calling Reset on the zero value of Reader initializes the internal buffer - * to the default size. - * Calling b.Reset(b) (that is, resetting a Reader to itself) does nothing. - */ - reset(r: io.Reader): void - } - interface Reader { - /** - * Peek returns the next n bytes without advancing the reader. The bytes stop - * being valid at the next read call. If Peek returns fewer than n bytes, it - * also returns an error explaining why the read is short. The error is - * ErrBufferFull if n is larger than b's buffer size. - * - * Calling Peek prevents a UnreadByte or UnreadRune call from succeeding - * until the next read operation. - */ - peek(n: number): string|Array - } - interface Reader { - /** - * Discard skips the next n bytes, returning the number of bytes discarded. - * - * If Discard skips fewer than n bytes, it also returns an error. - * If 0 <= n <= b.Buffered(), Discard is guaranteed to succeed without - * reading from the underlying io.Reader. - */ - discard(n: number): number - } - interface Reader { - /** - * Read reads data into p. - * It returns the number of bytes read into p. - * The bytes are taken from at most one Read on the underlying Reader, - * hence n may be less than len(p). - * To read exactly len(p) bytes, use io.ReadFull(b, p). - * If the underlying Reader can return a non-zero count with io.EOF, - * then this Read method can do so as well; see the [io.Reader] docs. - */ - read(p: string|Array): number - } - interface Reader { - /** - * ReadByte reads and returns a single byte. - * If no byte is available, returns an error. - */ - readByte(): number - } - interface Reader { - /** - * UnreadByte unreads the last byte. Only the most recently read byte can be unread. - * - * UnreadByte returns an error if the most recent method called on the - * Reader was not a read operation. Notably, Peek, Discard, and WriteTo are not - * considered read operations. - */ - unreadByte(): void - } - interface Reader { - /** - * ReadRune reads a single UTF-8 encoded Unicode character and returns the - * rune and its size in bytes. If the encoded rune is invalid, it consumes one byte - * and returns unicode.ReplacementChar (U+FFFD) with a size of 1. - */ - readRune(): [number, number] + * to ensure that each record is written in one piece. User-defined + * handlers are responsible for their own locking. + * + * # Writing a handler + * + * For a guide to writing a custom handler, see https://golang.org/s/slog-handler-guide. + */ +namespace slog { + /** + * An Attr is a key-value pair. + */ + interface Attr { + key: string + value: Value } - interface Reader { + interface Attr { /** - * UnreadRune unreads the last rune. If the most recent method called on - * the Reader was not a ReadRune, UnreadRune returns an error. (In this - * regard it is stricter than UnreadByte, which will unread the last byte - * from any read operation.) + * Equal reports whether a and b have equal keys and values. */ - unreadRune(): void + equal(b: Attr): boolean } - interface Reader { - /** - * Buffered returns the number of bytes that can be read from the current buffer. - */ - buffered(): number + interface Attr { + string(): string } - interface Reader { + /** + * A Handler handles log records produced by a Logger.. + * + * A typical handler may print log records to standard error, + * or write them to a file or database, or perhaps augment them + * with additional attributes and pass them on to another handler. + * + * Any of the Handler's methods may be called concurrently with itself + * or with other methods. It is the responsibility of the Handler to + * manage this concurrency. + * + * Users of the slog package should not invoke Handler methods directly. + * They should use the methods of [Logger] instead. + */ + interface Handler { + [key:string]: any; /** - * ReadSlice reads until the first occurrence of delim in the input, - * returning a slice pointing at the bytes in the buffer. - * The bytes stop being valid at the next read. - * If ReadSlice encounters an error before finding a delimiter, - * it returns all the data in the buffer and the error itself (often io.EOF). - * ReadSlice fails with error ErrBufferFull if the buffer fills without a delim. - * Because the data returned from ReadSlice will be overwritten - * by the next I/O operation, most clients should use - * ReadBytes or ReadString instead. - * ReadSlice returns err != nil if and only if line does not end in delim. + * Enabled reports whether the handler handles records at the given level. + * The handler ignores records whose level is lower. + * It is called early, before any arguments are processed, + * to save effort if the log event should be discarded. + * If called from a Logger method, the first argument is the context + * passed to that method, or context.Background() if nil was passed + * or the method does not take a context. + * The context is passed so Enabled can use its values + * to make a decision. */ - readSlice(delim: number): string|Array - } - interface Reader { + enabled(_arg0: context.Context, _arg1: Level): boolean /** - * ReadLine is a low-level line-reading primitive. Most callers should use - * ReadBytes('\n') or ReadString('\n') instead or use a Scanner. - * - * ReadLine tries to return a single line, not including the end-of-line bytes. - * If the line was too long for the buffer then isPrefix is set and the - * beginning of the line is returned. The rest of the line will be returned - * from future calls. isPrefix will be false when returning the last fragment - * of the line. The returned buffer is only valid until the next call to - * ReadLine. ReadLine either returns a non-nil line or it returns an error, - * never both. + * Handle handles the Record. + * It will only be called when Enabled returns true. + * The Context argument is as for Enabled. + * It is present solely to provide Handlers access to the context's values. + * Canceling the context should not affect record processing. + * (Among other things, log messages may be necessary to debug a + * cancellation-related problem.) * - * The text returned from ReadLine does not include the line end ("\r\n" or "\n"). - * No indication or error is given if the input ends without a final line end. - * Calling UnreadByte after ReadLine will always unread the last byte read - * (possibly a character belonging to the line end) even if that byte is not - * part of the line returned by ReadLine. - */ - readLine(): [string|Array, boolean] - } - interface Reader { - /** - * ReadBytes reads until the first occurrence of delim in the input, - * returning a slice containing the data up to and including the delimiter. - * If ReadBytes encounters an error before finding a delimiter, - * it returns the data read before the error and the error itself (often io.EOF). - * ReadBytes returns err != nil if and only if the returned data does not end in - * delim. - * For simple uses, a Scanner may be more convenient. + * Handle methods that produce output should observe the following rules: + * ``` + * - If r.Time is the zero time, ignore the time. + * - If r.PC is zero, ignore it. + * - Attr's values should be resolved. + * - If an Attr's key and value are both the zero value, ignore the Attr. + * This can be tested with attr.Equal(Attr{}). + * - If a group's key is empty, inline the group's Attrs. + * - If a group has no Attrs (even if it has a non-empty key), + * ignore it. + * ``` */ - readBytes(delim: number): string|Array - } - interface Reader { + handle(_arg0: context.Context, _arg1: Record): void /** - * ReadString reads until the first occurrence of delim in the input, - * returning a string containing the data up to and including the delimiter. - * If ReadString encounters an error before finding a delimiter, - * it returns the data read before the error and the error itself (often io.EOF). - * ReadString returns err != nil if and only if the returned data does not end in - * delim. - * For simple uses, a Scanner may be more convenient. + * WithAttrs returns a new Handler whose attributes consist of + * both the receiver's attributes and the arguments. + * The Handler owns the slice: it may retain, modify or discard it. */ - readString(delim: number): string - } - interface Reader { + withAttrs(attrs: Array): Handler /** - * WriteTo implements io.WriterTo. - * This may make multiple calls to the Read method of the underlying Reader. - * If the underlying reader supports the WriteTo method, - * this calls the underlying WriteTo without buffering. + * WithGroup returns a new Handler with the given group appended to + * the receiver's existing groups. + * The keys of all subsequent attributes, whether added by With or in a + * Record, should be qualified by the sequence of group names. + * + * How this qualification happens is up to the Handler, so long as + * this Handler's attribute keys differ from those of another Handler + * with a different sequence of group names. + * + * A Handler should treat WithGroup as starting a Group of Attrs that ends + * at the end of the log event. That is, + * + * ``` + * logger.WithGroup("s").LogAttrs(level, msg, slog.Int("a", 1), slog.Int("b", 2)) + * ``` + * + * should behave like + * + * ``` + * logger.LogAttrs(level, msg, slog.Group("s", slog.Int("a", 1), slog.Int("b", 2))) + * ``` + * + * If the name is empty, WithGroup returns the receiver. */ - writeTo(w: io.Writer): number + withGroup(name: string): Handler } /** - * Writer implements buffering for an io.Writer object. - * If an error occurs writing to a Writer, no more data will be - * accepted and all subsequent writes, and Flush, will return the error. - * After all data has been written, the client should call the - * Flush method to guarantee all data has been forwarded to - * the underlying io.Writer. + * A Level is the importance or severity of a log event. + * The higher the level, the more important or severe the event. */ - interface Writer { - } - interface Writer { - /** - * Size returns the size of the underlying buffer in bytes. - */ - size(): number - } - interface Writer { - /** - * Reset discards any unflushed buffered data, clears any error, and - * resets b to write its output to w. - * Calling Reset on the zero value of Writer initializes the internal buffer - * to the default size. - * Calling w.Reset(w) (that is, resetting a Writer to itself) does nothing. - */ - reset(w: io.Writer): void - } - interface Writer { - /** - * Flush writes any buffered data to the underlying io.Writer. - */ - flush(): void - } - interface Writer { - /** - * Available returns how many bytes are unused in the buffer. - */ - available(): number - } - interface Writer { + interface Level extends Number{} + interface Level { /** - * AvailableBuffer returns an empty buffer with b.Available() capacity. - * This buffer is intended to be appended to and - * passed to an immediately succeeding Write call. - * The buffer is only valid until the next write operation on b. + * String returns a name for the level. + * If the level has a name, then that name + * in uppercase is returned. + * If the level is between named values, then + * an integer is appended to the uppercased name. + * Examples: + * + * ``` + * LevelWarn.String() => "WARN" + * (LevelInfo+2).String() => "INFO+2" + * ``` */ - availableBuffer(): string|Array + string(): string } - interface Writer { + interface Level { /** - * Buffered returns the number of bytes that have been written into the current buffer. + * MarshalJSON implements [encoding/json.Marshaler] + * by quoting the output of [Level.String]. */ - buffered(): number + marshalJSON(): string|Array } - interface Writer { + interface Level { /** - * Write writes the contents of p into the buffer. - * It returns the number of bytes written. - * If nn < len(p), it also returns an error explaining - * why the write is short. + * UnmarshalJSON implements [encoding/json.Unmarshaler] + * It accepts any string produced by [Level.MarshalJSON], + * ignoring case. + * It also accepts numeric offsets that would result in a different string on + * output. For example, "Error-8" would marshal as "INFO". */ - write(p: string|Array): number + unmarshalJSON(data: string|Array): void } - interface Writer { + interface Level { /** - * WriteByte writes a single byte. + * MarshalText implements [encoding.TextMarshaler] + * by calling [Level.String]. */ - writeByte(c: number): void + marshalText(): string|Array } - interface Writer { + interface Level { /** - * WriteRune writes a single Unicode code point, returning - * the number of bytes written and any error. + * UnmarshalText implements [encoding.TextUnmarshaler]. + * It accepts any string produced by [Level.MarshalText], + * ignoring case. + * It also accepts numeric offsets that would result in a different string on + * output. For example, "Error-8" would marshal as "INFO". */ - writeRune(r: number): number + unmarshalText(data: string|Array): void } - interface Writer { + interface Level { /** - * WriteString writes a string. - * It returns the number of bytes written. - * If the count is less than len(s), it also returns an error explaining - * why the write is short. + * Level returns the receiver. + * It implements Leveler. */ - writeString(s: string): number + level(): Level } - interface Writer { - /** - * ReadFrom implements io.ReaderFrom. If the underlying writer - * supports the ReadFrom method, this calls the underlying ReadFrom. - * If there is buffered data and an underlying ReadFrom, this fills - * the buffer and writes it before calling ReadFrom. - */ - readFrom(r: io.Reader): number + // @ts-ignore + import loginternal = internal +} + +namespace hook { + /** + * Handler defines a hook handler function. + */ + interface Handler {(e: T): void } + /** + * wrapped local Hook embedded struct to limit the public API surface. + */ + type _subTlzch = Hook + interface mainHook extends _subTlzch { } } +/** + * Package core is the backbone of PocketBase. + * + * It defines the main PocketBase App interface and its base implementation. + */ +namespace core { + interface BaseModelEvent { + model: models.Model + } + interface BaseModelEvent { + tags(): Array + } + interface BaseCollectionEvent { + collection?: models.Collection + } + interface BaseCollectionEvent { + tags(): Array + } +} + +namespace subscriptions { +} + /** * Package slog provides structured logging, * in which log records include a message, @@ -19816,161 +19571,426 @@ namespace slog { /** * The time at which the output method (Log, Info, etc.) was called. */ - time: time.Time + time: time.Time + /** + * The log message. + */ + message: string + /** + * The level of the event. + */ + level: Level + /** + * The program counter at the time the record was constructed, as determined + * by runtime.Callers. If zero, no program counter is available. + * + * The only valid use for this value is as an argument to + * [runtime.CallersFrames]. In particular, it must not be passed to + * [runtime.FuncForPC]. + */ + pc: number + } + interface Record { + /** + * Clone returns a copy of the record with no shared state. + * The original record and the clone can both be modified + * without interfering with each other. + */ + clone(): Record + } + interface Record { + /** + * NumAttrs returns the number of attributes in the Record. + */ + numAttrs(): number + } + interface Record { + /** + * Attrs calls f on each Attr in the Record. + * Iteration stops if f returns false. + */ + attrs(f: (_arg0: Attr) => boolean): void + } + interface Record { + /** + * AddAttrs appends the given Attrs to the Record's list of Attrs. + * It omits empty groups. + */ + addAttrs(...attrs: Attr[]): void + } + interface Record { + /** + * Add converts the args to Attrs as described in [Logger.Log], + * then appends the Attrs to the Record's list of Attrs. + * It omits empty groups. + */ + add(...args: any[]): void + } + /** + * A Value can represent any Go value, but unlike type any, + * it can represent most small values without an allocation. + * The zero Value corresponds to nil. + */ + interface Value { + } + interface Value { + /** + * Kind returns v's Kind. + */ + kind(): Kind + } + interface Value { + /** + * Any returns v's value as an any. + */ + any(): any + } + interface Value { + /** + * String returns Value's value as a string, formatted like fmt.Sprint. Unlike + * the methods Int64, Float64, and so on, which panic if v is of the + * wrong kind, String never panics. + */ + string(): string + } + interface Value { + /** + * Int64 returns v's value as an int64. It panics + * if v is not a signed integer. + */ + int64(): number + } + interface Value { + /** + * Uint64 returns v's value as a uint64. It panics + * if v is not an unsigned integer. + */ + uint64(): number + } + interface Value { + /** + * Bool returns v's value as a bool. It panics + * if v is not a bool. + */ + bool(): boolean + } + interface Value { + /** + * Duration returns v's value as a time.Duration. It panics + * if v is not a time.Duration. + */ + duration(): time.Duration + } + interface Value { + /** + * Float64 returns v's value as a float64. It panics + * if v is not a float64. + */ + float64(): number + } + interface Value { + /** + * Time returns v's value as a time.Time. It panics + * if v is not a time.Time. + */ + time(): time.Time + } + interface Value { + /** + * LogValuer returns v's value as a LogValuer. It panics + * if v is not a LogValuer. + */ + logValuer(): LogValuer + } + interface Value { + /** + * Group returns v's value as a []Attr. + * It panics if v's Kind is not KindGroup. + */ + group(): Array + } + interface Value { + /** + * Equal reports whether v and w represent the same Go value. + */ + equal(w: Value): boolean + } + interface Value { + /** + * Resolve repeatedly calls LogValue on v while it implements LogValuer, + * and returns the result. + * If v resolves to a group, the group's attributes' values are not recursively + * resolved. + * If the number of LogValue calls exceeds a threshold, a Value containing an + * error is returned. + * Resolve's return value is guaranteed not to be of Kind KindLogValuer. + */ + resolve(): Value + } +} + +/** + * Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer + * object, creating another object (Reader or Writer) that also implements + * the interface but provides buffering and some help for textual I/O. + */ +namespace bufio { + /** + * Reader implements buffering for an io.Reader object. + */ + interface Reader { + } + interface Reader { + /** + * Size returns the size of the underlying buffer in bytes. + */ + size(): number + } + interface Reader { + /** + * Reset discards any buffered data, resets all state, and switches + * the buffered reader to read from r. + * Calling Reset on the zero value of Reader initializes the internal buffer + * to the default size. + * Calling b.Reset(b) (that is, resetting a Reader to itself) does nothing. + */ + reset(r: io.Reader): void + } + interface Reader { + /** + * Peek returns the next n bytes without advancing the reader. The bytes stop + * being valid at the next read call. If Peek returns fewer than n bytes, it + * also returns an error explaining why the read is short. The error is + * ErrBufferFull if n is larger than b's buffer size. + * + * Calling Peek prevents a UnreadByte or UnreadRune call from succeeding + * until the next read operation. + */ + peek(n: number): string|Array + } + interface Reader { + /** + * Discard skips the next n bytes, returning the number of bytes discarded. + * + * If Discard skips fewer than n bytes, it also returns an error. + * If 0 <= n <= b.Buffered(), Discard is guaranteed to succeed without + * reading from the underlying io.Reader. + */ + discard(n: number): number + } + interface Reader { /** - * The log message. + * Read reads data into p. + * It returns the number of bytes read into p. + * The bytes are taken from at most one Read on the underlying Reader, + * hence n may be less than len(p). + * To read exactly len(p) bytes, use io.ReadFull(b, p). + * If the underlying Reader can return a non-zero count with io.EOF, + * then this Read method can do so as well; see the [io.Reader] docs. */ - message: string + read(p: string|Array): number + } + interface Reader { /** - * The level of the event. + * ReadByte reads and returns a single byte. + * If no byte is available, returns an error. */ - level: Level + readByte(): number + } + interface Reader { /** - * The program counter at the time the record was constructed, as determined - * by runtime.Callers. If zero, no program counter is available. + * UnreadByte unreads the last byte. Only the most recently read byte can be unread. * - * The only valid use for this value is as an argument to - * [runtime.CallersFrames]. In particular, it must not be passed to - * [runtime.FuncForPC]. + * UnreadByte returns an error if the most recent method called on the + * Reader was not a read operation. Notably, Peek, Discard, and WriteTo are not + * considered read operations. */ - pc: number + unreadByte(): void } - interface Record { + interface Reader { /** - * Clone returns a copy of the record with no shared state. - * The original record and the clone can both be modified - * without interfering with each other. + * ReadRune reads a single UTF-8 encoded Unicode character and returns the + * rune and its size in bytes. If the encoded rune is invalid, it consumes one byte + * and returns unicode.ReplacementChar (U+FFFD) with a size of 1. */ - clone(): Record + readRune(): [number, number] } - interface Record { + interface Reader { /** - * NumAttrs returns the number of attributes in the Record. + * UnreadRune unreads the last rune. If the most recent method called on + * the Reader was not a ReadRune, UnreadRune returns an error. (In this + * regard it is stricter than UnreadByte, which will unread the last byte + * from any read operation.) */ - numAttrs(): number + unreadRune(): void } - interface Record { + interface Reader { /** - * Attrs calls f on each Attr in the Record. - * Iteration stops if f returns false. + * Buffered returns the number of bytes that can be read from the current buffer. */ - attrs(f: (_arg0: Attr) => boolean): void + buffered(): number } - interface Record { + interface Reader { /** - * AddAttrs appends the given Attrs to the Record's list of Attrs. - * It omits empty groups. + * ReadSlice reads until the first occurrence of delim in the input, + * returning a slice pointing at the bytes in the buffer. + * The bytes stop being valid at the next read. + * If ReadSlice encounters an error before finding a delimiter, + * it returns all the data in the buffer and the error itself (often io.EOF). + * ReadSlice fails with error ErrBufferFull if the buffer fills without a delim. + * Because the data returned from ReadSlice will be overwritten + * by the next I/O operation, most clients should use + * ReadBytes or ReadString instead. + * ReadSlice returns err != nil if and only if line does not end in delim. */ - addAttrs(...attrs: Attr[]): void + readSlice(delim: number): string|Array } - interface Record { + interface Reader { /** - * Add converts the args to Attrs as described in [Logger.Log], - * then appends the Attrs to the Record's list of Attrs. - * It omits empty groups. + * ReadLine is a low-level line-reading primitive. Most callers should use + * ReadBytes('\n') or ReadString('\n') instead or use a Scanner. + * + * ReadLine tries to return a single line, not including the end-of-line bytes. + * If the line was too long for the buffer then isPrefix is set and the + * beginning of the line is returned. The rest of the line will be returned + * from future calls. isPrefix will be false when returning the last fragment + * of the line. The returned buffer is only valid until the next call to + * ReadLine. ReadLine either returns a non-nil line or it returns an error, + * never both. + * + * The text returned from ReadLine does not include the line end ("\r\n" or "\n"). + * No indication or error is given if the input ends without a final line end. + * Calling UnreadByte after ReadLine will always unread the last byte read + * (possibly a character belonging to the line end) even if that byte is not + * part of the line returned by ReadLine. */ - add(...args: any[]): void + readLine(): [string|Array, boolean] } - /** - * A Value can represent any Go value, but unlike type any, - * it can represent most small values without an allocation. - * The zero Value corresponds to nil. - */ - interface Value { + interface Reader { + /** + * ReadBytes reads until the first occurrence of delim in the input, + * returning a slice containing the data up to and including the delimiter. + * If ReadBytes encounters an error before finding a delimiter, + * it returns the data read before the error and the error itself (often io.EOF). + * ReadBytes returns err != nil if and only if the returned data does not end in + * delim. + * For simple uses, a Scanner may be more convenient. + */ + readBytes(delim: number): string|Array } - interface Value { + interface Reader { /** - * Kind returns v's Kind. + * ReadString reads until the first occurrence of delim in the input, + * returning a string containing the data up to and including the delimiter. + * If ReadString encounters an error before finding a delimiter, + * it returns the data read before the error and the error itself (often io.EOF). + * ReadString returns err != nil if and only if the returned data does not end in + * delim. + * For simple uses, a Scanner may be more convenient. */ - kind(): Kind + readString(delim: number): string } - interface Value { + interface Reader { /** - * Any returns v's value as an any. + * WriteTo implements io.WriterTo. + * This may make multiple calls to the Read method of the underlying Reader. + * If the underlying reader supports the WriteTo method, + * this calls the underlying WriteTo without buffering. */ - any(): any + writeTo(w: io.Writer): number } - interface Value { + /** + * Writer implements buffering for an io.Writer object. + * If an error occurs writing to a Writer, no more data will be + * accepted and all subsequent writes, and Flush, will return the error. + * After all data has been written, the client should call the + * Flush method to guarantee all data has been forwarded to + * the underlying io.Writer. + */ + interface Writer { + } + interface Writer { /** - * String returns Value's value as a string, formatted like fmt.Sprint. Unlike - * the methods Int64, Float64, and so on, which panic if v is of the - * wrong kind, String never panics. + * Size returns the size of the underlying buffer in bytes. */ - string(): string + size(): number } - interface Value { + interface Writer { /** - * Int64 returns v's value as an int64. It panics - * if v is not a signed integer. + * Reset discards any unflushed buffered data, clears any error, and + * resets b to write its output to w. + * Calling Reset on the zero value of Writer initializes the internal buffer + * to the default size. + * Calling w.Reset(w) (that is, resetting a Writer to itself) does nothing. */ - int64(): number + reset(w: io.Writer): void } - interface Value { + interface Writer { /** - * Uint64 returns v's value as a uint64. It panics - * if v is not an unsigned integer. + * Flush writes any buffered data to the underlying io.Writer. */ - uint64(): number + flush(): void } - interface Value { + interface Writer { /** - * Bool returns v's value as a bool. It panics - * if v is not a bool. + * Available returns how many bytes are unused in the buffer. */ - bool(): boolean + available(): number } - interface Value { + interface Writer { /** - * Duration returns v's value as a time.Duration. It panics - * if v is not a time.Duration. + * AvailableBuffer returns an empty buffer with b.Available() capacity. + * This buffer is intended to be appended to and + * passed to an immediately succeeding Write call. + * The buffer is only valid until the next write operation on b. */ - duration(): time.Duration + availableBuffer(): string|Array } - interface Value { + interface Writer { /** - * Float64 returns v's value as a float64. It panics - * if v is not a float64. + * Buffered returns the number of bytes that have been written into the current buffer. */ - float64(): number + buffered(): number } - interface Value { + interface Writer { /** - * Time returns v's value as a time.Time. It panics - * if v is not a time.Time. + * Write writes the contents of p into the buffer. + * It returns the number of bytes written. + * If nn < len(p), it also returns an error explaining + * why the write is short. */ - time(): time.Time + write(p: string|Array): number } - interface Value { + interface Writer { /** - * LogValuer returns v's value as a LogValuer. It panics - * if v is not a LogValuer. + * WriteByte writes a single byte. */ - logValuer(): LogValuer + writeByte(c: number): void } - interface Value { + interface Writer { /** - * Group returns v's value as a []Attr. - * It panics if v's Kind is not KindGroup. + * WriteRune writes a single Unicode code point, returning + * the number of bytes written and any error. */ - group(): Array + writeRune(r: number): number } - interface Value { + interface Writer { /** - * Equal reports whether v and w represent the same Go value. + * WriteString writes a string. + * It returns the number of bytes written. + * If the count is less than len(s), it also returns an error explaining + * why the write is short. */ - equal(w: Value): boolean + writeString(s: string): number } - interface Value { + interface Writer { /** - * Resolve repeatedly calls LogValue on v while it implements LogValuer, - * and returns the result. - * If v resolves to a group, the group's attributes' values are not recursively - * resolved. - * If the number of LogValue calls exceeds a threshold, a Value containing an - * error is returned. - * Resolve's return value is guaranteed not to be of Kind KindLogValuer. + * ReadFrom implements io.ReaderFrom. If the underlying writer + * supports the ReadFrom method, this calls the underlying ReadFrom. + * If there is buffered data and an underlying ReadFrom, this fills + * the buffer and writes it before calling ReadFrom. */ - resolve(): Value + readFrom(r: io.Reader): number } } @@ -19981,9 +20001,6 @@ namespace slog { namespace types { } -namespace search { -} - /** * Package mail implements parsing of mail messages. * @@ -20020,6 +20037,9 @@ namespace mail { } } +namespace search { +} + /** * Package slog provides structured logging, * in which log records include a message, diff --git a/src/components/.gitkeep b/src/components/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/helpers/pocketbase.ts b/src/helpers/pocketbase.ts index 1e30da4..e20183a 100644 --- a/src/helpers/pocketbase.ts +++ b/src/helpers/pocketbase.ts @@ -4,20 +4,18 @@ import Pocketbase from 'pocketbase' var pb: Pocketbase // -- Server -if (typeof window === 'undefined') { - if (process.env.COMPOSE_PROFILES?.toLocaleLowerCase() != 'prod') pb = new Pocketbase('http://0.0.0.0:8090') - else pb = new Pocketbase('http://pocketbase:' + process.env.POCKETBASE_PORT) -} +if (typeof window === 'undefined') pb = new Pocketbase('http://pocketbase:8090') // -- Client else { - pb = new Pocketbase(process.env.NEXT_PUBLIC_POCKETBASE_URL) + pb = new Pocketbase(window.location.protocol + '//' + window.location.host + '/pb') + // Cookie handler, loads and updates the pb_auth cookie. pb.authStore.loadFromCookie(document.cookie) + pb.authStore.onChange(() => document.cookie = pb.authStore.exportToCookie({ httpOnly: false })) - pb.authStore.onChange(() => { - document.cookie = pb.authStore.exportToCookie({ httpOnly: false }) - }) + // Prevents exceptions, nextjs in dev-mode executes useEffects twice whilst react-strict mode is on. + if (process && process.env.NODE_ENV === 'development') pb.autoCancellation(false) } export default pb diff --git a/tailwind.config.ts b/tailwind.config.ts index 5bdf25d..ba0c422 100644 --- a/tailwind.config.ts +++ b/tailwind.config.ts @@ -11,7 +11,7 @@ module.exports = { // ----- Recommended ----- // Use https://realtimecolors.com to pick your palette, - // then supply https://uicolors.app/create with your colors + // then supply https://tailwindshades.com with your colors // to generate the objects that are required below. primary: { @@ -56,6 +56,7 @@ module.exports = { 900: '#000000', 950: '#000000' } + } } }