dff-util 1.3.8 → 1.4.0

package/README.md

@@ -11,6 +11,7 @@ Select a topic below to view its reference and examples.
 | [AppRandomString](#general-utilities) | [AppUniqueCode](#general-utilities) | [AppCodeByType](#general-utilities) | [AppCode](#general-utilities) | [AppDaysBack](#general-utilities) | [AppAddDays](#general-utilities) | [AppUUID4](#general-utilities) |
 | [TruncateText](#text-and-date-formatting) | [DateTime24HrFormat](#text-and-date-formatting) | [DateTime12HrFormat](#text-and-date-formatting) | [DateAndTime](#text-and-date-formatting) | [TimeAgo](#text-and-date-formatting) | [toCamelCase](#case-conversion-and-object-mapping) | [toSnakeCase](#case-conversion-and-object-mapping) |
 | [toLowerCase](#case-conversion-and-object-mapping) | [toUpperCase](#case-conversion-and-object-mapping) | [toPascalCase](#case-conversion-and-object-mapping) | [toViewMapper](#case-conversion-and-object-mapping) | [toEntityMapper](#case-conversion-and-object-mapping) | [toSchemaMapper](#case-conversion-and-object-mapping) | [QueryCond](#query-conditions-querycond) |
+| [CsvToJson](#csv-and-json-conversion) | [JsonToCsv](#csv-and-json-conversion) | | | | | |
 
 **[Http](#http)**
 
@@ -104,9 +105,9 @@ These examples reflect the current implementation. `toCamelCase` preserves inter
 
 | Function | Key conversion | Example input | Example output |
 | :--- | :--- | :--- | :--- |
-| `toViewMapper` | Convert keys to camel case and `_id` to `id` recursively | `{ _id: 'abc123', user_name: 'prasad', address_info: { city_name: 'hyderabad' } }` | `{ id: 'abc123', userName: 'prasad', addressInfo: { cityName: 'hyderabad' } }` |
-| `toEntityMapper` | Convert keys to snake case recursively; preserve `id` | `{ id: 'abc123', userName: 'prasad', addressInfo: { cityName: 'hyderabad' } }` | `{ id: 'abc123', user_name: 'prasad', address_info: { city_name: 'hyderabad' } }` |
-| `toSchemaMapper` | Convert top-level `id` to `_id` and keys to snake case; nested values use `toEntityMapper` | `{ id: 'abc123', userName: 'prasad', addressInfo: { cityName: 'hyderabad' } }` | `{ _id: 'abc123', user_name: 'prasad', address_info: { city_name: 'hyderabad' } }` |
+| `toViewMapper` | Convert keys to camel case and `_id` to `id` recursively | `{ _id: 'abc123', user_name: 'k7m2x9', address_info: { city_name: 'hyderabad' } }` | `{ id: 'abc123', userName: 'k7m2x9', addressInfo: { cityName: 'hyderabad' } }` |
+| `toEntityMapper` | Convert keys to snake case recursively; preserve `id` | `{ id: 'abc123', userName: 'k7m2x9', addressInfo: { cityName: 'hyderabad' } }` | `{ id: 'abc123', user_name: 'k7m2x9', address_info: { city_name: 'hyderabad' } }` |
+| `toSchemaMapper` | Convert top-level `id` to `_id` and keys to snake case; nested values use `toEntityMapper` | `{ id: 'abc123', userName: 'k7m2x9', addressInfo: { cityName: 'hyderabad' } }` | `{ _id: 'abc123', user_name: 'k7m2x9', address_info: { city_name: 'hyderabad' } }` |
 
 All three preserve language maps whose keys are recognized language codes. Primitive and non-plain-object values are returned unchanged. `toViewMapper` and `toEntityMapper` process array items recursively; `toSchemaMapper` uses `toEntityMapper` for array items, so their `id` keys remain `id`.
 
@@ -300,6 +301,67 @@ QueryCond output: [
 ]
 ```
 
+### CSV and JSON conversion
+
+`CsvToJson` and `JsonToCsv` convert between CSV text and JSON objects. The delimiter is optional and defaults to `,`. Fields that contain the delimiter, double quotes, or line breaks are quoted; quotes inside a field are escaped by doubling (`""`), following RFC 4180.
+
+```typescript
+import { CsvToJson, JsonToCsv } from 'dff-util';
+
+const rows = CsvToJson('name,note\n"Doe, John","He said ""hello"""');
+// [{ name: 'Doe, John', note: 'He said "hello"' }]
+
+const csv = JsonToCsv([
+  { name: 'Doe, John', note: 'He said "hello"' },
+  { name: 'k7m2x9', city: 'Hyderabad' },
+]);
+// name,note,city
+// "Doe, John","He said ""hello""",
+// k7m2x9,,Hyderabad
+
+const tsv = JsonToCsv([{ name: 'k7m2x9', city: 'Hyderabad' }], '\t');
+const fromTsv = CsvToJson(tsv, '\t');
+
+const multiline = CsvToJson(`name,bio
+k7m2x9,"line1
+line2"
+n4t9pw,"a
+b
+c"`);
+// [
+//   { name: 'k7m2x9', bio: 'line1\nline2' },
+//   { name: 'n4t9pw', bio: 'a\nb\nc' },
+// ]
+
+JsonToCsv([
+  { name: 'k7m2x9', note: 'line1\nline2' },
+  { name: 'n4t9pw', note: 'hello\r\nworld' },
+]);
+// name,note
+// k7m2x9,"line1
+// line2"
+// n4t9pw,"hello
+// world"
+```
+
+| Function | Arguments | Result |
+| :--- | :--- | :--- |
+| `CsvToJson` | `csv, delimiter = ','` | Array of objects; header row becomes keys |
+| `JsonToCsv` | `data, delimiter = ','` | CSV text with a header row |
+
+`JsonToCsv` accepts an object, an array of objects, or a JSON string of either. Nested objects and arrays are written with `JSON.stringify`. An empty array, `null`, or `undefined` input returns `''`. `CsvToJson` also accepts `null` or `undefined` and returns `[]`. Blank lines are skipped when they cannot be a data row. A leading BOM is stripped. `\n` and `\r\n` are accepted. Unterminated quoted fields throw.
+
+Every header still becomes a property on each row. `null` and `undefined` write as empty cells; an empty cell parses as `null`.
+
+| JSON value | CSV cell | Parsed value |
+| :--- | :--- | :--- |
+| `null` | empty cell | `null` |
+| `undefined` | empty cell | `null` |
+| missing key | empty cell | `null` |
+| `''` | `""` | `''` |
+
+The delimiter may be any non-empty string except a quote or line break, including `;`, `\t`, or `||`.
+
 ## Http
 
 ### HTTP requests
@@ -500,22 +562,20 @@ const fileBlob = await Http.Get(
 
 ## Call Api
 
-These helpers are defined in `src/main/api-call.ts` and exported from `dff-util`. All three use synchronous `XMLHttpRequest`: they return values directly and throw errors synchronously. No `await` is needed. Browser XHR support and server CORS permission are required; requests block while waiting.
+These helpers are defined in `src/main/api-call.ts` and exported from `dff-util`. All three use `fetch` and return Promises. Use `await` (or `.then`) in an async function or a module that supports top-level await. A runtime with `fetch` is required (browsers and Node.js 18+). In the browser, the remote service must permit your origin through CORS.
 
 The former names `Hbs`, `LangText`, and `CurrencyConvert` are now `CallHbs`, `CallLangText`, and `CallCurrencyConvert`. Import them from `dff-util` or `main/api-call` instead of `main/util`.
 
 ### Handlebars rendering (CallHbs)
 
-`CallHbs` renders inline templates through `https://hbs.rndpro.in`, using the same request format as the HBS service. It uses synchronous `XMLHttpRequest` and sends the template and data to that service. It returns directly, without a Promise. Standard Node.js does not provide `XMLHttpRequest`.
-
-Synchronous requests block the browser while waiting and are deprecated on the main thread. The service must permit your browser origin and JSON POST requests through CORS. See [synchronous XHR limitations](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Synchronous_and_Asynchronous_Requests).
+`CallHbs` renders inline templates through `https://hbs.rndpro.in`, using the same request format as the HBS service. It POSTs JSON `{ template, data }` with `Content-Type: application/json` and returns a Promise. The service must permit your origin and JSON POST requests through CORS.
 
 | Call | Endpoint | Return type |
 | :--- | :--- | :--- |
-| `CallHbs(template, data)` | `POST /render` | `string` |
-| `CallHbs(template, items, true)` | `POST /multi` | `string[]` |
+| `await CallHbs(template, data)` | `POST /render` | `Promise<string>` |
+| `await CallHbs(template, items, true)` | `POST /multi` | `Promise<string[]>` |
 
-The TypeScript return type is `string | string[]`; the table shows the result for each mode.
+The TypeScript return type is `Promise<string | string[]>`; the table shows the result for each mode.
 
 #### Supported inputs and rendering modes
 
@@ -524,12 +584,13 @@ Based on the `dff-hbs` service in the local `hbs` repository (`src/models.rs`, `
 | Input or mode | Type | Behavior / example |
 | :--- | :--- | :--- |
 | `template` | `string` | Inline Handlebars text, such as `Hello, {{name}}!`; not a registered template name |
-| `data` with `multi = false` (default) | `RequestBodyType` | One object used as the template context: `{ name: 'Prasad' }` |
+| `data` with `multi = false` (default) | `RequestBodyType` | One object used as the template context: `{ name: 'k7m2x9' }` |
 | `data` with `multi = false` | `RequestBodyType[]` | One array context; iterate using `{{#each this}}{{name}}{{/each}}` |
 | `data` with `multi = true` | `RequestBodyType[]` | Render the same template for each object in one `/multi` request |
-| Object property values | JSON string, number, boolean, null, object, or array | Nested data is supported, for example `{ user: { name: 'Prasad' }, active: true }` |
+| Object property values | JSON string, number, boolean, null, object, or array | Nested data is supported, for example `{ user: { name: 'k7m2x9' }, active: true }` |
 | Single result | `string` | Rendered text from `/render` |
 | Batch result | `string[]` | Rendered strings in input order from `/multi`; an empty array returns `[]` |
+| `data` is `null`/`undefined` | no request | Returns `template` unchanged; `[template]` when `multi = true` |
 
 #### Template helper reference
 
@@ -574,74 +635,74 @@ Quote examples show the helper value before any HTML escaping. The registered he
 ```typescript
 import { CallHbs } from 'dff-util';
 
-const rendered = CallHbs('Hello, {{to_pascal_case name}}!', {
-  name: 'prasad',
+const rendered = await CallHbs('Hello, {{to_pascal_case name}}!', {
+  name: 'k7m2x9',
 });
-console.log(rendered); // Hello, Prasad!
+console.log(rendered); // Hello, K7m2x9!
 ```
 
 #### Render multiple data items in one request
 
 ```typescript
-const rendered = CallHbs(
+const rendered = await CallHbs(
   'Hello, {{to_pascal_case name}}!',
-  [{ name: 'prasad' }, { name: 'monika' }],
+  [{ name: 'k7m2x9' }, { name: 'n4t9pw' }],
   true,
 );
-console.log(rendered); // ['Hello, Prasad!', 'Hello, Monika!']
+console.log(rendered); // ['Hello, K7m2x9!', 'Hello, N4t9pw!']
 ```
 
 The third argument defaults to `false`. Set it to `true` to render the same template once per array item, preserving order. An empty batch returns `[]`. With `false`, an array is treated as a single template context, for example with `{{#each this}}`.
 
-Both endpoints receive JSON in the form `{ template, data }`. Templates can use the string helpers and `switch` helper registered by HBS. Data must be a JSON object or an array of JSON objects; batch rendering requires an array of objects. Empty templates are allowed. Omitting `multi` is equivalent to passing `false`.
+Both endpoints receive JSON in the form `{ template, data }`. Templates can use the string helpers and `switch` helper registered by HBS. Data must be a JSON object or an array of JSON objects; batch rendering requires an array of objects. If `data` is `null` or `undefined`, no request is made and the template is returned unchanged, or as `[template]` when `multi = true`. Empty templates are allowed. Omitting `multi` is equivalent to passing `false`.
 
 #### Handle failures
 
 ```typescript
 try {
-  const result = CallHbs('Hello, {{name}}!', { name: 'Prasad' });
+  const result = await CallHbs('Hello, {{name}}!', { name: 'k7m2x9' });
   console.log(result);
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);
 }
 ```
 
-Non-success HTTP responses throw an error containing the status and response text. The service returns `400` for invalid requests and `500` for rendering failures; a failing batch reports the item index and rejects the entire batch. Network, CORS, and JSON-parsing errors propagate to the caller. Successful batch responses are checked to ensure they contain an array of strings.
+Non-success HTTP responses reject with an error containing the status and response text. The service returns `400` for invalid requests and `500` for rendering failures; a failing batch reports the item index and rejects the entire batch. Network, CORS, and JSON-parsing errors propagate to the caller. Successful batch responses are checked to ensure they contain an array of strings.
 
 ### Language translation (CallLangText)
 
-`CallLangText(text, sourceLocale, targetLocale)` returns the translated text as a `string`.
+`CallLangText(text, sourceLocale, targetLocale)` returns a Promise that resolves to the translated text as a `string`.
 
 ```typescript
 import { CallLangText } from 'dff-util';
 
 try {
-  const translated = CallLangText('Hello, how are you?', 'en-US', 'te-IN');
+  const translated = await CallLangText('Hello, how are you?', 'en-US', 'te-IN');
   console.log(translated);
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);
 }
 ```
 
-Uses `https://lingva.ml/api/v1`, taking the two-letter language prefix from each locale. Text is URL-encoded. Empty inputs, invalid language codes, unsuccessful HTTP responses, and service-reported errors throw.
+Uses `https://lingva.ml/api/v1`, taking the two-letter language prefix from each locale. Text is URL-encoded. Empty inputs, invalid language codes, unsuccessful HTTP responses, and service-reported errors reject.
 
 ### Currency conversion (CallCurrencyConvert)
 
-`CallCurrencyConvert(fromCurrency, toCurrency)` returns the exchange rate as a `number`: the target-currency value of one source-currency unit.
+`CallCurrencyConvert(fromCurrency, toCurrency)` returns a Promise that resolves to the exchange rate as a `number`: the target-currency value of one source-currency unit.
 
 ```typescript
 import { CallCurrencyConvert } from 'dff-util';
 
 try {
-  const rate = CallCurrencyConvert('INR', 'USD');
+  const rate = await CallCurrencyConvert('INR', 'USD');
   console.log(rate);
-  console.log(CallCurrencyConvert('USD', 'USD')); // 1; no HTTP request
+  console.log(await CallCurrencyConvert('USD', 'USD')); // 1; no HTTP request
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);
 }
 ```
 
-Uses `https://api.frankfurter.dev/v1/latest`. Missing inputs, unsuccessful HTTP responses, and missing or nonnumeric rates throw. Network and JSON-parsing errors propagate to the caller.
+Uses `https://api.frankfurter.dev/v1/latest`. Missing inputs, unsuccessful HTTP responses, and missing or nonnumeric rates reject. Network and JSON-parsing errors propagate to the caller.
 
 ## Tokens and encryption
 

package/dist/main/api-call.d.ts

@@ -1,6 +1,6 @@
 import { RequestBodyType } from './const-type';
 /** Render an inline Handlebars template using the hosted HBS service. */
-export declare function CallHbs(template: string, data: RequestBodyType | RequestBodyType[], multi?: boolean): string | string[];
-export declare const CallLangText: (data: string, source: string, target: string) => string;
+export declare function CallHbs(template: string, data: RequestBodyType | RequestBodyType[] | null | undefined, multi?: boolean): Promise<string | string[]>;
+export declare const CallLangText: (data: string, source: string, target: string) => Promise<string>;
 /** Return the exchange rate for one unit of the source currency. */
-export declare const CallCurrencyConvert: (from: string, to: string) => number;
+export declare const CallCurrencyConvert: (from: string, to: string) => Promise<number>;

package/dist/main/api-call.js

@@ -1,45 +1,65 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallCurrencyConvert = exports.CallLangText = void 0;
 exports.CallHbs = CallHbs;
-// All API calls are synchronous and require XMLHttpRequest support.
 function requestText(url, label, body) {
-    if (typeof XMLHttpRequest === 'undefined') {
-        throw new Error(`${label} requires a browser with synchronous XMLHttpRequest support`);
-    }
-    const request = new XMLHttpRequest();
-    request.open(body === undefined ? 'GET' : 'POST', url, false);
-    if (body !== undefined)
-        request.setRequestHeader('Content-Type', 'application/json');
-    request.send(body === undefined ? null : JSON.stringify(body));
-    if (request.status < 200 || request.status >= 300) {
-        const message = request.responseText;
-        throw new Error(`${label} failed: ${request.status} ${request.statusText}${message ? `: ${message}` : ''}`);
-    }
-    return request.responseText;
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof fetch === 'undefined') {
+            throw new Error(`${label} requires a runtime with fetch support`);
+        }
+        const init = body === undefined
+            ? { method: 'GET' }
+            : {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            };
+        const response = yield fetch(url, init);
+        const text = yield response.text();
+        if (!response.ok) {
+            throw new Error(`${label} failed: ${response.status} ${response.statusText}${text ? `: ${text}` : ''}`);
+        }
+        return text;
+    });
 }
 /** Render an inline Handlebars template using the hosted HBS service. */
-function CallHbs(template, data, multi = false) {
-    if (typeof template !== 'string' || data === undefined) {
-        throw new Error('Invalid input: template must be a string and data is required');
-    }
-    const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-    if (!(Array.isArray(data) ? data.every(isObject) : isObject(data))) {
-        throw new Error('Invalid input: data must be a JSON object or an array of JSON objects');
-    }
-    if (multi && !Array.isArray(data)) {
-        throw new Error('Invalid input: data must be an array for multi rendering');
-    }
-    const text = requestText(`https://hbs.rndpro.in/${multi ? 'multi' : 'render'}`, 'HBS rendering', { template, data });
-    if (!multi)
-        return text;
-    const rendered = JSON.parse(text);
-    if (!Array.isArray(rendered) || !rendered.every((item) => typeof item === 'string')) {
-        throw new Error('Invalid HBS response: expected an array of strings');
-    }
-    return rendered;
+function CallHbs(template_1, data_1) {
+    return __awaiter(this, arguments, void 0, function* (template, data, multi = false) {
+        if (typeof template !== 'string') {
+            throw new Error('Invalid input: template must be a string');
+        }
+        // With no data, no request is made: return the template unchanged,
+        // or a single-item array when rendering in multi mode.
+        if (data === null || data === undefined) {
+            return multi ? [template] : template;
+        }
+        const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+        if (!(Array.isArray(data) ? data.every(isObject) : isObject(data))) {
+            throw new Error('Invalid input: data must be a JSON object or an array of JSON objects');
+        }
+        if (multi && !Array.isArray(data)) {
+            throw new Error('Invalid input: data must be an array for multi rendering');
+        }
+        const text = yield requestText(`https://hbs.rndpro.in/${multi ? 'multi' : 'render'}`, 'HBS rendering', { template, data });
+        if (!multi)
+            return text;
+        const rendered = JSON.parse(text);
+        if (!Array.isArray(rendered) || !rendered.every((item) => typeof item === 'string')) {
+            throw new Error('Invalid HBS response: expected an array of strings');
+        }
+        return rendered;
+    });
 }
-const CallLangText = (data, source, target) => {
+const CallLangText = (data, source, target) => __awaiter(void 0, void 0, void 0, function* () {
     if (!data || !source || !target) {
         throw new Error('Invalid input: data, source, or target is missing');
     }
@@ -50,7 +70,7 @@ const CallLangText = (data, source, target) => {
     }
     const encodedData = encodeURIComponent(data);
     const url = `https://lingva.ml/api/v1/${src}/${tgt}/${encodedData}`;
-    const json = JSON.parse(requestText(url, 'Translation'));
+    const json = JSON.parse(yield requestText(url, 'Translation'));
     if (json.error) {
         throw new Error(`API error: ${json.error}`);
     }
@@ -58,10 +78,10 @@ const CallLangText = (data, source, target) => {
         throw new Error('Invalid translation response: expected a string');
     }
     return json.translation || '';
-};
+});
 exports.CallLangText = CallLangText;
 /** Return the exchange rate for one unit of the source currency. */
-const CallCurrencyConvert = (from, to) => {
+const CallCurrencyConvert = (from, to) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     if (!from || !to) {
         throw new Error('Invalid input: from or to is missing');
@@ -69,11 +89,11 @@ const CallCurrencyConvert = (from, to) => {
     if (from === to)
         return 1;
     const url = `https://api.frankfurter.dev/v1/latest?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`;
-    const json = JSON.parse(requestText(url, 'Currency conversion'));
+    const json = JSON.parse(yield requestText(url, 'Currency conversion'));
     const rate = (_a = json.rates) === null || _a === void 0 ? void 0 : _a[to];
     if (typeof rate !== 'number' || !Number.isFinite(rate)) {
         throw new Error('Invalid currency response: expected a numeric exchange rate');
     }
     return rate;
-};
+});
 exports.CallCurrencyConvert = CallCurrencyConvert;

package/dist/main/csv.d.ts

@@ -0,0 +1,5 @@
+export type CsvCell = string | null;
+/** Parse CSV text into an array of objects. The first row is used as header keys. */
+export declare function CsvToJson(csv: string | null | undefined, delimiter?: string): Record<string, CsvCell>[];
+/** Serialize JSON objects as CSV text. Nested objects and arrays are JSON-stringified. */
+export declare function JsonToCsv(data: string | Record<string, unknown> | Record<string, unknown>[] | null | undefined, delimiter?: string): string;

package/dist/main/csv.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsvToJson = CsvToJson;
+exports.JsonToCsv = JsonToCsv;
+function normalizeDelimiter(delimiter) {
+    if (typeof delimiter !== 'string' || delimiter.length === 0) {
+        throw new Error('Invalid input: delimiter must be a non-empty string');
+    }
+    if (delimiter.includes('"') || delimiter.includes('\n') || delimiter.includes('\r')) {
+        throw new Error('Invalid input: delimiter cannot contain quotes or line breaks');
+    }
+    return delimiter;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function needsQuotes(value, delimiter) {
+    return (value === '' ||
+        value.includes('"') ||
+        value.includes('\n') ||
+        value.includes('\r') ||
+        value.includes(delimiter));
+}
+function encodeField(value, delimiter) {
+    if (needsQuotes(value, delimiter)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function encodeValue(value, delimiter) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return encodeField(value, delimiter);
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (value instanceof Date)
+        return encodeField(value.toISOString(), delimiter);
+    if (typeof value === 'object')
+        return encodeField(JSON.stringify(value), delimiter);
+    return encodeField(String(value), delimiter);
+}
+function decodeCell(field) {
+    if (!field)
+        return null;
+    if (field.quoted)
+        return field.value;
+    if (field.value === '')
+        return null;
+    return field.value;
+}
+function parseCsvRows(input, delimiter) {
+    if (input.charCodeAt(0) === 0xfeff)
+        input = input.slice(1);
+    if (input.length === 0)
+        return [];
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let inQuotes = false;
+    const dLen = delimiter.length;
+    const pushField = () => {
+        row.push({ value: field, quoted });
+        field = '';
+        quoted = false;
+    };
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (input[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += ch;
+            }
+            continue;
+        }
+        if (ch === '"' && field === '') {
+            inQuotes = true;
+            quoted = true;
+            continue;
+        }
+        if (input.startsWith(delimiter, i)) {
+            pushField();
+            i += dLen - 1;
+            continue;
+        }
+        if (ch === '\n' || ch === '\r') {
+            pushField();
+            rows.push(row);
+            row = [];
+            if (ch === '\r' && input[i + 1] === '\n')
+                i++;
+            continue;
+        }
+        field += ch;
+    }
+    if (inQuotes) {
+        throw new Error('Invalid CSV: unterminated quoted field');
+    }
+    if (!(input.endsWith('\n') || input.endsWith('\r'))) {
+        pushField();
+        rows.push(row);
+    }
+    return rows;
+}
+function isBlankLine(row, columnCount) {
+    return row.length === 1 && row[0].value === '' && !row[0].quoted && columnCount > 1;
+}
+function isEmptyRow(row) {
+    return row.every((cell) => cell.value === '' && !cell.quoted);
+}
+/** Parse CSV text into an array of objects. The first row is used as header keys. */
+function CsvToJson(csv, delimiter = ',') {
+    if (csv === null || csv === undefined)
+        return [];
+    if (typeof csv !== 'string') {
+        throw new Error('Invalid input: csv must be a string');
+    }
+    const rows = parseCsvRows(csv, normalizeDelimiter(delimiter));
+    if (rows.length === 0 || (rows.length === 1 && isEmptyRow(rows[0])))
+        return [];
+    const headers = rows[0].map((cell) => cell.value);
+    const records = [];
+    for (let r = 1; r < rows.length; r++) {
+        const row = rows[r];
+        if (isBlankLine(row, headers.length))
+            continue;
+        const record = {};
+        for (let c = 0; c < headers.length; c++) {
+            const key = headers[c];
+            if (key === '')
+                continue;
+            record[key] = decodeCell(row[c]);
+        }
+        records.push(record);
+    }
+    return records;
+}
+/** Serialize JSON objects as CSV text. Nested objects and arrays are JSON-stringified. */
+function JsonToCsv(data, delimiter = ',') {
+    const delim = normalizeDelimiter(delimiter);
+    let records = data;
+    if (typeof records === 'string') {
+        if (records.trim() === '')
+            return '';
+        try {
+            records = JSON.parse(records);
+        }
+        catch (_a) {
+            throw new Error('Invalid input: data must be valid JSON');
+        }
+    }
+    if (records === null || records === undefined)
+        return '';
+    if (!Array.isArray(records)) {
+        if (!isPlainObject(records)) {
+            throw new Error('Invalid input: data must be an object or an array of objects');
+        }
+        records = [records];
+    }
+    const rows = records;
+    if (rows.length === 0)
+        return '';
+    if (!rows.every((row) => row === null || row === undefined || isPlainObject(row))) {
+        throw new Error('Invalid input: data must be an object or an array of objects');
+    }
+    const keys = [];
+    const seen = new Set();
+    for (const record of rows) {
+        if (!isPlainObject(record))
+            continue;
+        for (const key of Object.keys(record)) {
+            if (!seen.has(key)) {
+                seen.add(key);
+                keys.push(key);
+            }
+        }
+    }
+    if (keys.length === 0)
+        return '';
+    const lines = [keys.map((key) => encodeField(key, delim)).join(delim)];
+    for (const record of rows) {
+        if (record === null || record === undefined) {
+            lines.push(keys.map(() => '').join(delim));
+            continue;
+        }
+        const obj = record;
+        lines.push(keys.map((key) => encodeValue(obj[key], delim)).join(delim));
+    }
+    return lines.join('\n');
+}

package/dist/main/util.d.ts

@@ -19,3 +19,4 @@ export declare function DecodeURL(input: string): string;
 export declare function SafeEncode(input: string): string;
 export declare function SafeDecode(encoded: string): string;
 export { QueryCond, type QueryCondItem } from './query-cond';
+export { CsvToJson, JsonToCsv, type CsvCell } from './csv';

package/dist/main/util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryCond = exports.LangCountryCode = exports.TimeAgo = exports.DateAndTime = exports.DateTime12HrFormat = exports.DateTime24HrFormat = exports.TruncateText = exports.AppUUID4 = exports.AppAddDays = exports.AppDaysBack = exports.AppCode = exports.AppCodeByType = exports.AppUniqueCode = exports.AppRandomString = void 0;
+exports.JsonToCsv = exports.CsvToJson = exports.QueryCond = exports.LangCountryCode = exports.TimeAgo = exports.DateAndTime = exports.DateTime12HrFormat = exports.DateTime24HrFormat = exports.TruncateText = exports.AppUUID4 = exports.AppAddDays = exports.AppDaysBack = exports.AppCode = exports.AppCodeByType = exports.AppUniqueCode = exports.AppRandomString = void 0;
 exports.EncodeBase64 = EncodeBase64;
 exports.DecodeBase64 = DecodeBase64;
 exports.EncodeURL = EncodeURL;
@@ -197,3 +197,6 @@ function SafeDecode(encoded) {
 }
 var query_cond_1 = require("./query-cond");
 Object.defineProperty(exports, "QueryCond", { enumerable: true, get: function () { return query_cond_1.QueryCond; } });
+var csv_1 = require("./csv");
+Object.defineProperty(exports, "CsvToJson", { enumerable: true, get: function () { return csv_1.CsvToJson; } });
+Object.defineProperty(exports, "JsonToCsv", { enumerable: true, get: function () { return csv_1.JsonToCsv; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dff-util",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {