stadata-js 2.0.0 → 2.0.1

package/README.md

@@ -12,7 +12,7 @@ The STADATA JS SDK provides TypeScript/JavaScript developers with streamlined ac
 
 ## Features
 
-- **Functional Composable API** — `createStadataClient()` + `use*()` composables, idiomatic TypeScript
+- **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
@@ -75,26 +75,26 @@ Full documentation: **[ipds-59.github.io/stadata_js](https://ipds-59.github.io/s
 
 | 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` |
+| `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` |
 
 ### Error Handling
 
@@ -132,24 +132,57 @@ const stadata = createStadataClient({
 
 ## Migration from v1
 
-**v1 (deprecated):**
+Version 2 introduces a **breaking change** from the class-based API to the composable API.
+
+### v1 (deprecated)
+
 ```typescript
 await StadataJS.init({ apiKey: 'key' })
 const stadata = StadataJS.instance
-const result = await stadata.list.publications({ domain: '7200', lang: DataLanguage.ID })
+
+const publications = await stadata.list.publications({
+  domain: '7200',
+  lang: DataLanguage.ID,
+})
 ```
 
-**v2:**
+### v2 (recommended)
+
 ```typescript
-// Entry point
+import { initStadata, usePublications, DataLanguage } from 'stadata-js'
+
+// initialize once at app entry point
 initStadata({ apiKey: 'key' })
 
-// Anywhere in app
-const { fetchPublicationList } = usePublications()
-const result = await fetchPublicationList({ domain: '7200', lang: DataLanguage.ID })
+// use composables anywhere in your app
+const { fetchPublicationList, fetchPublicationDetail } = usePublications()
+
+const publications = await fetchPublicationList({
+  domain: '7200',
+  lang: DataLanguage.ID,
+})
+```
+
+### What changed
+
+- `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
+
+### Advanced migration path
+
+If you need multiple clients (for example different API keys), you can still use an explicit client:
+
+```typescript
+import { createStadataClient, usePublications } from 'stadata-js'
+
+const client = createStadataClient({ apiKey: 'other-key' })
+const { fetchPublicationList } = usePublications(client)
 ```
 
-> `StadataJS` class is kept as `@deprecated` in v2 and will be removed in v3.
+> `StadataJS` class is kept as `@deprecated` in v2 for transition purposes and will be removed in v3.
 
 ## Advanced: Multiple Clients
 

package/dist/index.d.mts

@@ -200,68 +200,76 @@ declare enum DomainType {
 
 type JSON = Record<string, unknown>;
 interface BaseListParams {
-    domain?: string;
     lang?: DataLanguage;
     page?: number;
     perPage?: number;
     cancelToken?: CancelToken;
 }
-interface DomainListParams extends Omit<BaseListParams, 'domain'> {
+interface BaseDomainListParams extends BaseListParams {
+    domain: string;
+}
+interface DomainListParams extends BaseListParams {
     type: DomainType;
     provinceCode?: string;
     keyword?: string;
 }
-interface PublicationListParams extends BaseListParams {
+interface PublicationListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface InfographicListParams extends BaseListParams {
+interface InfographicListParams extends BaseDomainListParams {
     keyword?: string;
 }
-interface StaticTableListParams extends BaseListParams {
+interface StaticTableListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface NewsListParams extends BaseListParams {
+interface NewsListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
     newsCategoryId?: string;
 }
-interface NewsCategoryListParams extends BaseListParams {
+interface NewsCategoryListParams extends BaseDomainListParams {
 }
-interface PressReleaseListParams extends BaseListParams {
+interface PressReleaseListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface SubjectListParams extends BaseListParams {
+interface SubjectListParams extends BaseDomainListParams {
+    subjectCategoryId?: number;
 }
-interface SubjectCategoryListParams extends BaseListParams {
+interface SubjectCategoryListParams extends BaseDomainListParams {
 }
-interface StrategicIndicatorListParams extends BaseListParams {
+interface StrategicIndicatorListParams extends BaseDomainListParams {
+    variableId?: number;
 }
-interface VariableListParams extends BaseListParams {
+interface VariableListParams extends BaseDomainListParams {
     subjectId?: number;
+    year?: number;
+    showExistingVariables?: boolean;
     showDeleted?: boolean;
 }
-interface VerticalVariableListParams extends BaseListParams {
+interface VerticalVariableListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface UnitListParams extends BaseListParams {
+interface UnitListParams extends BaseDomainListParams {
+    variableId?: number;
 }
-interface PeriodListParams extends BaseListParams {
+interface PeriodListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface DerivedPeriodListParams extends BaseListParams {
+interface DerivedPeriodListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface DerivedVariableListParams extends BaseListParams {
+interface DerivedVariableListParams extends BaseDomainListParams {
     variableId?: number;
+    verticalGroup?: number;
 }
-interface DynamicTableParams extends BaseListParams {
+interface DynamicTableParams extends BaseDomainListParams {
     variableId: number;
     periodId: string;
     derivedVariableId?: number;
@@ -269,6 +277,7 @@ interface DynamicTableParams extends BaseListParams {
     derivedPeriodId?: string;
 }
 interface StatisticClassificationListParams extends BaseListParams {
+    domain?: string;
     type?: ClassificationType;
     level?: ClassificationLevel;
     keyword?: string;
@@ -872,6 +881,13 @@ declare function initStadata(config: StadataClientConfig): StadataClientInstance
 declare function getGlobalClient(): StadataClientInstance;
 declare function resetGlobalClient(): void;
 
+declare class DynamicTableHtmlGenerator {
+    static generate(table: DynamicTable): string;
+    private static generateHeader;
+    private static generateBody;
+    private static formatValue;
+}
+
 interface StadataList {
     domains(params?: DomainListParams): Promise<Result<ListResult<Domain>, ApiFailure>>;
     publications(params: PublicationListParams): Promise<Result<ListResult<Publication>, ApiFailure>>;
@@ -974,4 +990,4 @@ declare class Trade extends BaseEntity {
     static fromJson(json: Record<string, unknown>): Trade;
 }
 
-export { ApiConstant, ApiEndpoint, ApiFailure, type BaseListParams, CancelToken, CancelledFailure, CensusArea, CensusCategory, CensusData, CensusDataset, CensusEvent, type CensusListParams, CensusTopic, ClassificationType, DataAvailability, DataLanguage, DerivedPeriod, type DerivedPeriodListParams, DerivedVariable, type DerivedVariableListParams, Domain, type DomainListParams, DomainType, DynamicTable, type DynamicTableParams, ForbiddenFailure, HSCodeType, Infographic, type InfographicListParams, type JSON, KBKILevel, KBLILevel, ListResult, LogLevel, NetworkClient, type NetworkClientConfig, NetworkFailure, type NetworkInterceptor, News, NewsCategory, type NewsCategoryListParams, type NewsListParams, NotFoundFailure, Pagination, ParseFailure, Period, type PeriodListParams, PressRelease, type PressReleaseListParams, Publication, type PublicationListParams, RelatedPublication, type RequestData, type RequestOptions, type ResponseData, ServerFailure, type StadataClient, type StadataClientConfig, type StadataClientInstance, StadataJS, type StadataJSConfig, StaticTable, type StaticTableListParams, StatisticClassification, type StatisticClassificationListParams, StrategicIndicator, type StrategicIndicatorListParams, Subject, SubjectCategory, type SubjectCategoryListParams, type SubjectListParams, TimeoutFailure, Trade, type TradeParams, TradePeriod, TradeSource, UnauthorizedFailure, Unit, type UnitListParams, type UseCensus, type UseDerivedPeriods, type UseDerivedVariables, type UseDomains, type UseDynamicTables, type UseInfographics, type UseNews, type UseNewsCategories, type UsePeriods, type UsePressReleases, type UsePublications, type UseStaticTables, type UseStatisticClassifications, type UseStrategicIndicators, type UseSubjectCategories, type UseSubjects, type UseTrade, type UseUnits, type UseVariables, type UseVerticalVariables, ValidationFailure, Variable, type VariableListParams, VerticalVariable, type VerticalVariableListParams, type ViewParams, createStadataClient, getGlobalClient, initStadata, resetGlobalClient, useCensus, useDerivedPeriods, useDerivedVariables, useDomains, useDynamicTables, useInfographics, useNews, useNewsCategories, usePeriods, usePressReleases, usePublications, useStaticTables, useStatisticClassifications, useStrategicIndicators, useSubjectCategories, useSubjects, useTrade, useUnits, useVariables, useVerticalVariables };
+export { ApiConstant, ApiEndpoint, ApiFailure, type BaseDomainListParams, type BaseListParams, CancelToken, CancelledFailure, CensusArea, CensusCategory, CensusData, CensusDataset, CensusEvent, type CensusListParams, CensusTopic, ClassificationType, DataAvailability, DataLanguage, DerivedPeriod, type DerivedPeriodListParams, DerivedVariable, type DerivedVariableListParams, Domain, type DomainListParams, DomainType, DynamicTable, DynamicTableHtmlGenerator, type DynamicTableParams, ForbiddenFailure, HSCodeType, Infographic, type InfographicListParams, type JSON, KBKILevel, KBLILevel, ListResult, LogLevel, NetworkClient, type NetworkClientConfig, NetworkFailure, type NetworkInterceptor, News, NewsCategory, type NewsCategoryListParams, type NewsListParams, NotFoundFailure, Pagination, ParseFailure, Period, type PeriodListParams, PressRelease, type PressReleaseListParams, Publication, type PublicationListParams, RelatedPublication, type RequestData, type RequestOptions, type ResponseData, ServerFailure, type StadataClient, type StadataClientConfig, type StadataClientInstance, StadataJS, type StadataJSConfig, StaticTable, type StaticTableListParams, StatisticClassification, type StatisticClassificationListParams, StrategicIndicator, type StrategicIndicatorListParams, Subject, SubjectCategory, type SubjectCategoryListParams, type SubjectListParams, TimeoutFailure, Trade, type TradeParams, TradePeriod, TradeSource, UnauthorizedFailure, Unit, type UnitListParams, type UseCensus, type UseDerivedPeriods, type UseDerivedVariables, type UseDomains, type UseDynamicTables, type UseInfographics, type UseNews, type UseNewsCategories, type UsePeriods, type UsePressReleases, type UsePublications, type UseStaticTables, type UseStatisticClassifications, type UseStrategicIndicators, type UseSubjectCategories, type UseSubjects, type UseTrade, type UseUnits, type UseVariables, type UseVerticalVariables, ValidationFailure, Variable, type VariableListParams, VerticalVariable, type VerticalVariableListParams, type ViewParams, createStadataClient, getGlobalClient, initStadata, resetGlobalClient, useCensus, useDerivedPeriods, useDerivedVariables, useDomains, useDynamicTables, useInfographics, useNews, useNewsCategories, usePeriods, usePressReleases, usePublications, useStaticTables, useStatisticClassifications, useStrategicIndicators, useSubjectCategories, useSubjects, useTrade, useUnits, useVariables, useVerticalVariables };

package/dist/index.d.ts

@@ -200,68 +200,76 @@ declare enum DomainType {
 
 type JSON = Record<string, unknown>;
 interface BaseListParams {
-    domain?: string;
     lang?: DataLanguage;
     page?: number;
     perPage?: number;
     cancelToken?: CancelToken;
 }
-interface DomainListParams extends Omit<BaseListParams, 'domain'> {
+interface BaseDomainListParams extends BaseListParams {
+    domain: string;
+}
+interface DomainListParams extends BaseListParams {
     type: DomainType;
     provinceCode?: string;
     keyword?: string;
 }
-interface PublicationListParams extends BaseListParams {
+interface PublicationListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface InfographicListParams extends BaseListParams {
+interface InfographicListParams extends BaseDomainListParams {
     keyword?: string;
 }
-interface StaticTableListParams extends BaseListParams {
+interface StaticTableListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface NewsListParams extends BaseListParams {
+interface NewsListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
     newsCategoryId?: string;
 }
-interface NewsCategoryListParams extends BaseListParams {
+interface NewsCategoryListParams extends BaseDomainListParams {
 }
-interface PressReleaseListParams extends BaseListParams {
+interface PressReleaseListParams extends BaseDomainListParams {
     keyword?: string;
     month?: number;
     year?: number;
 }
-interface SubjectListParams extends BaseListParams {
+interface SubjectListParams extends BaseDomainListParams {
+    subjectCategoryId?: number;
 }
-interface SubjectCategoryListParams extends BaseListParams {
+interface SubjectCategoryListParams extends BaseDomainListParams {
 }
-interface StrategicIndicatorListParams extends BaseListParams {
+interface StrategicIndicatorListParams extends BaseDomainListParams {
+    variableId?: number;
 }
-interface VariableListParams extends BaseListParams {
+interface VariableListParams extends BaseDomainListParams {
     subjectId?: number;
+    year?: number;
+    showExistingVariables?: boolean;
     showDeleted?: boolean;
 }
-interface VerticalVariableListParams extends BaseListParams {
+interface VerticalVariableListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface UnitListParams extends BaseListParams {
+interface UnitListParams extends BaseDomainListParams {
+    variableId?: number;
 }
-interface PeriodListParams extends BaseListParams {
+interface PeriodListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface DerivedPeriodListParams extends BaseListParams {
+interface DerivedPeriodListParams extends BaseDomainListParams {
     variableId?: number;
 }
-interface DerivedVariableListParams extends BaseListParams {
+interface DerivedVariableListParams extends BaseDomainListParams {
     variableId?: number;
+    verticalGroup?: number;
 }
-interface DynamicTableParams extends BaseListParams {
+interface DynamicTableParams extends BaseDomainListParams {
     variableId: number;
     periodId: string;
     derivedVariableId?: number;
@@ -269,6 +277,7 @@ interface DynamicTableParams extends BaseListParams {
     derivedPeriodId?: string;
 }
 interface StatisticClassificationListParams extends BaseListParams {
+    domain?: string;
     type?: ClassificationType;
     level?: ClassificationLevel;
     keyword?: string;
@@ -872,6 +881,13 @@ declare function initStadata(config: StadataClientConfig): StadataClientInstance
 declare function getGlobalClient(): StadataClientInstance;
 declare function resetGlobalClient(): void;
 
+declare class DynamicTableHtmlGenerator {
+    static generate(table: DynamicTable): string;
+    private static generateHeader;
+    private static generateBody;
+    private static formatValue;
+}
+
 interface StadataList {
     domains(params?: DomainListParams): Promise<Result<ListResult<Domain>, ApiFailure>>;
     publications(params: PublicationListParams): Promise<Result<ListResult<Publication>, ApiFailure>>;
@@ -974,4 +990,4 @@ declare class Trade extends BaseEntity {
     static fromJson(json: Record<string, unknown>): Trade;
 }
 
-export { ApiConstant, ApiEndpoint, ApiFailure, type BaseListParams, CancelToken, CancelledFailure, CensusArea, CensusCategory, CensusData, CensusDataset, CensusEvent, type CensusListParams, CensusTopic, ClassificationType, DataAvailability, DataLanguage, DerivedPeriod, type DerivedPeriodListParams, DerivedVariable, type DerivedVariableListParams, Domain, type DomainListParams, DomainType, DynamicTable, type DynamicTableParams, ForbiddenFailure, HSCodeType, Infographic, type InfographicListParams, type JSON, KBKILevel, KBLILevel, ListResult, LogLevel, NetworkClient, type NetworkClientConfig, NetworkFailure, type NetworkInterceptor, News, NewsCategory, type NewsCategoryListParams, type NewsListParams, NotFoundFailure, Pagination, ParseFailure, Period, type PeriodListParams, PressRelease, type PressReleaseListParams, Publication, type PublicationListParams, RelatedPublication, type RequestData, type RequestOptions, type ResponseData, ServerFailure, type StadataClient, type StadataClientConfig, type StadataClientInstance, StadataJS, type StadataJSConfig, StaticTable, type StaticTableListParams, StatisticClassification, type StatisticClassificationListParams, StrategicIndicator, type StrategicIndicatorListParams, Subject, SubjectCategory, type SubjectCategoryListParams, type SubjectListParams, TimeoutFailure, Trade, type TradeParams, TradePeriod, TradeSource, UnauthorizedFailure, Unit, type UnitListParams, type UseCensus, type UseDerivedPeriods, type UseDerivedVariables, type UseDomains, type UseDynamicTables, type UseInfographics, type UseNews, type UseNewsCategories, type UsePeriods, type UsePressReleases, type UsePublications, type UseStaticTables, type UseStatisticClassifications, type UseStrategicIndicators, type UseSubjectCategories, type UseSubjects, type UseTrade, type UseUnits, type UseVariables, type UseVerticalVariables, ValidationFailure, Variable, type VariableListParams, VerticalVariable, type VerticalVariableListParams, type ViewParams, createStadataClient, getGlobalClient, initStadata, resetGlobalClient, useCensus, useDerivedPeriods, useDerivedVariables, useDomains, useDynamicTables, useInfographics, useNews, useNewsCategories, usePeriods, usePressReleases, usePublications, useStaticTables, useStatisticClassifications, useStrategicIndicators, useSubjectCategories, useSubjects, useTrade, useUnits, useVariables, useVerticalVariables };
+export { ApiConstant, ApiEndpoint, ApiFailure, type BaseDomainListParams, type BaseListParams, CancelToken, CancelledFailure, CensusArea, CensusCategory, CensusData, CensusDataset, CensusEvent, type CensusListParams, CensusTopic, ClassificationType, DataAvailability, DataLanguage, DerivedPeriod, type DerivedPeriodListParams, DerivedVariable, type DerivedVariableListParams, Domain, type DomainListParams, DomainType, DynamicTable, DynamicTableHtmlGenerator, type DynamicTableParams, ForbiddenFailure, HSCodeType, Infographic, type InfographicListParams, type JSON, KBKILevel, KBLILevel, ListResult, LogLevel, NetworkClient, type NetworkClientConfig, NetworkFailure, type NetworkInterceptor, News, NewsCategory, type NewsCategoryListParams, type NewsListParams, NotFoundFailure, Pagination, ParseFailure, Period, type PeriodListParams, PressRelease, type PressReleaseListParams, Publication, type PublicationListParams, RelatedPublication, type RequestData, type RequestOptions, type ResponseData, ServerFailure, type StadataClient, type StadataClientConfig, type StadataClientInstance, StadataJS, type StadataJSConfig, StaticTable, type StaticTableListParams, StatisticClassification, type StatisticClassificationListParams, StrategicIndicator, type StrategicIndicatorListParams, Subject, SubjectCategory, type SubjectCategoryListParams, type SubjectListParams, TimeoutFailure, Trade, type TradeParams, TradePeriod, TradeSource, UnauthorizedFailure, Unit, type UnitListParams, type UseCensus, type UseDerivedPeriods, type UseDerivedVariables, type UseDomains, type UseDynamicTables, type UseInfographics, type UseNews, type UseNewsCategories, type UsePeriods, type UsePressReleases, type UsePublications, type UseStaticTables, type UseStatisticClassifications, type UseStrategicIndicators, type UseSubjectCategories, type UseSubjects, type UseTrade, type UseUnits, type UseVariables, type UseVerticalVariables, ValidationFailure, Variable, type VariableListParams, VerticalVariable, type VerticalVariableListParams, type ViewParams, createStadataClient, getGlobalClient, initStadata, resetGlobalClient, useCensus, useDerivedPeriods, useDerivedVariables, useDomains, useDynamicTables, useInfographics, useNews, useNewsCategories, usePeriods, usePressReleases, usePublications, useStaticTables, useStatisticClassifications, useStrategicIndicators, useSubjectCategories, useSubjects, useTrade, useUnits, useVariables, useVerticalVariables };