{"id":24558048,"url":"https://github.com/rse/sieving","last_synced_at":"2025-03-16T19:21:34.334Z","repository":{"id":57359237,"uuid":"125751452","full_name":"rse/sieving","owner":"rse","description":"Query-Based Item-List Reduction","archived":false,"fork":false,"pushed_at":"2024-03-11T20:40:27.000Z","size":170,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-10T10:46:47.913Z","etag":null,"topics":["filter","item","language","list","query","reduction","sieve"],"latest_commit_sha":null,"homepage":"https://npmjs.com/sieving","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rse.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}},"created_at":"2018-03-18T17:45:01.000Z","updated_at":"2024-12-22T03:54:11.000Z","dependencies_parsed_at":"2024-03-11T21:51:49.248Z","dependency_job_id":null,"html_url":"https://github.com/rse/sieving","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsieving","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsieving/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsieving/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsieving/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/sieving/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243918629,"owners_count":20368745,"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":["filter","item","language","list","query","reduction","sieve"],"created_at":"2025-01-23T05:47:15.530Z","updated_at":"2025-03-16T19:21:34.313Z","avatar_url":"https://github.com/rse.png","language":"JavaScript","readme":"\nSieving\n=======\n\nQuery-Based Item-List Reduction for JavaScript\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/sieving.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/rse/sieving.png\" alt=\"\"/\u003e\n\nAbout\n-----\n\nSieving is a JavaScript library for reducing/filtering a JavaScript\nlist of items, based on a simple simple query language. It is intended\nto be used for item list filtering or item list searching purposes\nwithin Browser or Node.js environments. Internally, Sieving is based\non a full-blown query parser, supports optional fuzzy matching and\nnamespacing of items, and supports union, intersection and subtraction\nof the result sets.\n\nA query like...\n\n```\nfoo bar^ +baz -quux, baz\n```\n\n...on a result set basis and mathematically means...\n\n```\n(((MATCH(\"foo\") ∩ BOOST(MATCH(\"bar\"), 1)) ∪ MATCH(\"baz\")) ∖ MATCH(\"quux\")) ∪ MATCH(\"baz\")\n```\n\n...or expressed in a functional way:\n\n```\nUNION(\n    SUBTRACT(\n        UNION(\n            INTERSECT(\n                MATCH(\"foo\"),\n                BOOST(MATCH(\"bar\"), 1)),\n            MATCH(\"baz\")),\n        MATCH(\"quux\")),\n    MATCH(\"baz\"))\n```\n\nInstallation\n------------\n\n```shell\n$ npm install sieving\n```\n\nUsage\n-----\n\n```js\nconst Sieving = require(\"sieving\")\n\nlet items = [ \"foo\", \"bar\", \"baz\", \"quux\", \"foo bar\", \"foo baz\", \"foo quux\", \"foo bar quux\" ]\n\n/*  step-by-step usage  */\nlet sieving = new Sieving()\nsieving.parse(\"foo +bar -quux, baz^\")\nconsole.log(sieving.format())\nconsole.log(sieving.dump())\nlet result = sieving.sieve(items)\nconsole.log(result)\n\n/*  all-in-one usage  */\nresult = Sieving.sieve(items, \"foo +bar -quux, baz^\")\nconsole.log(result)\n```\n\nOutput:\n\n```\nqueries [1,1]\n├── query [1,1]\n│   ├── term (value: \"foo\", type: \"bare\") [1,1]\n│   ├── term (op: \"union\", value: \"bar\", type: \"bare\") [1,5]\n│   └── term (op: \"subtraction\", value: \"quux\", type: \"bare\") [1,10]\n└── query [1,17]\n    └── term (value: \"baz\", type: \"bare\", boost: 1) [1,17]\n\n[ 'baz', 'foo', 'foo bar', 'foo baz', 'bar' ]\n[ 'baz', 'foo', 'foo bar', 'foo baz', 'bar' ]\n```\n\nExamples\n--------\n\n```js\nconst { sieve }  = require(\"sieving\")\nconst { expect } = require(\"chai\")\n\nlet items = [ \"foo\", \"bar\", \"baz\", \"quux\", \"foo bar baz quux\" ]\n\nexpect(sieve(items, \"foo\"))  .deep.equal([ \"foo\", \"foo bar baz quux\" ])\nexpect(sieve(items, \"fo?\"))  .deep.equal([ \"foo\", \"foo bar baz quux\" ])\nexpect(sieve(items, \"/fo./\")).deep.equal([ \"foo\", \"foo bar baz quux\" ])\nexpect(sieve(items, \"'foo'\")).deep.equal([ \"foo\" ])\n\nexpect(sieve(items, \"bax\",  { fuzzy: true })).deep.equal([ \"bar\", \"baz\" ])\nexpect(sieve(items, \"fox\",  { fuzzy: true })).deep.equal([ \"foo\" ])\nexpect(sieve(items, \"qxux\", { fuzzy: true })).deep.equal([ \"quux\" ])\n\nexpect(sieve(items, \"foo\"))          .deep.equal([ \"foo\", \"foo bar baz quux\" ])\nexpect(sieve(items, \"foo bar\"))      .deep.equal([ \"foo bar baz quux\" ])\nexpect(sieve(items, \"foo +bar\"))     .deep.equal([ \"foo\", \"foo bar baz quux\", \"bar\" ])\nexpect(sieve(items, \"foo +bar -baz\")).deep.equal([ \"foo\", \"bar\" ])\nexpect(sieve(items, \"foo, bar\"))     .deep.equal([ \"foo\", \"foo bar baz quux\", \"bar\" ])\nexpect(sieve(items, \"bar, foo\"))     .deep.equal([ \"bar\", \"foo bar baz quux\", \"foo\" ])\n```\n\nQuery Syntax\n------------\n\nThe following is a symbolic grammar describing the supported\nquery syntax. For more subtle details, see the [actual PEG grammar](src/sieving.pegjs)\nof the underlying parser.\n\n```\nqueries    ::=  query (\",\" query)*                  // union of queries\nquery      ::=  term (\" \" term)*                    // intersection of terms\nterm       ::=  operation? namespace? text boost?   // single query term\noperation  ::=  \"+\" | \"-\"                           // force union or subtraction of term\nnamespace  ::=  symbol | id \":\"                     // match against a particular namespace\ntext       ::=  quoted | regexp | glob | bareword   // four variants of the term\nboost      ::=  \"^\" number?                         // optionally boost the results\nquoted     ::=  /\"(\\\\\"|[^\"])*\"/ | /'(\\\\'|[^'])*'/   // double- or single-quoted term\nregexp     ::=  /\\/(\\\\\\/|[^\\/])*\\//                 // regular expression term\nglob       ::=  /.*[*?[\\]{}].*/                     // glob-style term\nbareword   ::=  /.+/                                // bareword term\nnumber     ::=  /\\d*\\.\\d+/ | /\\d+/                  // floating or integer number\nsymbol     ::=  /^[$#%@\u0026]$/                         // namespace symbol\nid         ::=  /^[a-zA-Z][a-zA-Z0-9-_]*$/          // namespace identifier\n```\n\nApplication Programming Interface (API)\n---------------------------------------\n\nThe following is the API as a TypeScript declaration.\nSee also the [actual TypeScript definition file](src/sieving.d.ts).\n\n```ts\ndeclare module \"Sieving\" {\n    class Sieving {\n        /*  create Sieving instance  */\n        public constructor(\n            options?: {\n                fieldsVal: string[], /*  names of fields in items of type object (default: [ \"value\" ])  */\n                fieldId:   string    /*  name of optional field of unique identifier in items of type object (default: \"id\")  */\n            }\n        )\n\n        /*  parse query into an internal AST  */\n        parse(\n            query:         string,   /*  query string  */\n            options?: {\n                lts:       boolean,  /*  parse query string into LST (default: true)  */\n                ast:       boolean   /*  parse query string into AST (default: true)  */\n            }\n        ): void\n\n        /*  dump internal AST as text (for debugging purposes only)  */\n        dump(\n            colorize?:     boolean   /*  whether to colorize output (default: true)  */\n        ): string\n\n        /*  format internal AST into query string  */\n        format(\n           format:         string    /*  format of output (default \"text\", or \"html\", \"xml\" or \"json\")  */\n        ): string\n\n        /*  evaluate internal AST (for custom matching)  */\n        evaluate(\n            queryResults: (\n                ns:        string,   /*  term namespace (default: \"\")  */\n                type:      string,   /*  term type (\"regexp\", \"glob\", \"squoted\", \"dquoted\", or \"bareword\")  */\n                value:     string    /*  term value  */\n            ) =\u003e any[]\n        ): any[]\n\n        /*  sieve items by evaluating query with standard matching  */\n        sieve(\n            items: any[],            /*  list of items to sieve/filter  */\n            options?: {\n                fuzzy:     boolean,  /*  whether to fuzzy match quoted and bare terms (default: false)  */\n                nocase:    boolean,  /*  whether to match case-insensitive (default: false)  */\n                maxLS:     number,   /*  maximum Levenshtein distance for fuzzy matching (default: 2)  */\n                minDC:     number    /*  minimum Dice-Coefficient for fuzzy matching (default: 0.50)  */\n            }\n        ): any[]\n\n        /*  sieve items by evaluating query with standard matching (stand-alone)  */\n        static sieve(\n            items: any[],            /*  list of items to sieve/filter  */\n            query: string,           /*  query string  */\n            options?: {\n                fieldsVal: string[], /*  names of fields in items of type object (default: [ \"value\" ])  */\n                fieldId:   string    /*  name of optional field of unique identifier in items of type object (default: \"id\")  */\n                fuzzy:     boolean,  /*  whether to fuzzy match quoted and bare terms (default: false)  */\n                nocase:    boolean,  /*  whether to match case-insensitive (default: false)  */\n                maxLS:     number,   /*  maximum Levenshtein distance for fuzzy matching (default: 2)  */\n                minDC:     number    /*  minimum Dice-Coefficient for fuzzy matching (default: 0.50)  */\n                debug:     boolean   /*  whether to dump the internal AST to stdout  */\n            }\n        ): any[]\n    }\n    export = Sieving\n}\n```\n\nLicense\n-------\n\nCopyright \u0026copy; 2018-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fsieving","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Fsieving","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fsieving/lists"}