@kollors/deep-json-server 0.6.0 → 0.7.0

package/types/src/config.d.ts

@@ -11,7 +11,7 @@ export type DatabaseConfig = {
 };
 export type MemoryFile = {
     content: Uint8Array;
-    id: string;
+    directory?: string;
     mimeType: string;
     name: string;
 };
@@ -24,6 +24,16 @@ export type FilesConfig = {
     directory: string;
     metadata: string;
 };
+export type OpenapiConfig = {
+    path?: string;
+};
+export type ServerConfig = {
+    host?: string;
+    logger?: boolean | Record<string, unknown>;
+    maxFileSize?: number;
+    maxPageSize?: number;
+    port?: number;
+};
 export type DeepJsonServerConfig = {
     /**
      * Database source and optional schema.
@@ -36,51 +46,28 @@ export type DeepJsonServerConfig = {
     /**
      * Generated OpenAPI file.
      */
-    openapi?: {
-        path?: string;
-    };
+    openapi?: OpenapiConfig;
     /**
      * Runtime settings.
      */
-    server?: {
-        host?: string;
-        logger?: boolean | Record<string, unknown>;
-        maxFileSize?: number;
-        maxPageSize?: number;
-        port?: number;
-    };
+    server?: ServerConfig;
+};
+export type NormalizedServerConfig = {
+    database: DatabaseConfig;
+    files?: FilesConfig;
+    openapi: OpenapiConfig;
+    server: ServerConfig;
 };
 /**
+ * Validates configuration and resolves relative paths.
  * @param {DeepJsonServerConfig} config Server configuration.
  * @param {string} [directoryPath] Base directory for relative paths.
- * @returns {{ database: DatabaseConfig, files?: FilesConfig, openapi: { path?: string }, server: { host?: string, logger?: boolean | Record<string, unknown>, maxFileSize?: number, maxPageSize?: number, port?: number } }} Normalized configuration.
+ * @returns {NormalizedServerConfig} Normalized configuration.
  */
-export declare const normalizeServerConfig: (config: DeepJsonServerConfig, directoryPath?: string) => {
-    database: DatabaseConfig;
-    files?: FilesConfig;
-    openapi: {
-        path?: string;
-    };
-    server: {
-        host?: string;
-        logger?: boolean | Record<string, unknown>;
-        maxFileSize?: number;
-        maxPageSize?: number;
-        port?: number;
-    };
-};
-/** @param {string} configPath Configuration module path. */
-export declare function readServerConfig(configPath: string): Promise<{
-    database: DatabaseConfig;
-    files?: FilesConfig;
-    openapi: {
-        path?: string;
-    };
-    server: {
-        host?: string;
-        logger?: boolean | Record<string, unknown>;
-        maxFileSize?: number;
-        maxPageSize?: number;
-        port?: number;
-    };
-}>;
+export declare const normalizeServerConfig: (config: DeepJsonServerConfig, directoryPath?: string) => NormalizedServerConfig;
+/**
+ * Loads an ES module config and resolves paths from its directory.
+ * @param {string} configPath Configuration module path.
+ * @returns {Promise<NormalizedServerConfig>} Normalized configuration.
+ */
+export declare function readServerConfig(configPath: string): Promise<NormalizedServerConfig>;

package/types/src/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const DEFAULT_HOST = "127.0.0.1";
 export declare const DEFAULT_MAX_FILE_SIZE: number;
+export declare const DEFAULT_MAX_PAGE_SIZE = 1000;
 export declare const DEFAULT_PAGE_SIZE = 10;
 export declare const DEFAULT_PORT = 4001;
-export declare const MAX_PAGE_SIZE = 1000;

package/types/src/database.d.ts

@@ -1,11 +1,33 @@
+export type DatabaseContainer = {
+    data: import('./config.js').DatabaseData;
+};
+export type DatabaseStore = {
+    /**
+     * Current database container.
+     */
+    database: DatabaseContainer;
+    /**
+     * Resolved database file path.
+     */
+    path?: string;
+    /**
+     * Returns current data and reloads disk-backed sources.
+     */
+    read: () => Promise<import('./config.js').DatabaseData>;
+    /**
+     * Runs a serialized update.
+     */
+    update: <T>(operation: (database: DatabaseContainer) => T) => Promise<T>;
+};
 export declare const validateDatabase: (data: any) => any;
 export declare const readJsonObject: (path: any, label: any) => Promise<any>;
 export declare const readDatabaseFile: (databasePath: any) => Promise<any>;
 /**
+ * Creates a disk- or memory-backed database with serialized updates.
  * @param {import('./config.js').DatabaseConfig} config Database source.
- * @returns {Promise<any>} Internal database store.
+ * @returns {Promise<DatabaseStore>} Database store.
  */
-export declare const createDatabaseStore: (config: import('./config.js').DatabaseConfig) => Promise<any>;
+export declare const createDatabaseStore: (config: import('./config.js').DatabaseConfig) => Promise<DatabaseStore>;
 export declare const getCollection: (database: any, resource: any) => any[];
 export declare const findItem: (collection: any, id: any) => any;
-export declare const createId: (collection: any) => any;
+export declare const createId: (collection: any) => string;

package/types/src/files.d.ts

@@ -1,24 +1,64 @@
-/** @param {import('./config.js').FilesConfig} config File storage configuration. */
-export declare const createFileStore: (config: import('./config.js').FilesConfig) => Promise<{
-    get: (id: any) => Promise<void>;
-    remove: (id: any) => Promise<void>;
-    upload: ({ maxFileSize, mimeType, name, stream }: {
-        maxFileSize: any;
-        mimeType: any;
-        name: any;
-        stream: any;
-    }) => Promise<void>;
-} | {
-    get: (id: any) => Promise<void>;
-    remove: (id: any) => Promise<void>;
-    upload: ({ maxFileSize, mimeType, name, stream }: {
-        maxFileSize: any;
-        mimeType: any;
-        name: any;
-        stream: any;
-    }) => Promise<void>;
-}>;
-export declare const registerFileRoutes: (server: any, { maxFileSize, store }: {
+import { Readable } from 'node:stream';
+export type StoredFileMetadata = {
+    directory: string;
+    mimeType: string;
+    name: string;
+};
+export type FileRecord = StoredFileMetadata & {
+    size: number;
+};
+export type FileMetadata = FileRecord & {
+    downloadUrl: string;
+    metadataUrl: string;
+    url: string;
+};
+export type FileUpload = {
+    directory: string;
+    maxFileSize: number;
+    mimeType: string;
+    name: string;
+    override: boolean;
+    stream: Readable;
+};
+export type FileUpdate = {
+    directory?: string;
+    name?: string;
+};
+export type FileStore = {
+    /**
+     * Returns file metadata and contents.
+     */
+    get: (path: string) => Promise<{
+        file: FileRecord;
+        stream: Readable;
+    }>;
+    /**
+     * Returns file metadata.
+     */
+    metadata: (path: string) => Promise<FileRecord>;
+    /**
+     * Deletes a file.
+     */
+    remove: (path: string) => Promise<void>;
+    /**
+     * Renames or moves a file.
+     */
+    update: (path: string, update: FileUpdate) => Promise<FileRecord>;
+    /**
+     * Stores a file.
+     */
+    upload: (upload: FileUpload) => Promise<{
+        created: boolean;
+        file: FileRecord;
+    }>;
+};
+/**
+ * Creates a disk- or memory-backed file store with serialized operations.
+ * @param {import('./config.js').FilesConfig} config File storage configuration.
+ * @returns {Promise<FileStore>} File store.
+ */
+export declare const createFileStore: (config: import('./config.js').FilesConfig) => Promise<FileStore>;
+export declare const registerFileRoutes: (fastify: any, { maxFileSize, store }: {
     maxFileSize: any;
     store: any;
 }) => void;

package/types/src/openapi/document.d.ts

@@ -1,6 +1,6 @@
 /**
- * Builds an OpenAPI 3.0 document from resolved server data.
- * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Document options.
+ * Builds an OpenAPI document without runtime server addresses.
+ * @param {{ database: Record<string, Array<Record<string, unknown>>>, files?: boolean, maxPageSize?: number, schema?: Record<string, unknown> }} options Source data and schema settings.
  * @returns {Record<string, unknown>} OpenAPI document.
  */
 export declare function buildOpenapiDocument(options: {

package/types/src/server.d.ts

@@ -1,13 +1,14 @@
 export type OpenapiDocument = Record<string, unknown>;
+export type ServerFacade = {
+    fastify: () => import('fastify').FastifyInstance;
+    openapi: () => Promise<OpenapiDocument>;
+};
 /**
- * Creates a Deep JSON Server facade.
- * @param {import('./config.js').DeepJsonServerConfig} options Server options.
+ * Creates lazy Fastify and OpenAPI accessors from one configuration.
+ * @param {import('./config.js').DeepJsonServerConfig} config Server configuration.
  * @param {{ files?: boolean }} [features] Optional feature switches.
- * @returns {Promise<{ fastify: () => import('fastify').FastifyInstance, openapi: () => Promise<OpenapiDocument> }>} Server facade.
+ * @returns {Promise<ServerFacade>} Server facade.
  */
-export declare function createServer(options: import('./config.js').DeepJsonServerConfig, features?: {
+export declare function createServer(config: import('./config.js').DeepJsonServerConfig, features?: {
     files?: boolean;
-}): Promise<{
-    fastify: () => import('fastify').FastifyInstance;
-    openapi: () => Promise<OpenapiDocument>;
-}>;
+}): Promise<ServerFacade>;

package/types/src/utils.d.ts

@@ -1,4 +1,12 @@
 export declare const createHttpError: (statusCode: any, message: any) => Error;
+/** @returns {<T>(operation: () => T | Promise<T>) => Promise<T>} Serialized operation scheduler. */
+export declare const createSerialQueue: () => <T>(operation: () => T | Promise<T>) => Promise<T>;
+/**
+ * Creates a random ID that is not currently in use.
+ * @param {(id: string) => boolean} isUsed Checks whether an ID already exists.
+ * @returns {string} Unique ID.
+ */
+export declare const createUniqueId: (isUsed: (id: string) => boolean) => string;
 export declare const getResourceNames: (data: any) => string[];
 export declare const isObject: (value: any) => boolean;
 export declare const isSafeKey: (key: any) => boolean;