{"_id":"@ajfafg/dekun","_rev":"2-bddcb36553bcd24d990b065cd21d4671","name":"@ajfafg/dekun","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@ajfafg/dekun","version":"0.1.0","description":"Extract variable and function definitions from TypeScript programs","main":"out/index.js","types":"out/index.d.ts","scripts":{"build":"tsc -p .","test":"jest"},"repository":{"type":"git","url":"git+https://github.com/ajfAfg/dekun.git"},"keywords":["testing","snapshot-testing","abstract-syntax-tree","jest","typescript"],"author":{"name":"ajfAfg"},"license":"MIT","bugs":{"url":"https://github.com/ajfAfg/dekun/issues"},"homepage":"https://github.com/ajfAfg/dekun#readme","dependencies":{"typescript":"^5.0.4"},"devDependencies":{"@types/jest":"^29.5.1","jest":"^29.5.0","ts-jest":"^29.1.0"},"gitHead":"bdadfe3a875a56859f0c58b657bf351e58f7bcf6","_id":"@ajfafg/dekun@0.1.0","_nodeVersion":"19.9.0","_npmVersion":"9.6.3","dist":{"integrity":"sha512-Z8wkczrXwEy8UqO6+seOzTbX5QT5wou6naiMjYk8JgWZtF7MQHfJlVJRIMwKJl+00Ldm9cX8Uz0m0sgqyFgHUg==","shasum":"3178795f95f7bf20b907fee9f9c01f358397e8c2","tarball":"https://registry.npmjs.org/@ajfafg/dekun/-/dekun-0.1.0.tgz","fileCount":5,"unpackedSize":9583,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDqyzqqyhEFw1AYrV9kNSw5evHXO0PSnusq4oc3zLqUyAiEA8gtGo2iCQcZQQpQNuoPs4Qj8gAvjHTAmA/eBlxiqLSk="}]},"_npmUser":{"name":"ajfafg","email":"ktknar05374@gmail.com"},"directories":{},"maintainers":[{"name":"ajfafg","email":"ktknar05374@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/dekun_0.1.0_1683349107254_0.44997550520257756"},"_hasShrinkwrap":false},"0.1.1":{"name":"@ajfafg/dekun","version":"0.1.1","description":"Extract variable and function definitions from TypeScript programs","main":"out/index.js","types":"out/index.d.ts","scripts":{"build":"tsc -p .","test":"jest"},"repository":{"type":"git","url":"git+https://github.com/ajfAfg/dekun.git"},"keywords":["testing","snapshot-testing","abstract-syntax-tree","jest","typescript"],"author":{"name":"ajfAfg"},"license":"MIT","bugs":{"url":"https://github.com/ajfAfg/dekun/issues"},"homepage":"https://github.com/ajfAfg/dekun#readme","dependencies":{"typescript":"^5.0.4"},"devDependencies":{"@types/jest":"^29.5.1","jest":"^29.5.0","ts-jest":"^29.1.0"},"gitHead":"ca69316f570081faba1100dde45cac11d5725fbb","_id":"@ajfafg/dekun@0.1.1","_nodeVersion":"19.9.0","_npmVersion":"9.6.3","dist":{"integrity":"sha512-stFhMYbHy6FH+tFa2cS7qOWCQ/AJWPPW32G01ypznnSUwZp5hBz92Fcv4xBRAGgKuc7+eaV49nOZHMO+DwKbxg==","shasum":"9492973ebf342c97b8b3301d11b248a88d0aeb30","tarball":"https://registry.npmjs.org/@ajfafg/dekun/-/dekun-0.1.1.tgz","fileCount":5,"unpackedSize":9780,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCx2jEHvJbj9GZdrFDG27XoCmAMF8Ni3zrTXUxEAFziLwIhAJYBe8oRe8wa/z8QTHqvIc2LQfwZaz8L506n88Ynm8lb"}]},"_npmUser":{"name":"ajfafg","email":"ktknar05374@gmail.com"},"directories":{},"maintainers":[{"name":"ajfafg","email":"ktknar05374@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/dekun_0.1.1_1683350378117_0.9844825229123717"},"_hasShrinkwrap":false},"0.1.2":{"name":"@ajfafg/dekun","version":"0.1.2","description":"Extract variable and function definitions from TypeScript programs","main":"out/index.js","types":"out/index.d.ts","scripts":{"build":"tsc -p .","test":"jest"},"repository":{"type":"git","url":"git+https://github.com/ajfAfg/dekun.git"},"keywords":["testing","snapshot-testing","abstract-syntax-tree","jest","typescript"],"author":{"name":"ajfAfg"},"license":"MIT","bugs":{"url":"https://github.com/ajfAfg/dekun/issues"},"homepage":"https://github.com/ajfAfg/dekun#readme","dependencies":{"typescript":"^5.0.4"},"devDependencies":{"@types/jest":"^29.5.1","jest":"^29.5.0","ts-jest":"^29.1.0"},"gitHead":"9118543ffc096dc9a0c48e42fa8200ce3c536af5","_id":"@ajfafg/dekun@0.1.2","_nodeVersion":"19.9.0","_npmVersion":"9.6.3","dist":{"integrity":"sha512-o3ExzjjstJas9pTDna6yPk2OGDUPtvX0lTLAApR1p0efZwa1/A/xU2psJG5P91q5YZTwa3uZa2DUaBFiNmrnyg==","shasum":"84219834ac6ecfeb299826b9ed6e66f845998cf2","tarball":"https://registry.npmjs.org/@ajfafg/dekun/-/dekun-0.1.2.tgz","fileCount":5,"unpackedSize":10258,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIB3oKsUshtk3R5EVixAa+jqpm00Wlz0xvSTf9ROLgt5/AiEA/2V/fa5+I07JnvypiruNtqKLjs6FgWVwYgqTxjzkemc="}]},"_npmUser":{"name":"ajfafg","email":"ktknar05374@gmail.com"},"directories":{},"maintainers":[{"name":"ajfafg","email":"ktknar05374@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/dekun_0.1.2_1683379164954_0.10577941060578966"},"_hasShrinkwrap":false}},"time":{"created":"2023-05-06T04:58:27.197Z","0.1.0":"2023-05-06T04:58:27.415Z","modified":"2023-05-06T13:19:25.356Z","0.1.1":"2023-05-06T05:19:38.292Z","0.1.2":"2023-05-06T13:19:25.155Z"},"maintainers":[{"name":"ajfafg","email":"ktknar05374@gmail.com"}],"description":"Extract variable and function definitions from TypeScript programs","homepage":"https://github.com/ajfAfg/dekun#readme","keywords":["testing","snapshot-testing","abstract-syntax-tree","jest","typescript"],"repository":{"type":"git","url":"git+https://github.com/ajfAfg/dekun.git"},"author":{"name":"ajfAfg"},"bugs":{"url":"https://github.com/ajfAfg/dekun/issues"},"license":"MIT","readme":"# dekun\n\nA Library in TypeScript that provides functions to return an AST string of a specified variable definition or function definition from a specified file.\n\n[本ライブラリを用いたテスト手法について書いた日本語の記事はこちら](https://zenn.dev/arjef/articles/snapshot-testing-of-function-definitions)\n\n## Use case\n\nSnapshot testing of function definitions. For example, it is used with [Jest](https://jestjs.io/) as follows.\n\nTarget\n\n```ts\nexport const sum = (xs: [number]): number => xs.reduce((x, y) => x + y, 0);\n\nfunction prod(xs: [number]): number {\n  return xs.reduce((x, y) => x * y, 1);\n}\n```\n\nTest\n\n```ts\nimport { extract } from \"@ajfafg/dekun\";\n\ndescribe(\"Demo\", () => {\n  it(\"sum\", () => {\n    expect(extract(\"src/foo.ts\", \"sum\")).toMatchSnapshot();\n  });\n  it(\"prod\", () => {\n    expect(extract(\"src/foo.ts\", \"prod\")).toMatchSnapshot();\n  });\n});\n```\n\n## **⚠️ CAUTION ⚠️**\n\nI was given the information that the `toString` method can also be used to string a function definition (when I enter a function in the Node.js REPL, I get something like `[Function (anonymous)]`, which I assumed was the result of implicitly evaluating `toString` the function). In this use case, it is more convenient to perform snapshot testing on a string obtained by `toString` method and automatically formatted by an existing formatter.\n\n## Motivation\n\nIn some cases, such as wrapper functions, a function definition immediately shows that the function works as expected. In such cases, the function can be considered correct enough as long as it is ensured that **the function definition is not unintentionally modified**. As the concept of the testing pyramid suggests, testing should be done while considering cost-effectiveness, and I also believe that testing methods should be selected according to what we want to ensure. When the property to be ensured are simple, as in this case, I want to test more lightly than conventional testing methods such as sample-based testing.\n\n## Approach\n\nPerform snapshot testing of function definitions. Snapshot testing is a testing method used mainly on the front-end, and is mainly used to ensure that a UI is not modified unintentionally. Since what the snapshot testing does is similar to the `diff` command, this testing method can be used for non-UI testings as well. This approach is based on the idea of snapshot testing function definitions instead of UIs.\n\nTo obtain a function definition, the [AST (abstract syntax tree)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of the function definition is converted to a string. The most important reason for using AST is that I do not want to fail tests when the syntactic meaning does not change. For example, if we simply specify the number of lines in the file to obtain a string of function definitions, the test will fail simply because of the addition of comments, as shown below. This is undesirable from the standpoint of test reliability.\n\n```ts\n// before\nconst foo = (): number => 1;\n\n// after\nconst foo = (): number => 1; // This is a comment\n```\n\nTo realize this approach, the following two elements must be provided.\n\n1. Test environment capable of snapshot testing\n2. Function that takes a file name and a function name as arguments and returns the string of the AST of that function definition defined in the file\n\nJest will take care of 1, but 2 was not found as far as I could find. Therefore, I developed this library `dekun`, which is responsible for 2. By the way, the library name is derived from \"Definition Extract 君\".\n\n## Current Specifications\n\n- Supported Languages\n  - TypeScript\n- Referenceable variable/function definitions\n  - Variables and functions defined at the top level of a file\n  - It doesn't matter whether or not `export`\n- Other detailed specifications\n  - Refer to the first variable declaration/assignment for variables defined with `var` / `let`\n    - i.e. `let foo = 1; foo = 2;` refers to `let foo = 1;`\n  - If the specified variable is defined at the same time as other variables, all its variable definitions are referenced\n    - For example, `foo` for `const foo = 1, bar = 2;` will refer to `const foo = 1, bar = 2;`\n    - It is not easy to refer only to `const foo = 1`, but easy to refer only to `foo = 1`\n    - If `const` information is missing, we can rewrite `const` to `var` and do anything, but the test will not fail, so I'm playing it safe this time\n  - Even if two function definitions have the same syntactic meaning, the strings obtained using this library may differ\n    - For example, the following two function definitions\n    - To avoid this, this library adopt AST, but it has not been fully dealt with, which is a weak point of this library.\n      - ~~That said, it is a problem that can be solved by using a strict formatter~~\n\n```ts\n// First\nfunction foo() {\n  return 1;\n}\n\n// Second\nfunction foo() {\n  return 1;\n}\n```\n\n<!-- TODO: \"Second\" のプログラムが自動フォーマットされていないか記事を公開する前に確認する（`function foo() {return 1;}` が正しい） -->\n\nCurrently, only minimal functionality is implemented in order to verity the acceptance of the \"snapshot testing of function definitions\" method in a PoC-like manner. I would appreciate your feedback to improve the functionality.\n\n## LICENSE\n\nMIT\n","readmeFilename":"README.md"}