https://github.com/hichemtab-tech/ts-runtime-picker
A package to dynamically create pickers based on TypeScript interfaces.
https://github.com/hichemtab-tech/ts-runtime-picker
babel compiler javascript js picker runtime runtime-compilation ts typescript typescript-library vite vite-plugin
Last synced: 10 months ago
JSON representation
A package to dynamically create pickers based on TypeScript interfaces.
- Host: GitHub
- URL: https://github.com/hichemtab-tech/ts-runtime-picker
- Owner: HichemTab-tech
- License: mit
- Created: 2024-12-13T20:50:13.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-10T18:59:15.000Z (10 months ago)
- Last Synced: 2025-04-10T19:50:29.024Z (10 months ago)
- Topics: babel, compiler, javascript, js, picker, runtime, runtime-compilation, ts, typescript, typescript-library, vite, vite-plugin
- Language: TypeScript
- Homepage:
- Size: 211 KB
- Stars: 26
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# ts-runtime-picker
**ts-runtime-picker** 🚀 is a TypeScript-first utility package designed to dynamically transform your code and provide runtime-safe "pickers" for your objects based on TypeScript interfaces or types. The package integrates seamlessly into your Vite-based or Webpack-based projects, allowing developers to enjoy type-safe runtime logic without sacrificing development speed or flexibility.
---
## 🛠️ Problem and Solution
### 🐛 The Problem
When working with JavaScript or TypeScript, developers often pass objects directly into functions, APIs, or databases (like Firebase). This can lead to unnecessary or unwanted properties being included. For example:
```typescript
const request = {
data: {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
password: "secret",
extraField: "notNeeded",
anotherExtraField: "stillNotNeeded"
}
};
firebase.collection("users").add(request.data);
```
In this example, only `firstName`, `lastName`, `email`, and `password` might be relevant for the operation, but `extraField` and `anotherExtraField` are also sent, which could cause inefficiencies, validation errors, or unexpected behavior.
Even if you explicitly type `request.data` as `User` in TypeScript, the extra fields (`extraField` and `anotherExtraField`) still exist at runtime. TypeScript enforces types only at compile time, meaning that any additional or unwanted properties are not automatically removed:
```typescript
interface User {
firstName: string;
lastName: string;
email: string;
password: string;
}
const request: { data: User } = {
data: {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
password: "secret",
extraField: "notNeeded", // This still exists at runtime
anotherExtraField: "stillNotNeeded" // This too
}
};
firebase.collection("users").add(request.data); // `extraField` and `anotherExtraField` are still sent!
```
Manually filtering the object to ensure it adheres to a defined interface is tedious and error-prone:
```typescript
const filteredData = {
firstName: request.data.firstName,
lastName: request.data.lastName,
email: request.data.email,
password: request.data.password
};
firebase.collection("users").add(filteredData);
```
### 💡 The Solution
`ts-runtime-picker` 🧰 solves this by automatically generating a picker function based on your TypeScript interface. This function ensures that only the properties defined in the interface are included in the object:
```typescript
import { createPicker } from "ts-runtime-picker";
interface User {
firstName: string;
lastName: string;
email: string;
password: string;
}
const picker = createPicker();
const filteredData = picker(request.data);
firebase.collection("users").add(filteredData);
```
The `picker` function dynamically removes unwanted properties, ensuring only the keys specified in `User` are included. This approach:
- ⏳ Saves time by eliminating repetitive manual filtering.
- ✅ Ensures runtime safety by aligning object properties with TypeScript interfaces.
- 🐞 Reduces the risk of bugs and inefficiencies caused by sending unnecessary data.
---
## 📦 Installation
To start using `ts-runtime-picker`, follow these steps:
### 1. Install the Package
```bash
npm install ts-runtime-picker
```
### 2. Add the Vite Plugin or Webpack Loader
#### Vite Plugin
In your `vite.config.ts`, import the plugin and include it in the plugins array:
```typescript
import { defineConfig } from "vite";
import TsRuntimePickerVitePlugin from "ts-runtime-picker/vite-plugin";
export default defineConfig({
plugins: [TsRuntimePickerVitePlugin()],
});
```
#### Webpack Loader
For projects using Webpack, you can integrate `ts-runtime-picker` with the following webpack loader.
```javascript
module.exports = {
//...
module: {
rules: [
{
test: /\.ts$/,
use: [
{
loader: 'ts-loader',
},
{
loader: 'ts-runtime-picker/webpack-loader', // add the ts-runtime-picker webpack loader
},
],
include: path.resolve(__dirname, 'src'),
exclude: /node_modules/,
},
],
},
resolve: {
extensions: ['.ts', '.js'],
fallback: {
fs: false,
path: false,
os: false,
perf_hooks: false,
}
},
//...
}
```
---
## ✨ Usage
### 1. Define Your TypeScript Interface
Create a TypeScript interface that defines the structure of the object you want to pick keys from:
```typescript
interface User {
firstName: string;
lastName: string;
email: string;
password: string;
}
```
### 2. Use `createPicker`
Call the `createPicker` function with your TypeScript interface:
```typescript
import { createPicker } from "ts-runtime-picker";
const picker = createPicker();
const inputObject = {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
password: "secret",
extraField: "notNeeded",
};
const result = picker(inputObject);
console.log(result); // { firstName: "John", lastName: "Doe", email: "john.doe@example.com", password: "secret" }
```
### 3. How It Works
The plugin dynamically transforms the `createPicker()` call into a runtime-safe implementation that picks only the keys defined in `User`. This transformation works with both Vite (via the plugin) and Webpack (via the loader).
---
## 🎯 Purpose and Benefits
The goal of `ts-runtime-picker` is to bridge the gap between TypeScript's compile-time type safety and runtime JavaScript functionality. By transforming your code at build time, this package enables developers to:
- 🚫 Avoid repetitive manual key picking from objects.
- ⚡ Ensure runtime behavior aligns with TypeScript-defined interfaces.
- 🎉 Simplify code while maintaining type safety.
- 🛠 Works seamlessly with modern bundlers, including Vite (via a plugin) and Webpack (via a loader).
---
## Contributing
We welcome contributions! If you'd like to improve `ts-runtime-picker`, feel free to [open an issue](https://github.com/HichemTab-tech/ts-runtime-picker/issues) or [submit a pull request](https://github.com/HichemTab-tech/ts-runtime-picker/pulls).
## Author
- [@HichemTab-tech](https://www.github.com/HichemTab-tech)
## License
[MIT](https://github.com/HichemTab-tech/ts-runtime-picker/blob/master/LICENSE)
## 🌟 Acknowledgements
Special thanks to the open-source community and early adopters of `ts-runtime-picker` for their feedback, which helped expand support to Webpack alongside Vite.
## GitAds Sponsored
[](https://gitads.dev/v1/ad-track?source=hichemtab-tech/ts-runtime-picker@github)