@develit-io/backend-sdk 5.4.5

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2025 Develit.io s.r.o.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# Develit Backend SDK
+
+A TypeScript SDK for building Cloudflare Workers with database integration, command patterns, and automatic audit logging.
+
+## Installation
+
+```bash
+bun add @develit-io/backend-sdk
+```
+
+## Core Features
+
+- **Worker Framework**: Decorator-based actions with `@action()` and `@service()`
+- **Database Integration**: Built-in Drizzle ORM with `initializeDB()`
+- **Command Pattern**: Reusable, parameterized database operations
+- **Atomic Audit Logging**: Audit logs included in same database batch
+- **Type Safety**: Full TypeScript support throughout
+
+## Quick Start
+
+```typescript
+@service('user-service')
+export default class UserService extends develitWorker(WorkerEntrypoint<UserEnv>) {
+
+  constructor(env: Env, ctx: ExecutionContext) {
+    super(env, ctx)
+    // Setup audit logging
+    const auditWriter = createAuditLogWriter(tables.auditLog)
+    this.initializeDB(env.USER_DB, tables, auditWriter)
+    // Now available: this.db
+  }
+
+  @action('create-user')
+  async createUser(input: CreateUserInput): Promise<IRPCResponse<CreateUserOutput>> {
+    return this.handleAction(
+      {data: input, schema: createUserInputSchema},
+      {successMessage: 'User created successfully'},
+      () => {
+        await this.db.execute(createUserCommand(userData))
+    })
+  }
+}
+```
+
+## Key Exports
+
+```typescript
+// Core functionality
+export { develitWorker, action, service } from '@develit-io/workers-sdk'
+export { defineCommand, DatabaseTransaction, createAuditLogWriter } from '@develit-io/workers-sdk'
+
+// Built-in worker properties after initializeDB():
+// - this.db: DatabaseTransaction
+```
+
+## Examples
+
+- **[defineCommand Usage](./examples/define-command.md)** - Creating parameterized commands
+- **[DatabaseTransaction Usage](./examples/database-transaction.md)** - Transaction and audit logging
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+
+- Cloudflare Workers environment
+- Drizzle ORM setup
+
+## License
+
+ISC License - see package.json for details.

package/dist/index.cjs

@@ -0,0 +1,464 @@
+'use strict';
+
+const drizzleOrm = require('drizzle-orm');
+const pgCore = require('drizzle-orm/pg-core');
+const sqliteCore = require('drizzle-orm/sqlite-core');
+require('http-status-codes');
+const z = require('zod/v4/core');
+const h3 = require('h3');
+const consola = require('consola');
+const drizzleKit = require('drizzle-kit');
+const superjson = require('superjson');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+function _interopNamespaceCompat(e) {
+  if (e && typeof e === 'object' && 'default' in e) return e;
+  const n = Object.create(null);
+  if (e) {
+    for (const k in e) {
+      n[k] = e[k];
+    }
+  }
+  n.default = e;
+  return n;
+}
+
+const z__namespace = /*#__PURE__*/_interopNamespaceCompat(z);
+const superjson__default = /*#__PURE__*/_interopDefaultCompat(superjson);
+
+const base = {
+  id: sqliteCore.text("id").primaryKey(),
+  createdAt: sqliteCore.integer("created_at", { mode: "timestamp_ms" }).default(
+    drizzleOrm.sql`(unixepoch('subsec') * 1000)`
+  ),
+  modifiedAt: sqliteCore.integer("modified_at", { mode: "timestamp_ms" }).default(drizzleOrm.sql`null`).$onUpdate(() => /* @__PURE__ */ new Date())
+};
+const basePostgres = {
+  id: pgCore.uuid("id").primaryKey(),
+  createdAt: pgCore.timestamp("created_at", { mode: "date", withTimezone: false }).defaultNow().notNull(),
+  modifiedAt: pgCore.timestamp("modified_at", { mode: "date", withTimezone: false }).default(drizzleOrm.sql`null`).$onUpdate(() => /* @__PURE__ */ new Date())
+};
+
+const ibanZodSchema = new z__namespace.$ZodString({
+  type: "string",
+  checks: [
+    new z__namespace.$ZodCheckMinLength({
+      check: "min_length",
+      minimum: 1
+    }),
+    new z__namespace.$ZodCheckRegex({
+      check: "string_format",
+      format: "regex",
+      pattern: /^([A-Z]{2}[0-9]{2})([A-Z0-9]{4})([A-Z0-9]{4})([A-Z0-9]{4})([A-Z0-9]{4})?$/
+    })
+  ]
+});
+const swiftZodSchema = new z__namespace.$ZodString({
+  type: "string",
+  checks: [
+    new z__namespace.$ZodCheckMinLength({
+      check: "min_length",
+      minimum: 1
+    }),
+    new z__namespace.$ZodCheckRegex({
+      check: "string_format",
+      format: "regex",
+      pattern: /^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/
+    })
+  ]
+});
+
+const handleActionResponse = ({
+  error,
+  status,
+  message,
+  data
+}) => {
+  if (error) {
+    throw h3.createError({ status, message });
+  }
+  if (data === void 0 || data === null) {
+    throw h3.createError({
+      statusCode: 500,
+      message: "Could not process the request. (ACTION_RESPONSE_FAILED)"
+    });
+  }
+  return data;
+};
+
+const createInternalError = (error, details) => {
+  return {
+    status: details?.status || 500,
+    code: details?.code || "UNKNOWN_ERROR",
+    message: details?.message || (error instanceof Error ? error.message : "An unexpected error occurred.")
+  };
+};
+const isInternalError = (error) => {
+  return typeof error === "object" && error !== null && "message" in error && "code" in error;
+};
+
+const RPCResponse = {
+  /**
+   * ✅ Constructs a successful RPC response.
+   *
+   * This method wraps the provided data in a standardized response format,
+   * ensuring consistency across API responses.
+   *
+   * @template T - The type of the response data.
+   * @param message - Response message
+   * @param detail - Optional -> Contains data and status code
+   * @returns An `IRPCResponse<T>` with the provided data and no error.
+   */
+  ok(message, detail) {
+    return {
+      status: detail?.status || 200,
+      data: detail?.data,
+      error: false,
+      message
+    };
+  },
+  /**
+   * ❌ Constructs a generic service error response.
+   *
+   * This method logs the error and returns a standardized error response.
+   *
+   * @template T - The expected response type (typically ignored in errors).
+   * @param error - An `RPCError` containing error details.
+   * @returns An `IRPCResponse<T>` with `null` data and the provided error.
+   */
+  serviceError(error) {
+    consola.consola.error(error.message);
+    return {
+      status: error.status,
+      message: error.message,
+      data: null,
+      error: true
+    };
+  },
+  /**
+   * ❌ Constructs a validation error response (HTTP 400).
+   *
+   * This is a convenience method for returning validation errors.
+   * It internally delegates to `serviceError()`.
+   *
+   * @template T - The expected response type (typically ignored in errors).
+   * @param error - An `RPCError` representing a validation failure.
+   * @returns An `IRPCResponse<T>` with `null` data and the provided error.
+   */
+  validationError(error) {
+    return RPCResponse.serviceError(error);
+  }
+};
+
+const useResult = async (promise) => {
+  try {
+    return [await promise, null];
+  } catch (error) {
+    return [null, isInternalError(error) ? error : createInternalError(error)];
+  }
+};
+const useResultSync = (fn) => {
+  try {
+    return [fn(), null];
+  } catch (error) {
+    return [null, isInternalError(error) ? error : createInternalError(error)];
+  }
+};
+
+async function handleAction(worker, input, options = {}, actionExecution) {
+  const {
+    successMessage = "Operation completed successfully.",
+    logOutputTransform,
+    logInputTransform,
+    skipValidation = false,
+    skipLogging = false
+  } = options;
+  try {
+    if (!skipLogging && input) {
+      const inputToLog = logInputTransform ? logInputTransform(input.data) : input;
+      worker.logInput(inputToLog);
+    }
+    let validatedInput = input?.data || null;
+    if (!skipValidation && input) {
+      validatedInput = worker.handleInput({
+        input: input.data,
+        schema: input.schema
+      });
+    }
+    const [data, error] = await useResult(
+      actionExecution(validatedInput)
+    );
+    if (error) {
+      worker.logError(error);
+      return RPCResponse.serviceError(error);
+    }
+    if (!skipLogging) {
+      const outputToLog = logOutputTransform ? logOutputTransform(data) : data;
+      worker.logOutput(outputToLog);
+    }
+    return RPCResponse.ok(successMessage, { data });
+  } catch (error) {
+    const internalError = createInternalError(error);
+    worker.logError(internalError);
+    return RPCResponse.serviceError(internalError);
+  }
+}
+
+const drizzleConfig = drizzleKit.defineConfig({
+  dialect: "sqlite",
+  schema: "./src/database/schema/",
+  out: "./src/database/migrations/"
+});
+function first(rows) {
+  return rows.length > 0 ? rows[0] : void 0;
+}
+function firstOrError(rows) {
+  if (rows.length === 0) {
+    throw new Error("Query did not return any data.");
+  }
+  return rows[0];
+}
+const uuidv4 = () => crypto.randomUUID();
+
+const calculateExponentialBackoff = (attempts, baseDelaySeconds) => {
+  return baseDelaySeconds ** attempts;
+};
+
+const asNonEmpty = (arr) => {
+  return arr.length > 0 ? [arr[0], ...arr.slice(1)] : null;
+};
+
+class DatabaseTransaction {
+  constructor(db, serviceName, auditLogWriter) {
+    this.db = db;
+    this.serviceName = serviceName;
+    this.auditLogWriter = auditLogWriter;
+  }
+  commands = [];
+  logs = [];
+  ids = [];
+  enqueue(commands) {
+    return (Array.isArray(commands) ? commands : [commands]).map((cmd) => {
+      const commandItem = cmd.handler(this.db);
+      const auditLogPayload = {
+        ...commandItem.logPayload,
+        service: this.serviceName || "unknown-service"
+      };
+      this.commands.push(commandItem.command);
+      this.logs.push(auditLogPayload);
+      if (commandItem.id) {
+        this.ids.push(commandItem.id);
+      }
+      return commandItem;
+    }).reduce((acc, curr) => {
+      acc.push(curr.id);
+      return acc;
+    }, []);
+  }
+  async execute(commandItem) {
+    this.enqueue(commandItem);
+    await this.executeAll();
+  }
+  async executeAll() {
+    let allCommands = [...this.commands];
+    if (this.auditLogWriter && this.logs.length > 0) {
+      const auditCommands = this.auditLogWriter(this.logs, this.db);
+      allCommands.push(...auditCommands);
+    }
+    const batchItems = asNonEmpty(allCommands);
+    if (batchItems) {
+      await this.db.batch(batchItems);
+    }
+    this.commands = [];
+    this.logs = [];
+    this.ids = [];
+  }
+  getLogs() {
+    return [...this.logs];
+  }
+  getIds() {
+    return [...this.ids];
+  }
+  getCommandsCount() {
+    return this.commands.length;
+  }
+}
+
+const defineCommand = (handler) => {
+  return (params) => ({
+    handler: (db) => handler(db, params)
+  });
+};
+
+function createAuditLogWriter(table) {
+  return (logs, db) => {
+    if (logs.length === 0) return [];
+    const auditRecords = logs.map((log) => ({
+      ...log,
+      createdAt: /* @__PURE__ */ new Date(),
+      id: crypto.randomUUID()
+    }));
+    return [db.insert(table).values(auditRecords)];
+  };
+}
+
+const service = (serviceName) => {
+  return function(constructor) {
+    return class extends constructor {
+      name = `${serviceName}-service`;
+    };
+  };
+};
+
+const action = (name) => {
+  return (_target, _propertyKey, descriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = function(...args) {
+      this.action = name;
+      return originalMethod.apply(this, args);
+    };
+    return descriptor;
+  };
+};
+
+function cloudflareQueue(options) {
+  return (_target, _propertyKey, descriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(...args) {
+      const batch = args[0];
+      let retriedCount = 0;
+      batch.messages.forEach((msg) => {
+        const originalRetry = msg.retry?.bind(msg);
+        msg.retry = () => {
+          retriedCount++;
+          return originalRetry({
+            delaySeconds: calculateExponentialBackoff(
+              msg.attempts,
+              options.baseDelay
+            )
+          });
+        };
+      });
+      const result = await originalMethod.apply(this, args);
+      if (typeof this.logQueueRetries === "function") {
+        this.logQueueRetries({
+          message: `Retried ${retriedCount} out of ${batch.messages.length} messages`
+        });
+      }
+      return result;
+    };
+  };
+}
+
+function develitWorker(Worker) {
+  class DevelitWorker extends Worker {
+    name = "not-set";
+    action = "not-set";
+    // public db!: DatabaseTransaction<string>
+    async fetch() {
+      return new Response("Service is up and running!");
+    }
+    // initializeDB<TAuditAction = string>(
+    //   database: D1Database,
+    //   schema: Record<string, unknown>,
+    //   auditLogWriter?: AuditLogWriter<TAuditAction>,
+    // ): void {
+    //   const drizzleInstance = drizzle(database, {
+    //     schema,
+    //   }) as DrizzleD1Database<Record<string, unknown>>
+    //   this.db = new DatabaseTransaction<TAuditAction>(
+    //     drizzleInstance,
+    //     this.name,
+    //     auditLogWriter,
+    //   ) as unknown as DatabaseTransaction<string>
+    // }
+    handleInput({
+      input,
+      schema
+    }) {
+      this.logInput({ input });
+      const parseResult = z__namespace.safeParse(schema, input);
+      if (!parseResult.success) {
+        const parseError = {
+          status: 400,
+          code: "INVALID_ACTION_INPUT",
+          message: z__namespace.prettifyError(parseResult.error)
+        };
+        this.logError(parseError);
+        throw RPCResponse.validationError(parseError);
+      }
+      if (!parseResult.data) {
+        throw createInternalError({
+          message: "The provided input could not be processed."
+        });
+      }
+      return parseResult.data;
+    }
+    log(data, identifier) {
+      const name = identifier ?? `${this.name}:${this.action}:log`;
+      console.log(name, {
+        entrypoint: this.name,
+        action: this.action,
+        identifier: name,
+        data: superjson__default.stringify(data)
+      });
+    }
+    logQueuePush(data) {
+      this.log(data, `${this.name}:${this.action}:queue-push`);
+    }
+    logQueuePull(data) {
+      this.log(data, `${this.name}:${this.action}:queue-pull`);
+    }
+    logQueueRetries(data) {
+      this.log(data, `${this.name}:${this.action}:queue-retries`);
+    }
+    logInput(data) {
+      this.log(data, `${this.name}:${this.action}:input`);
+    }
+    logOutput(data) {
+      this.log(data, `${this.name}:${this.action}:output`);
+    }
+    logError(error) {
+      this.log(error, `${this.name}:${this.action}:error`);
+    }
+    pushToQueue(queue, message) {
+      if (!Array.isArray(message))
+        return queue.send(message, { contentType: "v8" });
+      return queue.sendBatch(
+        message.map((m) => ({
+          body: m,
+          contentType: "v8"
+        }))
+      );
+    }
+    async handleAction(input, options = {}, actionExecution) {
+      return handleAction(this, input, options, actionExecution);
+    }
+  }
+  return DevelitWorker;
+}
+
+exports.DatabaseTransaction = DatabaseTransaction;
+exports.RPCResponse = RPCResponse;
+exports.action = action;
+exports.base = base;
+exports.basePostgres = basePostgres;
+exports.calculateExponentialBackoff = calculateExponentialBackoff;
+exports.cloudflareQueue = cloudflareQueue;
+exports.createAuditLogWriter = createAuditLogWriter;
+exports.createInternalError = createInternalError;
+exports.defineCommand = defineCommand;
+exports.develitWorker = develitWorker;
+exports.drizzleConfig = drizzleConfig;
+exports.first = first;
+exports.firstOrError = firstOrError;
+exports.handleAction = handleAction;
+exports.handleActionResponse = handleActionResponse;
+exports.ibanZodSchema = ibanZodSchema;
+exports.isInternalError = isInternalError;
+exports.service = service;
+exports.swiftZodSchema = swiftZodSchema;
+exports.useResult = useResult;
+exports.useResultSync = useResultSync;
+exports.uuidv4 = uuidv4;