@flowblade/sqlduck 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,4 +1,7 @@
+import * as _duckdb_node_api0 from "@duckdb/node-api";
 import { DuckDBConnection, DuckDBType } from "@duckdb/node-api";
+import * as _logtape_logtape0 from "@logtape/logtape";
+import { Logger } from "@logtape/logtape";
 import * as z from "zod";
 import { ZodObject } from "zod";
 
@@ -49,7 +52,7 @@ declare class DuckMemory {
   getSummary: () => Promise<DuckMemorySummary>;
 }
 //#endregion
-//#region src/table/table.d.ts
+//#region src/objects/table.d.ts
 /**
  * Fully qualified table information
  */
@@ -99,9 +102,14 @@ declare const getTableCreateFromZod: <TSchema extends TableSchemaZod>(params: Ge
 //#region src/sql-duck.d.ts
 type SqlDuckParams = {
   conn: DuckDBConnection;
-  logger?: (msg: string) => void;
+  /**
+   * Optional logtape/logger to use for logging.
+   * If not provided, a default logger will be used.
+   * @see {@link https://github.com/logtape/logtape}
+   */
+  logger?: Logger;
 };
-type RowStream<T> = AsyncIterableIterator<T>;
+type RowStream<T> = AsyncIterableIterator<T> | AsyncGenerator<T> | Generator<T>;
 type ToTableParams<TSchema extends TableSchemaZod> = {
   /**
    * Used to create and fill the data into the table
@@ -193,4 +201,145 @@ declare const zodCodecs: {
   readonly bigintToString: z.ZodCodec<z.ZodBigInt, z.ZodString>;
 };
 //#endregion
-export { DuckMemory, DuckMemoryTag, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, getTableCreateFromZod, zodCodecs };
+//#region src/objects/database.d.ts
+type DatabaseProperties = {
+  alias: string;
+};
+declare class Database {
+  #private;
+  get alias(): string;
+  constructor(params: DatabaseProperties);
+  toJson(): {
+    type: string;
+    params: {
+      alias: string;
+    };
+  };
+  [Symbol.toStringTag](): string;
+}
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.d.ts
+declare const duckDatabaseManagerDbParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<":memory:">;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"duckdb">;
+  path: z.ZodString;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+type DuckDatabaseManagerDbParams = z.infer<typeof duckDatabaseManagerDbParamsSchema>;
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.d.ts
+type Behaviour = 'OR REPLACE' | 'IF NOT EXISTS';
+type DuckDatabaseAttachCommandOptions = {
+  behaviour?: Behaviour;
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.d.ts
+declare class DuckDatabaseManager {
+  #private;
+  constructor(conn: DuckDBConnection, params?: {
+    logger?: Logger;
+  });
+  /**
+   * Attach a database to the current connection
+   *
+   * @example
+   * ```typescript
+   * const dbManager = new DuckDatabaseManager(conn);
+   * const database = dbManager.attach({
+   *   type: ':memory:', // can be 'duckdb', 's3'...
+   *   alias: 'mydb',
+   *   options: { COMPRESS: 'true' }
+   * });
+   *
+   * console.log(database.alias); // 'mydb'
+   * ```
+   */
+  attach: (dbParams: DuckDatabaseManagerDbParams, options?: DuckDatabaseAttachCommandOptions) => Promise<Database>;
+  attachOrReplace: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  attachIfNotExists: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  showDatabases: () => Promise<Record<string, _duckdb_node_api0.JS>[]>;
+  detach: (dbAlias: string) => Promise<boolean>;
+  detachIfExists: (dbAlias: string) => Promise<boolean>;
+  /**
+   * The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+   *
+   * It is therefore recommended to recompute these statistics for improved join orders,
+   * especially after performing large updates (inserts and/or deletes).
+   *
+   * @link https://duckdb.org/docs/stable/sql/statements/analyze
+   */
+  analyze: () => Promise<boolean>;
+  checkpoint: (dbAlias: string) => Promise<boolean>;
+}
+//#endregion
+//#region src/validation/core/duckdb-reserved-keywords.d.ts
+/**
+ * DuckDB reserved keywords that cannot be used as unquoted identifiers.
+ * @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+ */
+declare const duckdbReservedKeywords: readonly ["ALL", "ANALYSE", "ANALYZE", "AND", "ANY", "ARRAY", "AS", "ASC", "ASYMMETRIC", "BOTH", "CASE", "CAST", "CHECK", "COLLATE", "COLUMN", "CONSTRAINT", "CREATE", "CROSS", "CURRENT_CATALOG", "CURRENT_DATE", "CURRENT_ROLE", "CURRENT_SCHEMA", "CURRENT_TIME", "CURRENT_TIMESTAMP", "CURRENT_USER", "DEFAULT", "DEFERRABLE", "DESC", "DISTINCT", "DO", "ELSE", "END", "EXCEPT", "EXISTS", "EXTRACT", "FALSE", "FETCH", "FOR", "FOREIGN", "FROM", "GRANT", "GROUP", "HAVING", "IF", "ILIKE", "IN", "INITIALLY", "INNER", "INTERSECT", "INTO", "IS", "ISNULL", "JOIN", "LATERAL", "LEADING", "LEFT", "LIKE", "LIMIT", "LOCALTIME", "LOCALTIMESTAMP", "NATURAL", "NOT", "NOTNULL", "NULL", "OFFSET", "ON", "ONLY", "OR", "ORDER", "OUTER", "OVERLAPS", "PLACING", "PRIMARY", "REFERENCES", "RETURNING", "RIGHT", "ROW", "SELECT", "SESSION_USER", "SIMILAR", "SOME", "SYMMETRIC", "TABLE", "THEN", "TO", "TRAILING", "TRUE", "UNION", "UNIQUE", "USING", "VARIADIC", "VERBOSE", "WHEN", "WHERE", "WINDOW", "WITH"];
+type DuckdbReservedKeywords = (typeof duckdbReservedKeywords)[number];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.d.ts
+declare const duckTableNameSchema: z.ZodString;
+declare const duckTableAliasSchema: z.ZodString;
+//#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.d.ts
+declare const flowbladeLogtapeSqlduckConfig: {
+  categories: string[];
+};
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.d.ts
+declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
+//#endregion
+export { Database, DuckDatabaseManager, type DuckDatabaseManagerDbParams, DuckMemory, DuckMemoryTag, type DuckdbReservedKeywords, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, duckDatabaseManagerDbParamsSchema, duckTableAliasSchema, duckTableNameSchema, duckdbReservedKeywords, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };

package/dist/index.d.mts

@@ -1,4 +1,7 @@
+import * as _duckdb_node_api0 from "@duckdb/node-api";
 import { DuckDBConnection, DuckDBType } from "@duckdb/node-api";
+import * as _logtape_logtape0 from "@logtape/logtape";
+import { Logger } from "@logtape/logtape";
 import * as z from "zod";
 import { ZodObject } from "zod";
 
@@ -49,7 +52,7 @@ declare class DuckMemory {
   getSummary: () => Promise<DuckMemorySummary>;
 }
 //#endregion
-//#region src/table/table.d.ts
+//#region src/objects/table.d.ts
 /**
  * Fully qualified table information
  */
@@ -99,9 +102,14 @@ declare const getTableCreateFromZod: <TSchema extends TableSchemaZod>(params: Ge
 //#region src/sql-duck.d.ts
 type SqlDuckParams = {
   conn: DuckDBConnection;
-  logger?: (msg: string) => void;
+  /**
+   * Optional logtape/logger to use for logging.
+   * If not provided, a default logger will be used.
+   * @see {@link https://github.com/logtape/logtape}
+   */
+  logger?: Logger;
 };
-type RowStream<T> = AsyncIterableIterator<T>;
+type RowStream<T> = AsyncIterableIterator<T> | AsyncGenerator<T> | Generator<T>;
 type ToTableParams<TSchema extends TableSchemaZod> = {
   /**
    * Used to create and fill the data into the table
@@ -193,4 +201,145 @@ declare const zodCodecs: {
   readonly bigintToString: z.ZodCodec<z.ZodBigInt, z.ZodString>;
 };
 //#endregion
-export { DuckMemory, type DuckMemoryTag, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, getTableCreateFromZod, zodCodecs };
+//#region src/objects/database.d.ts
+type DatabaseProperties = {
+  alias: string;
+};
+declare class Database {
+  #private;
+  get alias(): string;
+  constructor(params: DatabaseProperties);
+  toJson(): {
+    type: string;
+    params: {
+      alias: string;
+    };
+  };
+  [Symbol.toStringTag](): string;
+}
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.d.ts
+declare const duckDatabaseManagerDbParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<":memory:">;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"duckdb">;
+  path: z.ZodString;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+type DuckDatabaseManagerDbParams = z.infer<typeof duckDatabaseManagerDbParamsSchema>;
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.d.ts
+type Behaviour = 'OR REPLACE' | 'IF NOT EXISTS';
+type DuckDatabaseAttachCommandOptions = {
+  behaviour?: Behaviour;
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.d.ts
+declare class DuckDatabaseManager {
+  #private;
+  constructor(conn: DuckDBConnection, params?: {
+    logger?: Logger;
+  });
+  /**
+   * Attach a database to the current connection
+   *
+   * @example
+   * ```typescript
+   * const dbManager = new DuckDatabaseManager(conn);
+   * const database = dbManager.attach({
+   *   type: ':memory:', // can be 'duckdb', 's3'...
+   *   alias: 'mydb',
+   *   options: { COMPRESS: 'true' }
+   * });
+   *
+   * console.log(database.alias); // 'mydb'
+   * ```
+   */
+  attach: (dbParams: DuckDatabaseManagerDbParams, options?: DuckDatabaseAttachCommandOptions) => Promise<Database>;
+  attachOrReplace: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  attachIfNotExists: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  showDatabases: () => Promise<Record<string, _duckdb_node_api0.JS>[]>;
+  detach: (dbAlias: string) => Promise<boolean>;
+  detachIfExists: (dbAlias: string) => Promise<boolean>;
+  /**
+   * The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+   *
+   * It is therefore recommended to recompute these statistics for improved join orders,
+   * especially after performing large updates (inserts and/or deletes).
+   *
+   * @link https://duckdb.org/docs/stable/sql/statements/analyze
+   */
+  analyze: () => Promise<boolean>;
+  checkpoint: (dbAlias: string) => Promise<boolean>;
+}
+//#endregion
+//#region src/validation/core/duckdb-reserved-keywords.d.ts
+/**
+ * DuckDB reserved keywords that cannot be used as unquoted identifiers.
+ * @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+ */
+declare const duckdbReservedKeywords: readonly ["ALL", "ANALYSE", "ANALYZE", "AND", "ANY", "ARRAY", "AS", "ASC", "ASYMMETRIC", "BOTH", "CASE", "CAST", "CHECK", "COLLATE", "COLUMN", "CONSTRAINT", "CREATE", "CROSS", "CURRENT_CATALOG", "CURRENT_DATE", "CURRENT_ROLE", "CURRENT_SCHEMA", "CURRENT_TIME", "CURRENT_TIMESTAMP", "CURRENT_USER", "DEFAULT", "DEFERRABLE", "DESC", "DISTINCT", "DO", "ELSE", "END", "EXCEPT", "EXISTS", "EXTRACT", "FALSE", "FETCH", "FOR", "FOREIGN", "FROM", "GRANT", "GROUP", "HAVING", "IF", "ILIKE", "IN", "INITIALLY", "INNER", "INTERSECT", "INTO", "IS", "ISNULL", "JOIN", "LATERAL", "LEADING", "LEFT", "LIKE", "LIMIT", "LOCALTIME", "LOCALTIMESTAMP", "NATURAL", "NOT", "NOTNULL", "NULL", "OFFSET", "ON", "ONLY", "OR", "ORDER", "OUTER", "OVERLAPS", "PLACING", "PRIMARY", "REFERENCES", "RETURNING", "RIGHT", "ROW", "SELECT", "SESSION_USER", "SIMILAR", "SOME", "SYMMETRIC", "TABLE", "THEN", "TO", "TRAILING", "TRUE", "UNION", "UNIQUE", "USING", "VARIADIC", "VERBOSE", "WHEN", "WHERE", "WINDOW", "WITH"];
+type DuckdbReservedKeywords = (typeof duckdbReservedKeywords)[number];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.d.ts
+declare const duckTableNameSchema: z.ZodString;
+declare const duckTableAliasSchema: z.ZodString;
+//#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.d.ts
+declare const flowbladeLogtapeSqlduckConfig: {
+  categories: string[];
+};
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.d.ts
+declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
+//#endregion
+export { Database, DuckDatabaseManager, type DuckDatabaseManagerDbParams, DuckMemory, type DuckMemoryTag, type DuckdbReservedKeywords, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, duckDatabaseManagerDbParamsSchema, duckTableAliasSchema, duckTableNameSchema, duckdbReservedKeywords, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };