প্রকল্প সম্পর্কে

# @overeng Effect Utils প্রোডাকশন-রেডি Effect ইউটিলিটি ও ইন্টিগ্রেশনের একটি সংগ্রহ। ## প্যাকেজসমূহ ### Notion ইন্টিগ্রেশন টাইপ-সেফ স্কিমা জেনারেশনসহ পূর্ণাঙ্গ Effect-নেটিভ Notion API ক্লায়েন্ট। #### @overeng/notion-effect-client টাইপড কোয়েরিসহ Notion API-এর জন্য Effect-নেটিভ HTTP ক্লায়েন্ট - **স্কিমা-সচেতন কোয়েরি** - Effect স্কিমা পাস করে স্বয়ংক্রিয় ডিকোডিংসহ সম্পূর্ণ টাইপড ফলাফল পান - **Markdown রূপান্তর** - কাস্টমাইজযোগ্য ট্রান্সফরমার দিয়ে পেজ/ব্লককে Markdown-এ রূপান্তর করুন - **স্ট্রিমিং API** - সব লিস্ট অপারেশনের জন্য Effect Streams-এর মাধ্যমে স্বয়ংক্রিয় পেজিনেশন #### @overeng/notion-effect-schema সব Notion API টাইপের জন্য বিস্তৃত Effect স্কিমা - **সম্পূর্ণ কভারেজ** - সব ২৭টি ব্লক টাইপ এবং ২১+ প্রপার্টি টাইপের স্কিমা - **প্রপার্টি ট্রান্সফর্ম** - সহজ অ্যাক্সেসের জন্য `asString`, `asNumber`, `asOption` ভ্যারিয়েন্ট - **রাইট সাপোর্ট** - পেজ তৈরি/আপডেটের জন্য ডেডিকেটেড রাইট স্কিমা #### @overeng/notion-effect-cli আপনার Notion ডেটাবেস থেকে টাইপ-সেফ স্কিমা জেনারেট করার CLI টুল - **স্কিমা জেনারেশন** - লাইভ Notion ডেটাবেস থেকে টাইপড স্কিমা জেনারেট করুন - **ড্রিফট ডিটেকশন** - CI/CD-এর জন্য `diff` কমান্ড দিয়ে স্কিমা পরিবর্তন ট্র্যাক করুন - **API র্যাপার জেনারেশন** - `--include-api` দিয়ে টাইপড CRUD অপারেশন জেনারেট করুন ### AI ইন্টিগ্রেশন | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/effect-ai-claude-cli | Effect AI-এর জন্য Claude CLI প্রোভাইডার | API কলে টাকা খরচ করার বদলে আপনার **Claude Code সাবস্ক্রিপশন** ব্যবহার করুন। `claude` CLI-তে ডেলিগেট করে Effect AI-এর LanguageModel ইন্টারফেস ইমপ্লিমেন্ট করে। - **সাবস্ক্রিপশন-ভিত্তিক** - আপনার বিদ্যমান Claude Code সাবস্ক্রিপশন ব্যবহার করুন (API-এর চেয়ে অনেক সস্তা) - **API কী লাগে না** - CLI আপনার সাবস্ক্রিপশনের মাধ্যমে অথেন্টিকেশন সামলায় - **সম্পূর্ণ LanguageModel সাপোর্ট** - `@effect/ai` Chat, generateText ইত্যাদির সাথে কাজ করে ### স্কিমা ফর্ম অ্যাক্সেসিবল React Aria ইমপ্লিমেন্টেশনসহ Effect স্কিমার জন্য হেডলেস ফর্ম লাইব্রেরি। | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/effect-schema-form | স্কিমা ইন্ট্রোস্পেকশনসহ হেডলেস ফর্ম কম্পোনেন্ট | | @overeng/effect-schema-form-aria | Tailwind CSS-সহ স্টাইলড React Aria কম্পোনেন্ট (Storybook) | - **স্কিমা ইন্ট্রোস্পেকশন** - Effect Schema স্ট্রাকচার থেকে স্বয়ংক্রিয়ভাবে ফর্ম ফিল্ড জেনারেট করুন - **হেডলেস আর্কিটেকচার** - নিজের কম্পোনেন্ট আনুন বা প্রি-বিল্ট React Aria ইমপ্লিমেন্টেশন ব্যবহার করুন - **ট্যাগড স্ট্রাক্ট সাপোর্ট** - লেবেলযুক্ত গ্রুপসহ ডিসক্রিমিনেটেড ইউনিয়নের স্বয়ংক্রিয় হ্যান্ডলিং - **নমনীয় রেন্ডারিং** - সম্পূর্ণ নিয়ন্ত্রণের জন্য প্রোভাইডার প্যাটার্ন, রেন্ডার প্রপস, বা হুকস API - **ডিফল্টভাবে অ্যাক্সেসিবল** - WCAG কমপ্লায়েন্সসহ React Aria Components ### React ইন্টিগ্রেশন Effect-চালিত অ্যাপ্লিকেশন তৈরির জন্য React হুক ও ইউটিলিটি। | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/effect-react | হুক ও কনটেক্সট প্রোভাইডারসহ Effect রানটাইমের জন্য React ইন্টিগ্রেশন | | @overeng/react-inspector | Effect Schema সাপোর্টসহ DevTools-স্টাইল ইন্সপেক্টর (Storybook) | - **EffectProvider** - একটি Layer থেকে Effect রানটাইম ইনিশিয়ালাইজ করে React ট্রিতে প্রদান করুন - **হুকস API** - কম্পোনেন্টে ইফেক্ট চালানোর জন্য `useEffectRunner`, `useEffectCallback`, `useEffectOnMount` - **স্বয়ংক্রিয় এরর হ্যান্ডলিং** - কাস্টম এরর কম্পোনেন্টসহ বিল্ট-ইন এরর বাউন্ডারি - **DevTools ইন্সপেক্টর** - Effect Schema-সচেতন ব্রাউজার-স্টাইল অবজেক্ট/টেবিল ইন্সপেক্টর - **টাইপ-সেফ রানটাইম অ্যাক্সেস** - অ্যাডভান্সড ব্যবহারের জন্য Effect রানটাইমে সরাসরি অ্যাক্সেস ### Playwright ইন্টিগ্রেশন | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/utils/node/playwright | OTEL ইন্টিগ্রেশনসহ Effect-নেটিভ Playwright র্যাপার | - **সার্ভিস ট্যাগ** - ডিপেন্ডেন্সি ইনজেকশনের জন্য `PwPage`, `PwBrowserContext` - **স্ট্রাকচার্ড এরর** - সামঞ্জস্যপূর্ণ এরর হ্যান্ডলিংয়ের জন্য সব অপারেশন `PwOpError` দিয়ে র্যাপ করা - **OTEL স্প্যান** - ক্রস-প্রসেস ট্রেস প্রোপাগেশনসহ স্বয়ংক্রিয় ট্রেসিং - **টেস্ট হেল্পার** - Playwright টেস্টে স্বয়ংক্রিয় লেয়ার প্রোভিশনের জন্য `withTestCtx` ### ইউটিলিটি | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/utils | ডিস্ট্রিবিউটেড লক, লগ ব্রিজিং, এবং ডিবাগ ইউটিলিটি | মূল ফিচার: - BroadcastChannel-এর মাধ্যমে SharedWorker→Tab লগ ব্রিজিং (`@overeng/utils/browser`) - Scope/finalizer ডিবাগিং এবং অ্যাক্টিভ হ্যান্ডেল মনিটরিং - TTL এক্সপায়ারেশনসহ ফাইল সিস্টেম-ব্যাকড ডিস্ট্রিবিউটেড লক - ঐচ্ছিক লগিং/রিটেনশনসহ ওয়ার্কস্পেস-সচেতন কমান্ড হেল্পার ### ডেভেলপার টুলস | প্যাকেজ | বিবরণ | | --- | --- | | @overeng/genie | TypeScript-ভিত্তিক কনফিগ ফাইল জেনারেটর | | @overeng/oxc-config | শেয়ার্ড oxlint এবং oxfmt কনফিগারেশন | **Genie** TypeScript সোর্স (`.genie.ts` ফাইল) থেকে `package.json`, `tsconfig.json`, এবং GitHub ওয়ার্কফ্লো ফাইল জেনারেট করে। ফিচারসমূহ: - **টাইপ-সেফ কনফিগ** - সম্পূর্ণ অটোকমপ্লিটসহ TypeScript-এ কনফিগ ডিফাইন করুন - **সামঞ্জস্যপূর্ণ ফরম্যাটিং** - oxfmt-এর মাধ্যমে স্বয়ংক্রিয় ফরম্যাটিং - **রিড-অনলি প্রোটেকশন** - জেনারেটেড ফাইল ডিফল্টভাবে রিড-অনলি - **CI ইন্টিগ্রেশন** - `--check` মোড ফাইল আপ-টু-ডেট কিনা যাচাই করে ## কুইক স্টার্ট ### ডেভ শেল-এ প্রবেশ করুন এই রিপো একটি সামঞ্জস্যপূর্ণ টুলচেইন প্রদানের জন্য `devenv` ব্যবহার করে। শেলের ভিতরে কমান্ড চালান: ```bash devenv shell ``` ### ডিপেন্ডেন্সি ভিউ প্রকাশ করুন ```bash devenv tasks run buck2:editor:publish ``` ### সব TypeScript প্রজেক্ট চেক করুন ```bash devenv tasks run buck2:quick ``` যখন সোর্স-সাইড টুল বা এডিটরের প্রয়োজন হয়, তখন Buck-উৎপাদিত ডিক্লারেশন প্যাকেজের `dist` ডিরেক্টরিতে প্রকাশ করুন: ```bash devenv tasks run buck2:typescript:materialize-dist ``` ### টেস্ট চালান ```bash # সব টেস্ট devenv tasks run test:run # একক প্যাকেজ (যেমন, utils, genie) devenv tasks run test:utils devenv tasks run test:genie # ইন্টিগ্রেশন টেস্ট (Notion প্যাকেজের জন্য NOTION_API_TOKEN প্রয়োজন) NOTION_API_TOKEN=secret_xxx devenv tasks run test:integration # ওয়াচ মোড devenv tasks run test:watch ``` ### টাইপ চেকিং Buck-ই একমাত্র রিপোজিটরি-ব্যাপী TypeScript চেক অথরিটি: ```bash devenv tasks run buck2:quick ``` ক্রস-সেল Buck প্রোভাইডার আইডেন্টিটি আলাদাভাবে অডিট করুন: ```bash devenv tasks run buck2:providers:check ``` ### Nix আর্টিফ্যাক্ট ইমপোর্ট চেক রিপোজিটরি প্রোডাক্ট রিয়ালাইজ না করেই জেনেরিক এবং JavaScript Buck প্রোডাক্ট ইমপোর্ট বাউন্ডারি ভ্যালিডেট করুন: ```bash devenv tasks run nix:buck2-artifact-import:check devenv tasks run nix:javascript-product-import:check ``` `check:all` হোস্ট সিস্টেমের প্রতিটি flake আউটপুটও কিছু বিল্ড না করেই ইভালুয়েট করে: ```bash devenv tasks run nix:flake:eval ``` ### লিন্টিং ```bash # ফরম্যাটিং + লিন্ট চেক devenv tasks run lint:check # ফরম্যাটিং + লিন্ট সমস্যা অটো-ফিক্স devenv tasks run lint:fix ``` ## প্যাকেজ স্ট্রাকচার প্রতিটি প্যাকেজ আধুনিক ESM কনভেনশন অনুসরণ করে: - সোর্স ফাইল `src/`-এ (`.ts` এক্সটেনশনসহ TypeScript) - এন্ট্রি পয়েন্ট `src/mod.ts`-এ - কম্পাইলড আউটপুট `dist/`-এ (gitignored) - ডেভেলপমেন্ট এক্সপোর্ট সোর্স ফাইলে পয়েন্ট করে - প্রকাশিত এক্সপোর্ট কম্পাইলড JavaScript-এ পয়েন্ট করে ## কনট্রিবিউটিং এই মনোরিপো ব্যবহার করে: - প্যাকেজ ম্যানেজমেন্টের জন্য **bun workspaces** - ইনক্রিমেন্টাল বিল্ডের জন্য **TypeScript project references** - লিন্টিং ও ফরম্যাটিংয়ের জন্য **oxlint + oxfmt** - টেস্টিংয়ের জন্য **Vitest** - মূল কার্যকারিতার জন্য **Effect** প্যাকেজ-নির্দিষ্ট ডকুমেন্টেশনের জন্য আলাদা প্যাকেজ README দেখুন।