{"id":15917628,"url":"https://github.com/dsfields/ordery-node","last_synced_at":"2025-04-03T11:42:06.967Z","repository":{"id":57316168,"uuid":"121028448","full_name":"dsfields/ordery-node","owner":"dsfields","description":"Create order-by expressions for Node.js applications.","archived":false,"fork":false,"pushed_at":"2018-02-20T22:45:50.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T18:15:35.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/dsfields.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-10T15:42:27.000Z","updated_at":"2018-02-12T15:51:11.000Z","dependencies_parsed_at":"2022-08-25T21:10:58.572Z","dependency_job_id":null,"html_url":"https://github.com/dsfields/ordery-node","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fordery-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fordery-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fordery-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fordery-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dsfields","download_url":"https://codeload.github.com/dsfields/ordery-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246998134,"owners_count":20866690,"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-10-06T18:11:57.596Z","updated_at":"2025-04-03T11:42:06.945Z","avatar_url":"https://github.com/dsfields.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ordery\n\nThe `ordery` module provides parsing for dynamic, ordery-by statements, and serves as a high-level abstraction for query ordering.  Parsed expressions can then be later turned into order by statements for different database technologies.  This is most useful for ingesting dynamic queries in a request to a RESTful API collection.\n\n__Contents__\n* [Usage](#usage)\n* [Ordery Expressions](#ordery-expressions)\n* [API](#api)\n* [Plugins](#plugins)\n\n## Usage\n\nAdd `ordery` to your `package.json` file's `dependencies`:\n\n```sh\n$ npm install ordery -S\n```\n\nThen use it in your code:\n\n```js\nconst ordery = require('ordery');\n\nconst expr = '/foo/bar,/baz:desc,/qux:asc';\nconst result = ordery.parse(expr);\n\nconsole.log(result.value);\n// [\n//   {\n//     target: {\n//       path: ['foo', 'bar'],\n//       value: '/foo/bar'\n//     },\n//     direction: 'asc',\n//   },\n//   {\n//     target: {\n//       path: ['baz'],\n//       value: '/baz'\n//     },\n//     direction: 'desc',\n//   },\n//   {\n//     target: {\n//       path: ['qux'],\n//       value: '/qux'\n//     },\n//     direction: 'asc',\n//   }\n// ]\n```\n\n## Ordery Expressions\n\nAll expressions have the structure (in Extended Backus-Naur Form):\n\n```ebnf\nexpression = clause , { \",\" , clause } ;\nclause = json_pointer , [ \":\" , direction ] ;\ndirection = \"asc\" | \"desc\" ;\njson_pointer = field , { field } ;\nfield = \"/\" , field_char , { field_char } ;\nfield_char = alphanumeric | \"_\" ;\nalphanumeric = \"A\" | \"B\" | \"C\" | \"D\" | \"E\" | \"F\" | \"G\" | \"H\" | \"I\"\n             | \"J\" | \"K\" | \"L\" | \"M\" | \"N\" | \"O\" | \"P\" | \"Q\" | \"R\"\n             | \"S\" | \"T\" | \"U\" | \"V\" | \"W\" | \"X\" | \"Y\" | \"Z\" | \"a\"\n             | \"b\" | \"c\" | \"d\" | \"e\" | \"f\" | \"g\" | \"h\" | \"i\" | \"j\"\n             | \"k\" | \"l\" | \"m\" | \"n\" | \"o\" | \"p\" | \"q\" | \"r\" | \"s\"\n             | \"t\" | \"u\" | \"v\" | \"w\" | \"x\" | \"y\" | \"z\" | \"0\" | \"1\"\n             | \"2\" | \"3\" | \"4\" | \"5\" | \"6\" | \"7\" | \"8\" | \"9\" ;\n```\n\n### Examples\n\nOrder by target `/foo` ascending:\n\n```\n/foo\n```\n\nOrder by target `/foo` ascending, and then by target `/bar/baz` descending.\n\n```\n/foo:asc,/bar/baz:desc\n```\n\n## API\n\nThe `ordery` module provides a simple interface for working with order-by expressions.\n\n### `ordery.Direction`\n\nA reference to the `Direction` enum value.  This enum includes the values:\n\n* `ASC`: represents ascending order.\n\n* `DESC`: represents descending order.\n\n### `ordery.errors.ParserError`\n\nA reference to the error throw by the [Ordery Expression](#order-expression) parser when an invalid expression is encountered.\n\n### `ordery.parse(expression)`\n\nParses an [Ordery Expression](#order-expression).\n\n__Parameters__\n\n* `expression`: _(required)_ a string formatted as an Order Expression.\n\n__Returns__\n\nAn object containing the result of the parsing operation.  This object has the following keys:\n\n* `error`: if parsing failed, this key will contain the resulting [`ParserError`](#orderyerrorsparsererror).  If parsing succeeded, this key is `null`.\n\n* `value`: instance of [`Order`](#orderyorder).\n\n### `ordery.Order`\n\nA class representing an Order Expression.\n\n#### `Order.asc(target)`\n\nA factory method for creating instances of `Order`.  This method seeds the resulting `Order` instance with an ascending order clause with the given `target`.\n\n__Parameters__\n\n* `target`: _(required)_ a string formatted as an [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901), or an instance of [`Target`](#orderytarget).\n\n__Returns__\n\nA new instance of `Order`.\n\n#### `Order.desc(target)`\n\nA factory method for creating instances of `Order`.  This method seeds the resulting `Order` instance with a descending order clause with the given `target`.\n\n__Parameters__\n\n* `target`: _(required)_ a string formatted as an [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901), or an instance of [`Target`](#orderytarget).\n\n__Returns__\n\nA new instance of `Order`.\n\n#### `Order.prototype.value`\n\nA property that gets an array containing objects that define an order-by clause.  Each object has the following keys:\n\n* `direction`: a string indicating the sort direction of the order-by clause.  This can be either `asc` or `desc`.\n\n* `target`: an instance of [`Target`](#orderytarget).\n\n#### `Order.prototype.asc(target)`\n\nA method that appends an ascending order clause to the `Order` instance using the given `target`.\n\n__Parameters__\n\n* `target`: _(required)_ a string formatted as an [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901), or an instance of [`Target`](#orderytarget).\n\n__Returns__\n\nThe instance of `Order`.\n\n#### `Order.prototype.desc(target)`\n\nA method that appends a descending order clause to the `Order` instance using the given `target`.\n\n__Parameters__\n\n* `target`: _(required)_ a string formatted as an [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901), or an instance of [`Target`](#orderytarget).\n\n__Returns__\n\nThe instance of `Order`.\n\n### `ordery.Target`\n\nA class that represents a field target in an order-by statement.\n\n#### `Target.parse(target)`\n\nA factory method that parses a string representing a field reference.\n\n__Parameters__\n\n* `target`: _(required)_ a string formatted as an [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901).\n\n__Returns__\n\nA new instance of `Target`.\n\n#### `Target.prototype.path`\n\nA property that gets an array of all field references in the target.  Each field reference is a string that represents the name of a key on a document or sub-document, or an integer that references an index in an array.\n\n### `Target.prototype.value`\n\nA property that gets a string that represents the original JSON pointer value.\n\n## Plugins\n\nThe `ordery` module provides a high-level abstraction over the concern of sort instructions, and is suitable for communicating sort instructions across application layers.  At some point, `order.Order` instances need to be converted into a sort instruction usable by an database technology.\n\nAvailable plugins for this purpose include:\n\n* [`ordery-mongodb`](https://www.npmjs.com/package/ordery-mongodb)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fordery-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsfields%2Fordery-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fordery-node/lists"}