@jd-data-limited/easy-fm 5.0.0-beta.2 → 5.0.0-beta.4

package/dist/typegen/dependencies.js

@@ -0,0 +1,67 @@
+import { access, readFile } from 'node:fs/promises';
+import { dirname, parse, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+const ZOD_VERSION = '^4.6.5';
+/** Ensures generated code can resolve its direct `zod` import. */
+export async function ensureZodInstalled(start) {
+    const plan = await getZodInstallPlan(start);
+    if (!plan)
+        return false;
+    await runInstall(plan);
+    return true;
+}
+/** Returns null when Zod is already declared. Exported for alternate CLIs. */
+export async function getZodInstallPlan(start) {
+    const packagePath = await findUp(resolve(start), 'package.json');
+    if (!packagePath)
+        throw new Error(`Cannot install Zod: no package.json found above ${resolve(start)}`);
+    const manifest = JSON.parse(await readFile(packagePath, 'utf8'));
+    const dependencyGroups = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+    if (dependencyGroups.some(group => hasDependency(manifest[group], 'zod')))
+        return null;
+    const cwd = dirname(packagePath);
+    const manager = await detectPackageManager(cwd, manifest.packageManager);
+    return { cwd, command: manager, args: installArguments(manager) };
+}
+function hasDependency(value, name) {
+    return typeof value === 'object' && value !== null && name in value;
+}
+async function detectPackageManager(cwd, declared) {
+    if (typeof declared === 'string') {
+        const name = declared.split('@')[0];
+        if (name === 'pnpm' || name === 'npm' || name === 'yarn' || name === 'bun')
+            return name;
+    }
+    const locks = [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun'], ['package-lock.json', 'npm']];
+    for (const [file, manager] of locks)
+        if (await findUp(cwd, file))
+            return manager;
+    return 'npm';
+}
+function installArguments(manager) {
+    if (manager === 'npm')
+        return ['install', `zod@${ZOD_VERSION}`];
+    return ['add', `zod@${ZOD_VERSION}`];
+}
+async function runInstall({ cwd, command, args }) {
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+        child.once('error', reject);
+        child.once('exit', code => code === 0 ? resolvePromise() : reject(new Error(`${command} ${args.join(' ')} exited with code ${code ?? 'unknown'}`)));
+    });
+}
+async function findUp(start, name) {
+    let directory = start;
+    while (true) {
+        const candidate = resolve(directory, name);
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch { }
+        const parent = dirname(directory);
+        if (parent === directory || directory === parse(directory).root)
+            return undefined;
+        directory = parent;
+    }
+}

package/dist/typegen/generate.d.ts

@@ -0,0 +1,5 @@
+import type { TypegenConfig } from './types.js';
+export declare function generate(config: TypegenConfig): Promise<{
+    output: string;
+    layouts: number;
+}>;

package/dist/typegen/generate.js

@@ -0,0 +1,85 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { zodTypegenValidator } from './zod.js';
+export async function generate(config) {
+    const discovered = await config.source.introspect();
+    const selected = config.layouts ? discovered.layouts.filter(layout => config.layouts.includes(layout.name)) : discovered.layouts;
+    const missing = config.layouts?.filter(name => !selected.some(layout => layout.name === name)) ?? [];
+    if (missing.length)
+        throw new Error(`Layouts not found: ${missing.join(', ')}`);
+    const schema = { version: 1, layouts: [...selected].sort((a, b) => a.name.localeCompare(b.name)) };
+    const output = resolve(config.output);
+    const temporary = `${output}.tmp-${process.pid}`;
+    await rm(temporary, { recursive: true, force: true });
+    await mkdir(temporary, { recursive: true });
+    await writeFile(resolve(temporary, 'client.ts'), renderClient(schema, config.validator ?? zodTypegenValidator()), 'utf8');
+    await writeFile(resolve(temporary, 'schema.json'), `${JSON.stringify({ ...schema, transports: config.transports ?? ['data-api', 'odata'] }, null, 2)}\n`, 'utf8');
+    await mkdir(dirname(output), { recursive: true });
+    await rm(output, { recursive: true, force: true });
+    await rename(temporary, output);
+    return { output, layouts: schema.layouts.length };
+}
+function renderClient(schema, validator) {
+    const interfaces = schema.layouts.map(renderLayout).join('\n\n');
+    const structure = schema.layouts.map(layout => `${quote(layout.name)}: ${layoutTypeName(layout)}`).join(',\n        ');
+    const validators = schema.layouts.map(layout => `${quote(layout.name)}: {\n        record: ${validator.renderRecord(layout)},\n        metadata: ${renderMetadata(layout)}\n    }`).join(',\n    ');
+    const properties = schema.layouts.map(layout => `${safeProperty(layout.clientName ?? layout.name)}: database.layout<${layoutTypeName(layout)}>(${quote(layout.name)})`).join(',\n        ');
+    return `/* Generated by easyfm typegen. Do not edit. */
+import {Database, withSchemaValidation, ${validator.runtimeValidator}, type DatabaseProvider, type DatabaseStructure, type LayoutInterface, type Portal, type ReadonlyField, type TextField, type NumberField, type DateField, type TimeField, type TimeStampField, type ContainerField} from '@jd-data-limited/easy-fm'
+${validator.imports.join('\n')}
+
+${interfaces}
+
+export interface GeneratedDatabase extends DatabaseStructure {
+    layouts: {
+        ${structure}
+    }
+}
+
+export const easyFMSchema = {
+    validator: ${validator.runtimeValidator},
+    layouts: {
+        ${validators}
+    }
+} satisfies Parameters<typeof withSchemaValidation>[1]
+
+export function createEasyFMClient (provider: DatabaseProvider) {
+    const database = Database.create<GeneratedDatabase>({provider: withSchemaValidation(provider, easyFMSchema)})
+    return {
+        database,
+        ${properties}
+    }
+}
+`;
+}
+function renderLayout(layout) {
+    const fields = layout.fields.map(field => `${quote(field.name)}: ${fieldType(field)}`).join('\n        ');
+    const portals = Object.entries(layout.portals).map(([name, portalFields]) => `${quote(name)}: Portal<{\n            ${portalFields.map(field => `${quote(field.name)}: ${fieldType(field)}`).join('\n            ')}\n        }>`).join('\n        ');
+    return `export interface ${layoutTypeName(layout)} extends LayoutInterface {
+    fields: {
+        ${fields}
+    }
+    portals: {
+        ${portals}
+    }
+}`;
+}
+function fieldType(field) {
+    const type = { text: 'TextField', number: 'NumberField', date: 'DateField', time: 'TimeField', timeStamp: 'TimeStampField', container: 'ContainerField' }[field.result];
+    return field.writable ? type : `ReadonlyField<${type}>`;
+}
+function renderMetadata(layout) {
+    const fields = renderMetadataFields(layout.fields);
+    const portals = Object.entries(layout.portals).map(([name, portalFields]) => `${quote(name)}: ${renderMetadataFields(portalFields)}`).join(', ');
+    return `{fields: ${fields}, portals: {${portals}}}`;
+}
+function renderMetadataFields(fields) {
+    return `{${fields.map(field => `${quote(field.name)}: {result: ${quote(field.result)}, type: ${quote(field.type)}}`).join(', ')}}`;
+}
+function layoutTypeName(layout) { return `${identifier(layout.clientName ?? layout.name, 'Layout')}Layout`; }
+function safeProperty(value) { return identifier(value, 'layout'); }
+function identifier(value, fallback) {
+    const cleaned = value.replace(/[^a-zA-Z0-9_$]/g, '_').replace(/^[^a-zA-Z_$]+/, '');
+    return cleaned || fallback;
+}
+function quote(value) { return JSON.stringify(value); }

package/dist/typegen/index.d.ts

@@ -0,0 +1,6 @@
+export { generate } from './generate.js';
+export { dataApiSchemaSource } from './dataApiSchemaSource.js';
+export { zodTypegenValidator } from './zod.js';
+export { configExists, readEnvironment, writeDataApiInitialization, type DataApiInitAnswers } from './init.js';
+export { ensureZodInstalled, getZodInstallPlan, type InstallPlan } from './dependencies.js';
+export { defineTypegenConfig, type SchemaSource, type TypegenConfig, type TypegenField, type TypegenLayout, type TypegenSchema, type TypegenTransport, type TypegenValidator } from './types.js';

package/dist/typegen/index.js

@@ -0,0 +1,6 @@
+export { generate } from './generate.js';
+export { dataApiSchemaSource } from './dataApiSchemaSource.js';
+export { zodTypegenValidator } from './zod.js';
+export { configExists, readEnvironment, writeDataApiInitialization } from './init.js';
+export { ensureZodInstalled, getZodInstallPlan } from './dependencies.js';
+export { defineTypegenConfig } from './types.js';

package/dist/typegen/init.d.ts

@@ -0,0 +1,13 @@
+export interface DataApiInitAnswers {
+    provider: 'data-api/odata';
+    transports: 'data-api' | 'odata' | 'both';
+    hostname: string;
+    database: string;
+    username: string;
+    password: string;
+    output: string;
+}
+export declare function configExists(path: string): Promise<boolean>;
+/** Non-interactive write step, usable by alternate setup UIs. */
+export declare function writeDataApiInitialization(config: string, answers: DataApiInitAnswers): Promise<void>;
+export declare function readEnvironment(path: string): Promise<Record<string, string>>;

package/dist/typegen/init.js

@@ -0,0 +1,113 @@
+import { mkdir, open, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+export async function configExists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** Non-interactive write step, usable by alternate setup UIs. */
+export async function writeDataApiInitialization(config, answers) {
+    const configPath = resolve(config);
+    const directory = dirname(configPath);
+    const envPath = resolve(directory, '.env');
+    await mkdir(directory, { recursive: true });
+    const file = await open(configPath, 'wx');
+    try {
+        await file.writeFile(renderConfig(answers), 'utf8');
+    }
+    finally {
+        await file.close();
+    }
+    await updateEnvironment(envPath, { FM_HOST: answers.hostname, FM_DATABASE: answers.database, FM_USERNAME: answers.username, FM_PASSWORD: answers.password });
+    await ensureEnvironmentIgnored(directory);
+}
+export async function readEnvironment(path) {
+    try {
+        const contents = await readFile(path, 'utf8');
+        return Object.fromEntries(contents.split(/\r?\n/).map(line => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/)).filter(match => match).map(match => [match[1], decodeEnvironmentValue(match[2])]));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+function renderConfig(answers) {
+    return `import {dataApiSchemaSource, defineTypegenConfig, zodTypegenValidator} from '@jd-data-limited/easy-fm/typegen'
+
+function required (name) {
+    const value = process.env[name]
+    if (!value) throw new Error(\`Missing required environment variable \${name}\`)
+    return value
+}
+
+export default defineTypegenConfig({
+    output: ${JSON.stringify(answers.output)},
+    transports: ${JSON.stringify(answers.transports === 'both' ? ['data-api', 'odata'] : [answers.transports])},
+    validator: zodTypegenValidator(),
+    source: dataApiSchemaSource({
+        hostname: required('FM_HOST'),
+        database: required('FM_DATABASE'),
+        credentials: {method: 'filemaker', username: required('FM_USERNAME'), password: required('FM_PASSWORD')},
+        externalSources: []
+    })
+})
+`;
+}
+async function updateEnvironment(path, values) {
+    let contents = '';
+    try {
+        contents = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lines = contents ? contents.split(/\r?\n/) : [];
+    for (const [name, value] of Object.entries(values)) {
+        const replacement = `${name}=${JSON.stringify(value)}`;
+        const index = lines.findIndex(line => line.startsWith(`${name}=`));
+        if (index >= 0)
+            lines[index] = replacement;
+        else
+            lines.push(replacement);
+    }
+    await writeFile(path, `${lines.filter((line, index) => line || index < lines.length - 1).join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+function decodeEnvironmentValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+}
+async function ensureEnvironmentIgnored(directory) {
+    const path = resolve(directory, '.gitignore');
+    let contents = '';
+    try {
+        contents = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const alreadyIgnored = contents.split(/\r?\n/).some(line => {
+        const rule = line.trim();
+        return rule === '.env' || rule === '/.env' || rule === '.env*' || rule === '/.env*';
+    });
+    if (alreadyIgnored)
+        return;
+    const prefix = contents && !contents.endsWith('\n') ? '\n' : '';
+    await writeFile(path, `${contents}${prefix}.env\n`, 'utf8');
+}

package/dist/typegen/types.d.ts

@@ -0,0 +1,40 @@
+import type { ApiFieldResultTypes, ApiFieldTypes } from '../models/apiResults.js';
+export interface TypegenField {
+    name: string;
+    result: typeof ApiFieldResultTypes[keyof typeof ApiFieldResultTypes];
+    type: typeof ApiFieldTypes[keyof typeof ApiFieldTypes];
+    writable: boolean;
+    required: boolean;
+}
+export interface TypegenLayout {
+    name: string;
+    clientName?: string;
+    fields: TypegenField[];
+    portals: Record<string, TypegenField[]>;
+}
+export interface TypegenSchema {
+    version: 1;
+    layouts: TypegenLayout[];
+}
+export type TypegenTransport = 'data-api' | 'odata';
+export interface SchemaSource {
+    introspect(): Promise<TypegenSchema>;
+}
+/** Code-generation plugin for a runtime validation library. */
+export interface TypegenValidator {
+    readonly imports: readonly string[];
+    readonly runtimeValidator: string;
+    /** Render a validator for the complete canonical ProviderRecord. */
+    renderRecord(layout: TypegenLayout): string;
+}
+export interface TypegenConfig {
+    source: SchemaSource;
+    output: string;
+    /** Placeholder describing intended runtime transports. */
+    transports?: TypegenTransport[];
+    /** Restrict output to these FileMaker layout names. */
+    layouts?: string[];
+    /** Defaults to the built-in strict Zod validator. */
+    validator?: TypegenValidator;
+}
+export declare function defineTypegenConfig(config: TypegenConfig): TypegenConfig;

package/dist/typegen/types.js

@@ -0,0 +1 @@
+export function defineTypegenConfig(config) { return config; }

package/dist/typegen/zod.d.ts

@@ -0,0 +1,3 @@
+import type { TypegenValidator } from './types.js';
+/** Strict Zod generator. Extra, missing, and wrongly typed fields fail validation. */
+export declare function zodTypegenValidator(): TypegenValidator;

package/dist/typegen/zod.js

@@ -0,0 +1,32 @@
+/** Strict Zod generator. Extra, missing, and wrongly typed fields fail validation. */
+export function zodTypegenValidator() {
+    return {
+        imports: ["import {z} from 'zod'"],
+        runtimeValidator: 'zodValidator',
+        renderRecord: renderProviderRecord
+    };
+}
+function renderProviderRecord(layout) {
+    const fieldData = objectSchema(layout.fields);
+    const portals = Object.entries(layout.portals).map(([name, fields]) => `${quote(name)}: z.array(${portalRowSchema(fields)})`).join(', ');
+    const portalData = `z.object({${portals}}).partial().strict().optional()`;
+    return `z.object({recordId: z.string(), modId: z.string(), fieldData: ${fieldData}, portalData: ${portalData}}).strict()`;
+}
+function objectSchema(fields) {
+    return `z.object({${fields.map(field => `${quote(field.name)}: ${fieldSchema(field)}`).join(', ')}}).strict()`;
+}
+function portalRowSchema(fields) {
+    const entries = fields.map(field => `${quote(field.name)}: ${fieldSchema(field)}`);
+    entries.push('recordId: z.union([z.string(), z.number()])', 'modId: z.union([z.string(), z.number()])');
+    return `z.object({${entries.join(', ')}}).strict()`;
+}
+function fieldSchema(field) {
+    if (field.result === 'number')
+        return 'z.number().nullable()';
+    if (field.result === 'date' || field.result === 'time' || field.result === 'timeStamp')
+        return 'z.string().nullable()';
+    if (field.result === 'container')
+        return 'z.string().nullable()';
+    return 'z.string()';
+}
+function quote(value) { return JSON.stringify(value); }

package/package.json

@@ -1,13 +1,27 @@
 {
   "name": "@jd-data-limited/easy-fm",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.4",
   "dependencies": {
+    "chalk": "^5.6.2",
     "commander": "^15.0.0",
+    "inquirer": "^14.2.2",
     "temporal-polyfill": "^1.0.5",
     "zod": "^4.6.5"
   },
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./typegen": {
+      "types": "./dist/typegen/index.d.ts",
+      "import": "./dist/typegen/index.js"
+    }
+  },
   "module": "es2022",
   "homepage": "https://jd-data.com/project/easyfm/",
   "url": "https://github.com/JD-Data-Limited/easy-fm",
@@ -44,6 +58,7 @@
     "@babel/core": "^8.0.6",
     "@babel/preset-env": "^8.0.6",
     "@babel/preset-typescript": "^8.0.1",
+    "@cloudflare/vitest-plugin": "^1.2.2",
     "@types/btoa": "^1.2.5",
     "@types/events": "^3.0.3",
     "@types/inquirer": "^9.0.10",
@@ -57,17 +72,20 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.3.0",
     "eslint-plugin-promise": "^7.3.0",
-    "inquirer": "^14.2.2",
     "jest": "^30.5.2",
     "ts-jest": "^29.4.12",
     "ts-morph": "^28.0.0",
     "tsx": "^4.23.15",
     "typedoc": "^0.28.20",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
   },
   "bin": {
     "easyfm": "dist/bin/cli.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "test": "npm run build && jest",
@@ -75,7 +93,11 @@
     "test:coverage": "jest --coverage --testPathIgnorePatterns='/__tests__/database.test.ts$'",
     "test:integration": "npm run build && jest __tests__/database.test.ts --runInBand",
     "test:unit": "jest __tests__/query.test.ts __tests__/CookieJar.test.ts --runInBand",
+    "test:runtime": "pnpm build && pnpm test:runtime:bun && pnpm test:runtime:deno && pnpm test:runtime:workers",
+    "test:runtime:bun": "bun test ./runtime-tests/bun.test.ts",
+    "test:runtime:deno": "deno test --no-check --allow-read --node-modules-dir=manual ./runtime-tests/deno.test.ts",
+    "test:runtime:workers": "vitest run --config ./runtime-tests/workers/vitest.config.ts",
     "stress:search": "tsx src/bin/stressSearch.ts",
-    "docs:build": "typedoc --options ./docs/theme.json"
+    "docs:build": "typedoc --options ../../docs/theme.json"
   }
 }

package/dist/layouts/recordFieldsMap.d.ts

@@ -1,2 +0,0 @@
-import { type Field, type FieldValue } from '../records/field.js';
-export type RecordFieldsMap = Record<string, Field<FieldValue>>;

package/dist/layouts/recordFieldsMap.js

@@ -1,4 +0,0 @@
-/*
- * Copyright (c) 2023-2024. See LICENSE file for more information
- */
-export {};

package/dist/records/field.d.ts

@@ -1,77 +0,0 @@
-import { RecordTypes } from '../types.js';
-import { type ApiFieldMetadata } from '../models/apiResults.js';
-import { type LayoutBase } from '../layouts/layoutBase.js';
-import { type Moment } from 'moment';
-import { Readable } from 'node:stream';
-import { type z } from 'zod';
-export type FieldValue = string | number | Moment | Container;
-export type Container = null;
-export interface Parentable {
-    layout: LayoutBase;
-    type: RecordTypes;
-    endpoint: string;
-    portal?: {
-        name: string;
-    };
-}
-interface StreamOptions {
-    abortSignal?: AbortSignal;
-}
-/**
- * A class representing a field in a record.
- *
- * @template T - The type of the field value.
- */
-export declare class Field<T extends FieldValue> {
-    #private;
-    parent: Parentable;
-    id: string;
-    protected _value: T | null;
-    static firstContainerDownload: Promise<any> | null;
-    constructor(record: Parentable, id: string, originalContents: T);
-    /** `true` if this field has changed since it was last loaded or saved. */
-    get edited(): boolean;
-    /**
-     * Resets the 'edited' state of this field, without changing its value
-     */
-    updateOriginalContents(): void;
-    /**
-     * Sets the value of the field.
-     *
-     * @param {T | null} content - The new content value to be set. Can be either the type T or null.
-     * @throws {Error} Cannot set container value using set(). Use upload() instead, if the result is a 'container'.
-     */
-    set(content: T | null): void;
-    /** Returns the FileMaker metadata for this field. */
-    get metadata(): z.infer<typeof ApiFieldMetadata>;
-    /** Gets or sets the current field value. */
-    get value(): T | null;
-    set value(value: T);
-    /** Returns this field value as a string. Throws if the value is not a string. */
-    get string(): string;
-    /**
-     * Uploads a file to the container field.
-     *
-     * @param {Buffer} file - The file content as a buffer.
-     *
-     * @throws {Error} - Cannot upload a file to the field if it's not a container field.
-     * @throws {Error} - Upload failed with HTTP error.
-     *
-     * @returns {Promise<void>} - A promise that resolves when the file is successfully uploaded.
-     */
-    upload(file: File): Promise<void>;
-    stream(): Promise<{
-        data: Readable;
-        mime: string;
-    }>;
-    /**
-     * Returns the container download as a Web `Response`.
-     */
-    webStream(options: StreamOptions): Promise<Response>;
-    /** Downloads the full container contents into memory. */
-    arrayBuffer(): Promise<{
-        data: ArrayBuffer;
-        mime: string;
-    }>;
-}
-export {};