stadata-js 1.1.0 → 2.0.1

package/README.md

@@ -2,317 +2,199 @@
 
 [![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** — `initStadata()` + `use*()` composables by default, with optional explicit clients for advanced use cases
+- **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);
+result.match(
+  ({ data, pagination }) => {
+    console.log(`Total: ${pagination.total}`)
+    data.forEach(pub => console.log(pub.title))
   },
-  (error) => {
-    console.error('Error:', error.message);
-  }
-);
+  (error) => console.error('Error:', error.message)
+)
 ```
 
-## Available Features
+## API Reference
 
-### ✅ Fully Implemented
+Full documentation: **[ipds-59.github.io/stadata_js](https://ipds-59.github.io/stadata_js/)**
+
+### Available Composables
+
+| Composable | Functions |
+|-----------|-----------|
+| `useDomains()` | `fetchDomainList` |
+| `usePublications()` | `fetchPublicationList`, `fetchPublicationDetail` |
+| `usePressReleases()` | `fetchPressReleaseList`, `fetchPressReleaseDetail` |
+| `useStaticTables()` | `fetchStaticTableList`, `fetchStaticTableDetail` |
+| `useDynamicTables()` | `fetchDynamicTableList` |
+| `useInfographics()` | `fetchInfographicList` |
+| `useNews()` | `fetchNewsList`, `fetchNewsDetail` |
+| `useNewsCategories()` | `fetchNewsCategoryList` |
+| `useVariables()` | `fetchVariableList`, `fetchVariableDetail` |
+| `useVerticalVariables()` | `fetchVerticalVariableList` |
+| `useDerivedVariables()` | `fetchDerivedVariableList` |
+| `useSubjects()` | `fetchSubjectList`, `fetchSubjectDetail` |
+| `useSubjectCategories()` | `fetchSubjectCategoryList` |
+| `useUnits()` | `fetchUnitList`, `fetchUnitDetail` |
+| `usePeriods()` | `fetchPeriodList` |
+| `useDerivedPeriods()` | `fetchDerivedPeriodList` |
+| `useStrategicIndicators()` | `fetchStrategicIndicatorList`, `fetchStrategicIndicatorDetail` |
+| `useStatisticClassifications()` | `fetchStatisticClassificationList`, `fetchStatisticClassificationDetail` |
+| `useCensus()` | `fetchCensusList` |
+| `useTrade()` | `fetchTradeData` |
 
-The SDK currently supports the following BPS data categories:
+### Error Handling
 
-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
+All functions return `Result<T, ApiFailure>` from [neverthrow](https://github.com/supermacro/neverthrow):
 
-### 🚧 Under Development
+```typescript
+const result = await fetchPublicationList({ domain: '7200', lang: DataLanguage.ID })
 
-The following features are planned for future releases:
+// Option 1: match
+result.match(
+  ({ data, pagination }) => console.log(data),
+  (error) => console.error(error.message)
+)
 
-- **Glossary** - Statistical terminology
-- **SDG Indicators** - Sustainable Development Goals indicators
-- **Inflation** - Consumer price index data
-- **Exchange Rates** - Foreign currency exchange rates
+// Option 2: guard check
+if (result.isOk()) {
+  const { data, pagination } = result.value
+}
 
-## Usage Examples
+if (result.isErr()) {
+  console.error(result.error.message)
+}
+```
 
-### Fetching Publications
+## Configuration
 
 ```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);
-    });
-  },
-  (error) => console.error(error.message)
-);
+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
+})
 ```
 
-### Fetching Static Tables
+## Migration from v1
 
-```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)
-);
-```
+Version 2 introduces a **breaking change** from the class-based API to the composable API.
 
-### Fetching Foreign Trade Data
+### v1 (deprecated)
 
 ```typescript
-// Get trade data
-const tradeResult = await stadata.list.trades({
+await StadataJS.init({ apiKey: 'key' })
+const stadata = StadataJS.instance
+
+const publications = await stadata.list.publications({
+  domain: '7200',
   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)
-);
+})
 ```
 
-### Error Handling
-
-The SDK uses the Result pattern from the `neverthrow` library for elegant error handling:
+### v2 (recommended)
 
 ```typescript
-const result = await stadata.list.domains({
-  lang: DataLanguage.EN,
-});
-
-// Pattern matching approach
-result.match(
-  (success) => {
-    // Handle success case
-    console.log('Data:', success.data);
-  },
-  (error) => {
-    // Handle error case
-    console.error('Error occurred:', error.message);
-  }
-);
+import { initStadata, usePublications, DataLanguage } from 'stadata-js'
 
-// isOk/isErr approach
-if (result.isOk()) {
-  const data = result.value;
-  console.log('Success:', data);
-} else {
-  const error = result.error;
-  console.error('Failed:', error);
-}
-```
+// initialize once at app entry point
+initStadata({ apiKey: 'key' })
 
-## API Reference
+// use composables anywhere in your app
+const { fetchPublicationList, fetchPublicationDetail } = usePublications()
 
-### StadataJS
+const publications = await fetchPublicationList({
+  domain: '7200',
+  lang: DataLanguage.ID,
+})
+```
 
-Main SDK class for initialization and access to all features.
+### What changed
 
-#### Methods
+- `StadataJS.init()` → `initStadata()`
+- `StadataJS.instance.list.publications()` → `usePublications().fetchPublicationList()`
+- `StadataJS.instance.view.publication()` → `usePublications().fetchPublicationDetail()`
+- list/view methods are now grouped by composable (`useDomains`, `useNews`, `useDynamicTables`, etc.)
+- global initialization is the default pattern, so you no longer need to carry a singleton instance around your app
 
-- `StadataJS.init(config: ApiConfig): Promise<void>` - Initialize the SDK with configuration
-- `StadataJS.instance: StadataJS` - Get the singleton SDK instance
+### Advanced migration path
 
-### Configuration
+If you need multiple clients (for example different API keys), you can still use an explicit client:
 
 ```typescript
-interface ApiConfig {
-  apiKey: string;        // Your BPS WebAPI key (required)
-  debug?: boolean;       // Enable debug logging (default: false)
-  baseUrl?: string;      // Custom API base URL (optional)
-}
-```
+import { createStadataClient, usePublications } from 'stadata-js'
 
-### Data Language
-
-```typescript
-enum DataLanguage {
-  ID = 'ind',  // Indonesian
-  EN = 'eng',  // English
-}
+const client = createStadataClient({ apiKey: 'other-key' })
+const { fetchPublicationList } = usePublications(client)
 ```
 
-## Architecture
-
-The SDK follows Clean Architecture principles with clear separation between:
-
-- **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
-
-This architecture ensures:
-- High testability
-- Loose coupling between components
-- Easy maintenance and extensibility
-- Clear separation of concerns
-
-## Contributing
-
-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 for transition purposes 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)