stadata-js 0.4.0 → 2.0.0

package/README.md

@@ -2,317 +2,166 @@
 
 [![npm version](https://img.shields.io/npm/v/stadata-js.svg)](https://www.npmjs.com/package/stadata-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-ipds--59.github.io-blue)](https://ipds-59.github.io/stadata_js/)
 
-Official TypeScript/JavaScript SDK for BPS (Badan Pusat Statistik) WebAPI - Seamlessly access Indonesia's Central Bureau of Statistics data through a comprehensive, type-safe client library.
+Official TypeScript/JavaScript SDK for BPS (Badan Pusat Statistik) WebAPI — Seamlessly access Indonesia's Central Bureau of Statistics data through a comprehensive, type-safe client library.
 
 ## Overview
 
 The STADATA JS SDK provides TypeScript/JavaScript developers with streamlined access to Indonesia's statistical data through the official BPS WebAPI. Create data-driven applications featuring demographic, economic, and socio-economic information from Indonesia's most authoritative statistical source.
 
-This toolkit facilitates seamless integration with BPS data sources, eliminating the need for manual downloads from the BPS website. Access publications, press releases, static/dynamic tables, infographics, census datasets, and much more through a clean, modern API.
-
 ## Features
 
-- **Full TypeScript Support** - Complete type definitions for all API endpoints with IntelliSense support
-- **Clean Architecture** - Follows Clean Architecture principles with clear separation of concerns
-- **Result Pattern** - Uses neverthrow library for elegant, functional error handling
-- **Dependency Injection** - Built-in DI container for flexible, testable architecture
-- **Request Cancellation** - Support for cancelling ongoing requests to optimize performance
-- **Interceptors** - Extensible request/response interceptor system for custom middleware
-- **Logging** - Configurable logging system with multiple log levels for debugging
-- **Immutable Entities** - All domain entities are immutable for predictable behavior
-- **Pagination Support** - Built-in pagination handling for all list endpoints
-- **Modern JavaScript** - Built for modern ES6+ environments with CommonJS and ESM support
+- **Functional Composable API** — `createStadataClient()` + `use*()` composables, idiomatic TypeScript
+- **Full TypeScript Support** — Complete type definitions with IntelliSense support
+- **Result Pattern** — Uses `neverthrow` for elegant, type-safe error handling
+- **Tree-shakeable** — Only bundle what you use
+- **Pagination Support** — Built-in pagination handling for all list endpoints
+- **Request Cancellation** — Cancel ongoing requests to optimize performance
+- **Immutable Entities** — Predictable, safe domain entities
 
 ## Requirements
 
 - Node.js >= 16.0.0
-- Valid API key from BPS WebAPI platform
+- Valid API key from [BPS WebAPI platform](https://webapi.bps.go.id/)
 
 ## Installation
 
 ```bash
+# npm
 npm install stadata-js
-```
 
-or using yarn:
+# pnpm
+pnpm add stadata-js
 
-```bash
+# yarn
 yarn add stadata-js
 ```
 
-or using pnpm:
-
-```bash
-pnpm add stadata-js
-```
-
 ## Quick Start
 
 ```typescript
-import { StadataJS, DataLanguage } from 'stadata-js';
+import { initStadata, usePublications, useDomains, DataLanguage, DomainType } from 'stadata-js'
 
-// Initialize the SDK with your API key
-await StadataJS.init({
-  apiKey: 'your-api-key-here',
-  debug: false, // Enable debug logging if needed
-});
+// 1. Initialize once at app entry point
+initStadata({ apiKey: 'your-api-key-here' })
 
-// Get the SDK instance
-const stadata = StadataJS.instance;
+// 2. Use composables anywhere — no client reference needed
+const { fetchPublicationList, fetchPublicationDetail } = usePublications()
+const { fetchDomainList } = useDomains()
 
-// Fetch all domains with pagination
-const domainsResult = await stadata.list.domains({
-  lang: DataLanguage.EN,
+// 3. Fetch data
+const result = await fetchPublicationList({
+  domain: '7200',
+  lang: DataLanguage.ID,
   page: 1,
   perPage: 10,
-});
-
-// Handle the result using pattern matching
-domainsResult.match(
-  (listResult) => {
-    console.log('Domains:', listResult.data);
-    console.log('Total:', listResult.pagination.total);
-    console.log('Current Page:', listResult.pagination.page);
-  },
-  (error) => {
-    console.error('Error:', error.message);
-  }
-);
-
-// Fetch a specific domain by ID
-const domainResult = await stadata.view.domain({
-  id: '7315',
-  lang: DataLanguage.ID,
-});
-
-domainResult.match(
-  (domain) => {
-    console.log('Domain Name:', domain.name);
-    console.log('Domain URL:', domain.url);
-  },
-  (error) => {
-    console.error('Error:', error.message);
-  }
-);
-```
-
-## Available Features
-
-### ✅ Fully Implemented
-
-The SDK currently supports the following BPS data categories:
+})
 
-1. **Domains** - Statistical domain information
-2. **Publications** - Statistical publications and reports
-3. **Infographics** - Visual statistical representations
-4. **News** - Latest statistical news
-5. **News Categories** - News categorization
-6. **Press Releases** - Official press releases
-7. **Static Tables** - Pre-formatted statistical tables
-8. **Subjects** - Statistical subjects
-9. **Subject Categories** - Subject categorization
-10. **Strategic Indicators** - Key economic indicators
-11. **Variables** - Statistical variables
-12. **Units** - Measurement units
-13. **Periods** - Time periods
-14. **Derived Variables** - Calculated statistical variables
-15. **Derived Periods** - Calculated time periods
-16. **Statistic Classifications** - Statistical classification systems
-17. **Census** - Census data
-18. **Dynamic Tables** - Interactive statistical tables
-19. **Foreign Trade** - International trade statistics
-
-### 🚧 Under Development
-
-The following features are planned for future releases:
-
-- **Glossary** - Statistical terminology
-- **SDG Indicators** - Sustainable Development Goals indicators
-- **Inflation** - Consumer price index data
-- **Exchange Rates** - Foreign currency exchange rates
-
-## Usage Examples
-
-### Fetching Publications
-
-```typescript
-// Get all publications
-const publicationsResult = await stadata.list.publications({
-  lang: DataLanguage.ID,
-  domain: '7315',
-  page: 1,
-  perPage: 20,
-});
-
-publicationsResult.match(
-  (result) => {
-    result.data.forEach((publication) => {
-      console.log(publication.title);
-      console.log(publication.issn);
-      console.log(publication.cover);
-    });
+result.match(
+  ({ data, pagination }) => {
+    console.log(`Total: ${pagination.total}`)
+    data.forEach(pub => console.log(pub.title))
   },
-  (error) => console.error(error.message)
-);
+  (error) => console.error('Error:', error.message)
+)
 ```
 
-### Fetching Static Tables
-
-```typescript
-// Get static tables with filters
-const tablesResult = await stadata.list.staticTables({
-  lang: DataLanguage.EN,
-  domain: '7315',
-  page: 1,
-  perPage: 15,
-});
-
-tablesResult.match(
-  (result) => {
-    result.data.forEach((table) => {
-      console.log(table.title);
-      console.log(table.subjectId);
-      console.log(table.table);
-    });
-  },
-  (error) => console.error(error.message)
-);
-```
-
-### Fetching Foreign Trade Data
+## API Reference
 
-```typescript
-// Get trade data
-const tradeResult = await stadata.list.trades({
-  lang: DataLanguage.ID,
-  page: 1,
-  perPage: 10,
-});
-
-tradeResult.match(
-  (result) => {
-    result.data.forEach((trade) => {
-      console.log(trade.title);
-      console.log(trade.period);
-      console.log(trade.hsLevel);
-    });
-  },
-  (error) => console.error(error.message)
-);
-```
+Full documentation: **[ipds-59.github.io/stadata_js](https://ipds-59.github.io/stadata_js/)**
+
+### Available Composables
+
+| Composable | Functions |
+|-----------|-----------|
+| `stadata.useDomains()` | `fetchDomainList` |
+| `stadata.usePublications()` | `fetchPublicationList`, `fetchPublicationDetail` |
+| `stadata.usePressReleases()` | `fetchPressReleaseList`, `fetchPressReleaseDetail` |
+| `stadata.useStaticTables()` | `fetchStaticTableList`, `fetchStaticTableDetail` |
+| `stadata.useDynamicTables()` | `fetchDynamicTableList` |
+| `stadata.useInfographics()` | `fetchInfographicList` |
+| `stadata.useNews()` | `fetchNewsList`, `fetchNewsDetail` |
+| `stadata.useNewsCategories()` | `fetchNewsCategoryList` |
+| `stadata.useVariables()` | `fetchVariableList`, `fetchVariableDetail` |
+| `stadata.useVerticalVariables()` | `fetchVerticalVariableList` |
+| `stadata.useDerivedVariables()` | `fetchDerivedVariableList` |
+| `stadata.useSubjects()` | `fetchSubjectList`, `fetchSubjectDetail` |
+| `stadata.useSubjectCategories()` | `fetchSubjectCategoryList` |
+| `stadata.useUnits()` | `fetchUnitList`, `fetchUnitDetail` |
+| `stadata.usePeriods()` | `fetchPeriodList` |
+| `stadata.useDerivedPeriods()` | `fetchDerivedPeriodList` |
+| `stadata.useStrategicIndicators()` | `fetchStrategicIndicatorList`, `fetchStrategicIndicatorDetail` |
+| `stadata.useStatisticClassifications()` | `fetchStatisticClassificationList`, `fetchStatisticClassificationDetail` |
+| `stadata.useCensus()` | `fetchCensusList` |
+| `stadata.useTrade()` | `fetchTradeData` |
 
 ### Error Handling
 
-The SDK uses the Result pattern from the `neverthrow` library for elegant error handling:
+All functions return `Result<T, ApiFailure>` from [neverthrow](https://github.com/supermacro/neverthrow):
 
 ```typescript
-const result = await stadata.list.domains({
-  lang: DataLanguage.EN,
-});
+const result = await fetchPublicationList({ domain: '7200', lang: DataLanguage.ID })
 
-// Pattern matching approach
+// Option 1: match
 result.match(
-  (success) => {
-    // Handle success case
-    console.log('Data:', success.data);
-  },
-  (error) => {
-    // Handle error case
-    console.error('Error occurred:', error.message);
-  }
-);
+  ({ data, pagination }) => console.log(data),
+  (error) => console.error(error.message)
+)
 
-// isOk/isErr approach
+// Option 2: guard check
 if (result.isOk()) {
-  const data = result.value;
-  console.log('Success:', data);
-} else {
-  const error = result.error;
-  console.error('Failed:', error);
+  const { data, pagination } = result.value
 }
-```
-
-## API Reference
-
-### StadataJS
-
-Main SDK class for initialization and access to all features.
-
-#### Methods
 
-- `StadataJS.init(config: ApiConfig): Promise<void>` - Initialize the SDK with configuration
-- `StadataJS.instance: StadataJS` - Get the singleton SDK instance
-
-### Configuration
-
-```typescript
-interface ApiConfig {
-  apiKey: string;        // Your BPS WebAPI key (required)
-  debug?: boolean;       // Enable debug logging (default: false)
-  baseUrl?: string;      // Custom API base URL (optional)
+if (result.isErr()) {
+  console.error(result.error.message)
 }
 ```
 
-### Data Language
+## Configuration
 
 ```typescript
-enum DataLanguage {
-  ID = 'ind',  // Indonesian
-  EN = 'eng',  // English
-}
+const stadata = createStadataClient({
+  apiKey: 'your-api-key',       // required
+  timeout: 15000,                // optional, ms (default: 30000)
+  debug: true,                   // optional, enable debug logging
+  baseURL: 'https://...',        // optional, custom base URL
+})
 ```
 
-## Architecture
-
-The SDK follows Clean Architecture principles with clear separation between:
+## Migration from v1
 
-- **Domain Layer** - Business entities and use cases
-- **Data Layer** - Repository implementations and data sources
-- **Core Layer** - Base classes, utilities, and infrastructure
-- **API Layer** - Public-facing SDK interface
+**v1 (deprecated):**
+```typescript
+await StadataJS.init({ apiKey: 'key' })
+const stadata = StadataJS.instance
+const result = await stadata.list.publications({ domain: '7200', lang: DataLanguage.ID })
+```
 
-This architecture ensures:
-- High testability
-- Loose coupling between components
-- Easy maintenance and extensibility
-- Clear separation of concerns
+**v2:**
+```typescript
+// Entry point
+initStadata({ apiKey: 'key' })
 
-## Contributing
+// Anywhere in app
+const { fetchPublicationList } = usePublications()
+const result = await fetchPublicationList({ domain: '7200', lang: DataLanguage.ID })
+```
 
-We welcome contributions! Whether you're fixing bugs, improving documentation, adding tests, or implementing new features, your help is appreciated.
+> `StadataJS` class is kept as `@deprecated` in v2 and will be removed in v3.
 
-### How to Contribute
+## Advanced: Multiple Clients
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes using conventional commits (`git commit -m 'feat: add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request to the `develop` branch
+If you need multiple clients (e.g. different API keys), use `createStadataClient` directly:
 
-### Contribution Areas
+```typescript
+import { createStadataClient, usePublications } from 'stadata-js'
 
-- **Bug Reports** - Report issues you encounter
-- **Feature Requests** - Suggest new capabilities
-- **Documentation** - Improve guides and examples
-- **Testing** - Add or improve test coverage
-- **Code** - Implement new features or fix bugs
+const client = createStadataClient({ apiKey: 'other-key' })
+const { fetchPublicationList } = usePublications(client) // explicit client
+```
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Links
-
-- [npm Package](https://www.npmjs.com/package/stadata-js)
-- [GitHub Repository](https://github.com/IPDS-59/stadata_js)
-- [Issue Tracker](https://github.com/IPDS-59/stadata_js/issues)
-- [BPS Website](https://www.bps.go.id)
-
-## Acknowledgments
-
-This SDK is an unofficial community project and is not affiliated with or endorsed by BPS (Badan Pusat Statistik). All data accessed through this SDK is provided by BPS through their official WebAPI.
-
----
-
-Made with ❤️ for the Indonesian developer community
+MIT © [IPDS-59](https://github.com/IPDS-59)