{"id":24081769,"url":"https://github.com/jonathanconway/code-selectors","last_synced_at":"2026-02-02T01:32:19.101Z","repository":{"id":185236509,"uuid":"625613079","full_name":"jonathanconway/code-selectors","owner":"jonathanconway","description":"Convention for referencing parts of code","archived":false,"fork":false,"pushed_at":"2023-08-15T05:04:46.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T21:49:34.159Z","etag":null,"topics":["code","debugging","referencing","selector","shortcut","syntax"],"latest_commit_sha":null,"homepage":"https://usecodeselectors.surge.sh/","language":"HTML","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/jonathanconway.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-04-09T16:47:51.000Z","updated_at":"2023-08-13T04:36:19.000Z","dependencies_parsed_at":"2025-01-09T23:26:29.636Z","dependency_job_id":"ef3de161-f5fe-4ec7-b577-aca1dd49b7e4","html_url":"https://github.com/jonathanconway/code-selectors","commit_stats":null,"previous_names":["jonathanconway/code-selectors"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonathanconway/code-selectors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanconway%2Fcode-selectors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanconway%2Fcode-selectors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanconway%2Fcode-selectors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanconway%2Fcode-selectors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonathanconway","download_url":"https://codeload.github.com/jonathanconway/code-selectors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanconway%2Fcode-selectors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28999657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T01:32:03.847Z","status":"ssl_error","status_checked_at":"2026-02-02T01:32:03.458Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["code","debugging","referencing","selector","shortcut","syntax"],"created_at":"2025-01-09T23:26:14.291Z","updated_at":"2026-02-02T01:32:19.086Z","avatar_url":"https://github.com/jonathanconway.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code Selectors\n\n\u003e Convention for referencing pieces of code\n\n⚡️ **_It's like CSS selectors, but for code!_**\n\nHave you ever wanted a consistent and concise way of referencing a specific part of a code-base?\n\nFor example, suppose you wanted to refer to a function named `login` or a constant named `color`. How would you reference them, apart from using a line number (e.g. myfile.ts:23) or plain English (e.g. \"the login function in myfile.ts\")?\n\nAnd how would you deal with more complex nested structures, such as `r`, `g` and `b` fields inside an object assigned to a `color` constant, or an anonymous callback passed to a `then` call on a Promise?\n\nCode selectors to the rescue!\n\nCode selectors aim to provide a consistent and concise language allowing you to reference any structure in any code file.\n\nWith code selectors, you can now write something like: `myfile.ts/login` to reference your login function or `myfile.ts/colors.r` to reference the `r` field in your `color` constant.\n\n## Interactive demo\n\n{hotspot}\n\n## Characteristics of code selectors\n\n### **_Concise_**\n\nCode selectors take as little space as possible. Brevity makes the selectors faster to type, easier to read and more convenient to copy/paste or add to links.\n\n### **_Readable_**\n\nCode selectors use the real names of structures as much as possible, to optimise for readability.\n\nWhere names are not available, 1-based indeces are used, referencing the *n*th of the class of object being described. For example a reference to the 2nd parameter of a function call uses the index 2, even if it is preceded by previous function calls with their own parameters.\n\n### **_Composable_**\n\nComplex references can be be built up from simpler, interchangeable parts.\n\nFor example, to refer to a constant in a function in a field on an object, we can compose \"closure\", \"object field\" and \"structure\" together, to create one complete reference.\n\n## Parts of code selectors\n\n- [Structure](#structure)\n- [Anonymous structure](#anonymous-structure)\n- [Object field](#object-field)\n- [Array element](#array-element)\n- [Function call](#function-call)\n- [Function call argument](#function-call-argument)\n- [Closure](#closure)\n\n### Structure\n\nAny named structure (function, constant, etc) declared in the main body of a file can be referenced by name of the file, followed by a \"contains\" accessor - `/`, followed by the name of the structure.\n\n\u003e [file.ext] / **`name`**\n\n- **`name`** is the name of the structure\n\nFor example, to reference the function `bar` in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nfunction foo() {}\n\n// * reference this\nfunction bar() {}\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/bar`\n\n---\n\n### Anonymous structure\n\nNot all structures have names. We might declare a self-calling function (IFFE) or immediately loop over an array declared inline. We can reference such a structure by its type, followed by an \"indexing\" accessor, followed by a numeric, 1-based index indicating the order of that structure within the set of all structures of the same type.\n\n\u003e [file.ext] / **`(type)`**@**`(index)`**\n\n- **`type`** is one of the following:\n  - `func` - function\n  - `arr` - array\n  - `obj` - object\n  - `clo` - anonymous closure\n- **`index`** is an order index, 1 or greater.\n\nFor example, to reference the second self-calling function declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\n(function () {})();\n\n// * reference this\n(function () {})();\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/func@2`\n\nOr, to reference the second array declared inline in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\n(function () {})();\n\n[1, 2, 3].map(console.log);\n\n[4, 5, 6].map(console.log); // * reference this\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/arr@2`\n\n---\n\n### Object field\n\nAny structure which is declared or set as a field on a containing object can be referenced by referencing the containing structure, followed by the \"object field\" accessor - `.`, followed by the name of the field itself.\n\n\u003e [file.ext] / **`(object)`**.**`(field)`**\n\n- **`object`** is the _name_ of the containing structure\n\n- **`field`** is the name of the contained field\n\nFor example, to reference the field `bar`, declared in the object `foo`, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nconst foo = {\n  bar: \"1\", // * reference this\n};\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/foo.bar`\n\nOr, to reference the field `bar`, set as a field on the object `foo`, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nconst foo = {};\n\nfoo.bar = \"1\"; // * reference this\n```\n\nYou can use the same selector as above:\n\n\u003e `myfile.ts/foo.bar`\n\n---\n\n### Array element\n\nAny structure which is declared as an element on a containing array can be referenced by referencing the containing structure, followed by an \"array index\" accessor and the index of the item - `[n]`.\n\n\u003e [file.ext] / **`(array)`** [**`(index)`**]\n\n- **`array`** is the _name_ of the containing structure\n\n- **`index`** is the _index_ of the contained element\n\nFor example, to reference the string `bar`, held in the array `foo` at index 1, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nconst foo = [\n  \"baz\",\n  \"bar\", // * reference this\n];\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/foo[1]`\n\nOr, to reference the string `bar`, set at index 1 of the array `foo`, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nconst foo = [\"baz\"];\n\nfoo[1] = \"bar\"; // * reference this\n```\n\nYou can use the same selector as above:\n\n\u003e `myfile.ts/foo[1]`\n\n---\n\n### Function call\n\nFunction calls are one of the most common kinds of expressions in any Javascript/Typescript project. We can reference a call by referencing the structure being called, followed by an indicator that it is being called - `()`.\n\n\u003e [file.ext] / **`(call)`**`()`\n\nFor example, to reference the call to the imported `foo` function, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nimport { foo } from \"foo.utils\";\n\nfoo(\"hello\");\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/foo()`\n\n---\n\n### Function call argument\n\nSuppose you want to reference an argument being passed to a parameter of a function call. This can be done by referencing the function call, followed by a \"containment\" indicator - simply `/`, followed by a numeric 1-based index, indicating the parameter's order within the function's parameter list.\n\n\u003e [file.ext] / **`(call)`** / @**`(index)`**\n\nFor example, to reference the anonymous function passed to the 2nd parameter to the imported `foo` function, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nimport { foo } from \"foo.utils\";\n\nfoo(\"hello\", () =\u003e \"world\");\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/foo()/@2`\n\n---\n\n### Closure\n\nMany of the structures that make up a Javascript/Typescript project are actually found inside a closure of some kind, rather than declared in the top-level scope. We can reference an entity declared inside of a closure by simply referencing that closure, followed by a \"containment\" indicator - simply `/`, followed by the structure itself.\n\n\u003e [file.ext] / **`(closure)`** / **`(structure)`**\n\nFor example, to reference the constant `bar` declared inside the top-level function `foo`, declared in file `myfile.ts`:\n\n```ts\n// myfile.ts\n\nfunction foo() {\n  const bar = \"hello!\"; // * reference this\n}\n```\n\nYou can use this selector:\n\n\u003e `myfile.ts/foo/bar`\n\n---\n\n## Complex examples\n\n### NodeJS/Express login request handler\n\n```ts\nimport express from \"express\";\nimport { getUser } from \"users\";\n\nconst app = express();\n\napp.post(\"/login\", async (req, res) =\u003e {\n  const user = await getUser(req.params.username, req.params.password);\n\n  if (user) {\n    res.send(200);\n  } else {\n    res.send(401);\n  }\n});\n```\n\n1. The `app.post` call: `index.ts/app.post()`\n2. The post handler: `index.ts/app.post()/@1`\n3. The call to `getUser`: `index.ts/app.post()/@1/getUser()`\n4. The constant `user`: `index.ts/app.post()/@1/user`\n5. The call to `res.send` with `200` passed: `index.ts/app.post()/@1/res.send()@1`\n6. The call to `res.send` with `401` passed: `index.ts/app.post()/@1/res.send()@2`\n\n### ReactJS Counter component\n\n```tsx\nexport const Counter: VFC = () =\u003e {\n  const [count, setCount] = useState(0);\n  const [overLimit, setOverLimit] = useState(false);\n\n  useEffect(() =\u003e {\n    const interval = setInterval(() =\u003e {\n      setCount(() =\u003e count + 1);\n\n      if (count \u003e 10) {\n        setOverLimit(() =\u003e true);\n      }\n    }, 1_000);\n\n    return () =\u003e clearInterval(interval);\n  });\n\n  return \u003cspan\u003e{count}\u003c/span\u003e;\n};\n```\n\n1. The `Counter` itself: `myfile.ts/Counter`\n2. The first call to `useState`: `myfile.ts/Counter/useState()@1`\n3. The destructured constant `count`: `myfile.ts/Counter/count`\n4. The destructured function `setCount`: `myfile.ts/Counter/setCount`\n5. The second call to `useState`: `myfile.ts/Counter/useState()@2`\n6. The call to `useEffect`: `myfile.ts/Counter/useEffect()`\n7. The function passed to `useEffect`: `myfile.ts/Counter/useEffect()/@1`\n8. The call to `setInterval`: `myfile.ts/Counter/useEffect()/@1/setInterval()`\n9. The function passed to `setInterval`: `myfile.ts/Counter/useEffect()/@1/setInterval()/@1`\n10. The call to `setCount`: `myfile.ts/Counter/useEffect()/@1/setInterval()/@1/setCount()`\n11. The function passed to `setCount`: `myfile.ts/Counter/useEffect()/@1/setInterval()/@1/setCount()/@1`\n12. The constant `interval`: `myfile.ts/Counter/useEffect()/@1/interval`\n13. The function returned by function passed to `useEffect`: `myfile.ts/Counter/useEffect()/@1/func@2`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanconway%2Fcode-selectors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathanconway%2Fcode-selectors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanconway%2Fcode-selectors/lists"}