Add TypeScript support with module-level type inference

README.md

@@ -7,8 +7,9 @@ When the directory structure of your Node.js application (not library!) has some
 const mysql = require('../../../../db/mysql')
 ```
 Those suck for maintenance and they're ugly. [link](https://gist.github.com/branneman/8048520)
+
 ## Install
-```javascript
+```bash
 npm install abrequire --save
 ```
 
@@ -22,34 +23,85 @@ const use = require('abrequire')
 ```
 
 ## Example
+
+Project structure:
+```
+root/
+├── app/
+│   ├── db/
+│   │   ├── mysql.js
+│   │   └── mongoose.js
+│   └── routes/
+│       └── group/
+│           └── subGroup/
+│               └── router.js
+├── server.js
+├── node_modules/
+└── package.json
 ```
--root
---app
-----db
-------mysql.js
-------mongoose.js
-----routes
-------group
----------subGroup
-------------router.js
---server.js
---node_module
---package.json
-```
-When `router.js` require `mysql.js`  relative path
+
+Instead of relative paths:
 ```javascript
 const mysql = require('../../../../db/mysql')
 ```
-When `router.js` require `mysql.js`  absolute path
+
+Use absolute paths from the project root:
 ```javascript
 const use = require('abrequire')
 const mysql = use('app/db/mysql')
 ```
+
+## TypeScript Support
+
+abrequire includes TypeScript type definitions out of the box.
+
+### Basic usage with explicit type
+
+Provide the type manually using a generic parameter:
+
+```typescript
+import use = require('abrequire')
+
+const mysql = use<typeof import('./app/db/mysql')>('app/db/mysql')
+```
+
+### Automatic type inference via module augmentation
+
+For the best experience, register your module paths and their types once using
+TypeScript's module augmentation. After that, `use()` will automatically infer
+the correct return type for each registered path — no generics needed at the call site.
+
+**Step 1** — Create a declaration file in your project (e.g. `global.d.ts`):
+
+```typescript
+declare module 'abrequire' {
+  interface AbrequireModules {
+    'app/db/mysql': typeof import('./app/db/mysql')
+    'app/db/mongoose': typeof import('./app/db/mongoose')
+    'app/utils/helper': typeof import('./app/utils/helper')
+  }
+}
+```
+
+**Step 2** — Use `use()` anywhere in your project with full type safety:
+
+```typescript
+import use = require('abrequire')
+
+const mysql = use('app/db/mysql')       // type is inferred automatically
+const mongoose = use('app/db/mongoose') // type is inferred automatically
+```
+
+Unregistered paths fall back to `any`, so you can still use them freely:
+
+```typescript
+const something = use('app/other/module') // type: any
+```
+
 ## Authors
 
 * **Nonthachai Korninai** - [Github](https://github.com/7elven)
 
 ## License
 
 This project is licensed under the MIT License
-

index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Register your module paths and types here via module augmentation:
+ *
+ * declare module 'abrequire' {
+ *   interface AbrequireModules {
+ *     'app/db/mysql': typeof import('./app/db/mysql');
+ *     'app/utils/helper': typeof import('./app/utils/helper');
+ *   }
+ * }
+ */
+export interface AbrequireModules {}
+
+/**
+ * Require a module using an absolute path from the project root.
+ *
+ * When the path is registered in AbrequireModules, the return type is inferred automatically.
+ * Otherwise, you can provide the type explicitly: use<MyModule>('app/my-module')
+ *
+ * @example
+ * const mysql = use('app/db/mysql')  // typed if registered in AbrequireModules
+ * const helper = use<Helper>('app/utils/helper')  // explicit type
+ */
+declare function use<K extends keyof AbrequireModules>(path: K): AbrequireModules[K];
+declare function use<T = any>(path: string): T;
+
+export = use;

package.json

@@ -3,6 +3,7 @@
   "version": "0.0.4",
   "description": "abrequire is absolute path require",
   "main": "index.js",
+  "types": "index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/7elven/abrequire"