{"id":19425893,"url":"https://github.com/catchthetornado/askql","last_synced_at":"2025-04-05T13:08:59.711Z","repository":{"id":39214601,"uuid":"258495744","full_name":"CatchTheTornado/askql","owner":"CatchTheTornado","description":"AskQL is a query language that can express any data request","archived":false,"fork":false,"pushed_at":"2023-03-08T11:53:24.000Z","size":7478,"stargazers_count":390,"open_issues_count":179,"forks_count":29,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-29T12:08:52.558Z","etag":null,"topics":["api","graphql","hacktoberfest","integration","nodejs","programming-language","query-language","rest-api","typescript"],"latest_commit_sha":null,"homepage":"https://askql.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CatchTheTornado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-04-24T11:39:31.000Z","updated_at":"2025-03-19T22:46:01.000Z","dependencies_parsed_at":"2024-01-06T07:53:16.811Z","dependency_job_id":"8fcebcba-a244-4052-bbd4-24607778ec27","html_url":"https://github.com/CatchTheTornado/askql","commit_stats":null,"previous_names":["xfaang/askql"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatchTheTornado%2Faskql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatchTheTornado%2Faskql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatchTheTornado%2Faskql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatchTheTornado%2Faskql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CatchTheTornado","download_url":"https://codeload.github.com/CatchTheTornado/askql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","graphql","hacktoberfest","integration","nodejs","programming-language","query-language","rest-api","typescript"],"created_at":"2024-11-10T14:05:18.859Z","updated_at":"2025-04-05T13:08:59.685Z","avatar_url":"https://github.com/CatchTheTornado.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://askql.org\"\u003e\n    \u003cimg src=\"https://xfaang-assets.s3.eu-west-3.amazonaws.com/logo/askql-logo-OW-cut.png\" title=\"AskQL Logo\" width=\"200\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# [AskQL](https://askql.org/)\n\n**AskQL is the next step after GraphQL and Serverless**. \n\nWith AskQL developers can attach scripts to queries that are executed serverside. The AskQL parser accepts the GraphQL query format so there's **no learning curve**. Because the scripts are executed serverside and the results [can be cached](#584) it's great for Web Vitals and app performance. Think of it as a **programmable GraphQL**.\n\nRead a great articly on [AskQL as a GraphQL alternative](https://yonatankra.com/on-covid-19-graphql-and-askql/)\n\n**Deploy your dynamic JAMStack, Mobile, CMS apps with no backend development required.**\n\nBy doing so frontend developers needing additional API endpoints are no longer bound by the backend development release cycles. They can send the middleware/endpoint code along with the query. No deployments, no custom resolvers, lambdas required.\n\n**It's safe**\n\nAskQL uses the isolated Virtual Machine to execute the scripts and the resources concept that let you fully controll what integrations, collections and other data sources are accessible to the scripts. Moreover features like [Access management](#583) and [Secrets management](#581) are on their way.\n\n**Business loves it**\n\nWe're working on a set of built in resources integrating AskQL with [MACH data sources](https://machalliance.org/) like eCommerce platforms **(SFCC, Commercetools)**, databases **(MongoDB, MySQL)** etc. By having it all in - frontend devs can directly access the data sources, processing the data server-side, with no additional API endpoints, middlewares required. It' shortening the integration time a lot,\n\nBy the way, it's a Turning-complete query and programming language :-)\n\n[![](http://img.youtube.com/vi/DZg9Ux2gzsA/0.jpg)](http://www.youtube.com/watch?v=DZg9Ux2gzsA \"\")\n\n## Getting started\n\nAskQL comes with whole variety of default resources (resource is equivalent of GraphQL resolver). You should definitely read the **[Introduction to AskQL](https://yonatankra.com/introduction-to-askql/)** by @YonatanKra and **[AskQL Quickstart](https://yonatankra.com/askql-nodejs-quickstart/)**\n\n## Why and what for?\n\n\u003cimg \n    src=\"https://xfaang-assets.s3.eu-west-3.amazonaws.com/diagrams/REST_API_approach.png\" \n    align=\"center\"\n    title=\"Rest\"\n    height=50%\n    width=50%\u003e\u003cimg \n    src=\"https://xfaang-assets.s3.eu-west-3.amazonaws.com/diagrams/AskQL_approach-update-july2020.jpg\" \n    align=\"center\"\n    title=\"AskQL\"\n    height=50%\n    width=50%\u003e\n\nBenefits for development process:\n\n- Next milestone after GraphQL and REST API\n- New safe query language extedning the GraphQL syntax\n- Send code to servers without the need to deploy\n- Send executable code instead of JSONs\n- Give the frontend developers more freedom, simplifying the dev process to single layer\n\nBenefits for programmers:\n\n- Asynchronous by default, no more `await` keyword - cleaner code\n- Processes only immutable data - fewer errors\n- Compiled to a clean functional code - clear logic\n\nBenefits for business:\n\n- We're working on a set of built in resources integrating AskQL with MACH data sources like eCommerce platforms (SFCC, Commercetools), databases (MongoDB, MySQL) etc. It' shortening the integration time a lot,\n- Leaner, straightforward app development process and low maintenance cost - you built just the frontend app, no backend app is required.\n\n### Prerequisites\n\n`node \u003e=12.14`\n\n## Roadmap\n\nYou can use AskQL right away - both as the CLI scripting for extending your Node's app or as a GraphQL endpoint alternative. Howeve'r were working an some cool features making it even easier for business use-cases and You're invited to contribute :)\n\n- [Namespacing support - #579](https://github.com/CatchTheTornado/askql/issues/579)\n- [Add Secrets management feature - #581](https://github.com/CatchTheTornado/askql/issues/581)\n- [Access control and session management - #583](https://github.com/CatchTheTornado/askql/issues/583)\n- [Add stored procedures/persited/hash queries - #584](https://github.com/CatchTheTornado/askql/issues/584)\n- [Add HTTP GET variables access to AskScript - #585](https://github.com/CatchTheTornado/askql/issues/585)\n- [TypeScript SDK - #586](https://github.com/CatchTheTornado/askql/issues/586)\n- [Add React Context and/or hooks for querying AskQL endpoints - #587](https://github.com/CatchTheTornado/askql/issues/587)\n\n## Quick Start\n\n### Installation\n\nIn your Node project run:\n\n```\nnpm install askql\n```\n\n### Usage\n\nYou can use AskQL interpreter for variety of use cases:\n\n- **Ultimate endpoint** accpeting the extended GraphQL queries\n\nSample server. [Checkout full demo](https://github.com/YonatanKra/askql-demo) from @YonatanKra repo.\n\n```js\nimport askql from \"askql\";\nimport express from 'express';\nimport bodyParser from 'body-parser';\n\nconst { askExpressMiddleware } = middlewareFactory;\nconst { resources } = askql; // resources available to AskQL Scripts\nconst values = { }; // values available to AskQL scripts\n\nexport const askMiddleware = askExpressMiddleware(\n    { resources, values },\n    { callNext: true, passError: true }\n);\n\nconst port = 8080;\nconst app = express();\n\napp.use(express.static('public'));\n\napp.use(bodyParser.json());\napp.use(bodyParser.urlencoded({extended: true}));\napp.post('/ask', [askMiddleware]);\n\napp.listen(port, () =\u003e {\n    console.log(`AskQL listening at http://localhost:${port}`);\n});\n```\n\n- **CLI appps** acting a query language\n\nSample index.js file:\n\n```js\nconst askql = require(\"askql\");\n\n(async () =\u003e {\n  const result = await askql.runUntyped(\n    { resources: askql.askvm.resources },\n    askql.parse(\"ask { 'hello world!' }\")\n  );\n\n  console.log(JSON.stringify(result, null, 2));\n})();\n```\n\n[👉 More examples](https://github.com/xFAANG/askql/tree/master/src/askscript/__tests__)\n\n\n## Examples\n\nAskQL comes with whole variety of default resources (resource is equivalent of GraphQL resolver). You should definitely read the [Introduction to AskQL](https://yonatankra.com/introduction-to-askql/) by @YonatanKra and [AskQL Quickstart](https://yonatankra.com/askql-nodejs-quickstart/)\n\nQuery the Star Wars characters with AskQL and the [`fetch` builtin resource](https://github.com/CatchTheTornado/askql/blob/master/src/askvm/resources/node/fetch.ts):\n\n```js\nask {\n\tfetch('https://swapi.dev/api/people'):at('results'):map(fun(swCharacter) {\n    {\n      Name: swCharacter.name,\n      Gender: swCharacter.gender,\n      'Hair Color': swCharacter.hair_color\n    }\n  })\n}\n```\n\n## Development \u0026 Contributing\n\nPlease find all important information here:\n\n[Contributing guidelines](https://github.com/xFAANG/askql/blob/master/CONTRIBUTING.md)\n\n## Installation from source\n\n1. Clone the repository\n\n   `git clone git@github.com:xFAANG/askql.git`\n\n2. For Linux it is advised to install autoreconf as it is used by one of the Node packages used by AskScript Playground.\n\n   For Ubuntu/Debian run: `sudo apt-get install autoconf`\n\n3. Install dependencies:\n   `npm i`\n\n4. Build the project:\n   `npm run build`\n\n5. Link the project to askql command:\n   `npm link`\n\n6. Now you should be able to launch the interpreter (we use REPL for that):\n   `askql`\n\n## Code examples\n\nYou can find all the examples in `__tests__` folders (e.g. [👉 AskScript tests](https://github.com/xFAANG/askql/tree/master/src/askscript/__tests__)) or in the Usage section below.\n\n## Documentation\n\nFind AskQL documentation [here](https://www.notion.so/AskQL-Documentation-cd065c579d0c44d381ddddc4682f5736).\u003cbr\u003e\n\nThe Documentation is divided into 4 parts:\u003cbr\u003e\n\n- [AskQL Overview](https://www.notion.so/AskQL-Overview-198fc4dd0b084cfa94eb4147bee71fb0)\n- [AskQL Quick Guide](https://www.notion.so/AskQL-Quick-Guide-576232203717426d84731fe76b33818f)\n- [AskScript - Human Friendly Language for AskScript](https://www.notion.so/AskScript-Human-Friendly-Language-for-AskQL-7363b28b745d499384230420eea667bc)\n\n### Try It Yourself\n\nDo not hesitate to try it out yourself! You can also find fellow AskQL devs in our [Discord community](https://discord.gg/pYdzypH).\n\u003cbr\u003e\n\n## Tools\n\n### CLI (AskScript interpreter)\n\nSimilar to `python` or `node`, AskScript CLI allows the user to type AskScript programs and get immediate result.\n\nIn order to run CLI:\n\n1.  Build the code:\n\n        npm run build\n\n1.  Run:\n\n        node dist/cli.js\n\nEvery input is treated as an AskScript program. For convenience, CLI expects just the body of your program, without `ask{` `}`.\n\nThe editor has 2 modes - a default single-line mode and a multiline mode.\n\nIn order to enter the multiline mode, please type `.editor`.\n\nAt the end of your multiline input please press Ctrl+D.\n\n        $ node dist/cli.js\n        🦄 .editor\n        // Entering editor mode (^D to finish, ^C to cancel)\n        const a = 'Hello'\n        a:concat(' world')\n\n        (Ctrl+D pressed)\n\nResult:\n\n        string ask(let('a','Hello'),call(get('concat'),get('a'),' world'))\n        'Hello world'\n\nAs the output CLI always prints AskCode (which would be sent to an AskVM machine if the code was executed over the network) and the result of the AskScript program.\n\n#### Usage\n\n1. Write a hello world and test it out with the CLI interpreter! If you'd like to use the GraphQL like endpoint [read this article](https://yonatankra.com/on-covid-19-graphql-and-askql/).\n\nIn AskQL we only use single quotes:\n\n```\n🦄 'Hello world'\nstring ask('Hello world')\n'Hello world'\n```\n\nIn the response you get a compiled version of the program that is sent asynchronously to the AskVM.\n\n2. There are two number types\n\n```\n🦄 4\nint ask(4)\n4\n```\n\n```\n🦄 4.2\nfloat ask(4.2)\n4.2\n```\n\n3. Let's say we've got more sophisticated example using the REST api and the `fetch` resource to get the current India's COVID19 stats:\n\n```\nask {\n  fetch('https://api.covid19india.org/data.json')['cases_time_series']\n  :map(fun(dataSet) {\n                         return {\n                            data: dataSet['date'],\n                            dailyconfirmed: dataSet['dailyconfirmed'],\n                            dailydeceased: dataSet['dailydeceased'],\n                            dailyrecovered: dataSet['dailyrecovered']\n                          }\n                        })\n}\n```\n\n4. Exit the console!\n\n`ctrl + d`\n\n5. You finished the AskScript tutorial, congratulations! 🎉\n\n### Playground\n\nHere is the link to our [AskQL playground](http://cli.askql.org/)!\n\n#### Developer info - how to run Playground frontend\n\n1. Copy .env.example to .env and set `PLAYGROUND_PORT` and `PLAYGROUND_ASK_SERVER_URL` appropriately. You can also set the optional `GTM` variable to your Google Tag Manager code.\n\n   or\n\n   You can also specify the variables in command line when running the Playground.\n\n2. Compile Playground:\n\n   ```\n   npm run playground:build\n   ```\n\n   or\n\n   ```\n   npm run build\n   ```\n\n3. Run it:\n\n   ```\n   npm run playground:start\n   ```\n\n\n    You can specify port and server URL in command line:\n\n    ```\n    PLAYGROUND_PORT=8080 PLAYGROUND_ASK_SERVER_URL=\"http://localhost:1234\" npm run playground:start\n    ```\n\n#### Additional notes\n\nSome files in the Playground come or are inspired by https://github.com/microsoft/TypeScript-Node-Starter (MIT) and https://github.com/Coffeekraken/code-playground (MIT).\n\n#### Developer info - how to run Playground backend\n\n1. Run:\n\n   ```\n   npm run build\n   ```\n\n2. Run:\n\n   ```\n   node dist/playground-backend/express/demoAskScriptServer.js\n   ```\n\n   If you want to specify custom port, run:\n\n   ```\n   PORT=1234 node dist/playground-backend/express/demoAskScriptServer.js\n   ```\n\n   instead.\n\n## FAQ\n\n### What's the difference between `ask { \u003caskscript\u003e }` and `eval( \u003cjavascript\u003e )`?\n\nJavaScript's `eval( \u003cjavascript\u003e )` is terrible at ensuring security. One can execute there _any_ code on _any_ resources available in Javascript. Moreover there is no control over time of execution or stack size limit.\n\nOn contrary, Ask's `ask { \u003caskscript\u003e }` runs by default on a secure, sandboxed AskVM, which has a separate execution context. We have built in control mechanisms that only allow using external resources you configured. Ask programs are also run with the limits on execution time and stack size restrictions you define.\n\n## Troubleshooting\n\nIf you didn't find answers to your questions here, write on our [Discord community](https://discord.gg/pYdzypH). We will both help you with the first steps and discuss more advanced topics.\n\n## License\n\nThe code in this project is licensed under MIT license.\n\n## Core Developers\n\n- [Marcin Hagmajer](https://github.com/mhagmajer/) (ex-Facebook)\n- [Łukasz Czerwiński](https://github.com/czerwinskilukasz1/) (ex-Google)\n\n\u003ca href=\"https://xfaang.com\" align=\"left\"\u003e\n  \u003cimg \n    src=\"https://xfaang-assets.s3.eu-west-3.amazonaws.com/logo/logo.png\" \n    align=\"left\"\n    title=\"xFAANG Logo\" \n    width=\"236\"\u003e\n\u003c/a\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatchthetornado%2Faskql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatchthetornado%2Faskql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatchthetornado%2Faskql/lists"}