{"id":21992579,"url":"https://github.com/tecc/querio","last_synced_at":"2026-05-06T05:39:40.669Z","repository":{"id":184930497,"uuid":"672686341","full_name":"tecc/querio","owner":"tecc","description":"Condition-based query parser, optimal for building database queries.","archived":false,"fork":false,"pushed_at":"2023-08-15T20:03:46.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-03-01T12:19:47.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/tecc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-30T23:12:38.000Z","updated_at":"2023-07-30T23:14:02.000Z","dependencies_parsed_at":"2025-01-28T10:01:35.317Z","dependency_job_id":null,"html_url":"https://github.com/tecc/querio","commit_stats":null,"previous_names":["tecc/querio"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecc%2Fquerio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecc%2Fquerio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecc%2Fquerio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tecc%2Fquerio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tecc","download_url":"https://codeload.github.com/tecc/querio/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052619,"owners_count":20553161,"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":[],"created_at":"2024-11-29T20:14:11.293Z","updated_at":"2026-05-06T05:39:40.638Z","avatar_url":"https://github.com/tecc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Querio: Condition-based query parser\n\n\u003e Note: This is not a URL query string parser. For that, try [qs](https://www.npmjs.com/package/qs).\n\nThis README is not finished and may contain some inaccuracies. \nLook through the test code if you'd like to see how to use and not to use Querio.\n\n## Usage\n\n### Parse specifications\n\nTo use Querio, you must first create a _parse specification_. These specifications dictate *how* Querio should parse the\nquery strings.\n\nA parse specification is essentially a key-value pair of strings (_condition type_) to _condition specifications_.\nConsider the following (it's \"inspired\" by repository issues):\n\n```ts\nimport { values } from \"querio\";\n\nconst spec = {\n    author: values.string,\n    issue: values.int\n};\n```\n\nThis specification would tell Querio that the condition type `author` is to be interpreted as a string.\n`values.string` is just a predefined condition specification for strings.\nYou can have as many condition types as you want, as long as their names don't conflict.\n\nGiven this specification, you would parse query strings using the `parse` function:\n\n```ts\nimport { parse } from \"querio\";\n\n// OK: The username must be equal to \"tecc\"\nparse(\"author:tecc\", spec);\n\n// OK: The username must be equal to \"tecc\", and the issue ID has to be equal to 123\nparse(\"author:tecc issue:123\", spec);\n\n// ERROR: NotANumber isn't a valid integer, so this will throw.\nparse(\"author:tecc issue:NotANumber\", spec);\n\n// ERROR: name isn't a known condition type, so this will throw.\nparse(\"name:tecc\", spec);\n```\n\n### Condition types\n\nAs previously mentioned, a parse specification consists of multiple condition types.\nThese condition types consist of the type's name, and its specification.\n\nYou can have as many condition types as you want, as long as none of them have conflicting names.\nThere is also one restriction on what names you can use for the parse specification:\nyou *cannot* use the names `and`, `or`, and `not`.\n\nIf the example from the previous section were to be expanded, it would look something like this:\n\n```ts\nconst spec = {\n    author: {\n        parse: (input) =\u003e input,\n        compare: /* omitted for brevity */\n    },\n    issue: {\n        parse: (input) =\u003e parseInt(input),\n        compare: /* also omitted */\n    }\n};\n```\n\nA condition specification specifies how Querio should handle each condition type. They are structured like so:\n\n```ts\ntype ValueType = /* Something */;\nconst conditionSpecification = {\n    parse: (input: string): ValueType =\u003e {\n        // This function parses the input string to its value type.\n    }\n}\n```\n\nCondition specifications can also be \"empty\", meaning they do not have a value.\nIn this case, they act like flags.\n\n### Complex conditions\n\nThe already-provided functionality is fine and all, but what if you want more complex queries?\nWhat if you want any issue that was authored by `tecc` _or_ has the ID `123`? What about those _not_ authored\nby `johndoe`? Well, Querio supports this out-of-the-box.\n\nAddressing the first problem, using the `|` character between two or more conditions.\nFor example, `author:tecc | issue:123` would be interpreted as \"the author must equal `tecc` OR the issue ID must equal `123`\".\n\nThe second problem can be solved by prefixing any condition with a `-` sign: `-author:johndoe`.\n\nAnother very powerful feature are _groups_: by encasing conditions in parentheses, that group is treated as \"one condition\".\nFor example, `( author:tecc issue:123 ) | author:johndoe` would be interpreted as \"( the author must equal `tecc` AND the ID must equal 123 ) OR the author must equal `johndoe`\".\n\nGroups can also be prefixed with a `-` to negate them: `-( author:tecc issue:123 )`.\n\n## Explanation\n\nWell, I needed something that could parse a string into some format well-suited for converting directly to database\nqueries. Querio was made to fill that purpose in a generic way.\n\nThe primary inspiration in its initial design phase was the [arg](https://www.npmjs.com/package/arg) package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftecc%2Fquerio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftecc%2Fquerio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftecc%2Fquerio/lists"}