Bookshelf Instance

/**
 * Creates a new Bookshelf instance
 * @param {Knex} knex - Initialized Knex client instance
 * @returns {Bookshelf} Bookshelf instance
 * @throws {Error} If knex is not a valid Knex instance
 */
function Bookshelf(knex);

const knex = require('knex')({
  client: 'mysql',
  connection: {
    host: '127.0.0.1',
    user: 'your_db_user', 
    password: 'your_password',
    database: 'myapp'
  }
});

const bookshelf = require('bookshelf')(knex);

interface BookshelfProperties {
  /** Current Bookshelf version string */
  VERSION: string;
  
  /** Reference to the underlying Knex instance */
  knex: Knex;
  
  /** Base Model constructor for extending */
  Model: ModelConstructor;
  
  /** Base Collection constructor for extending */
  Collection: CollectionConstructor;
}

/**
 * Register or retrieve a model by name
 * @param {string} name - Model name
 * @returns {Model} Previously registered model
 */
model(name: string): Model;

/**
 * Register a new model
 * @param {string} name - Model name for registry
 * @param {Model|object} Model - Model constructor or plain object to extend
 * @param {object} [staticProperties] - Static properties for the model
 * @returns {Model} Registered model constructor
 */
model(name: string, Model: ModelConstructor | object, staticProperties?: object): Model;

// Register a model
const User = bookshelf.model('User', {
  tableName: 'users',
  posts() {
    return this.hasMany('Post'); // Can reference by string name
  }
});

// Retrieve a registered model
const User = bookshelf.model('User');

// Register with static properties
const Post = bookshelf.model('Post', {
  tableName: 'posts'
}, {
  findByTitle(title) {
    return this.where('title', title).fetch();
  }
});

/**
 * Register or retrieve a collection by name
 * @param {string} name - Collection name
 * @returns {Collection} Previously registered collection
 */
collection(name: string): Collection;

/**
 * Register a new collection
 * @param {string} name - Collection name for registry
 * @param {Collection|object} Collection - Collection constructor or plain object to extend
 * @param {object} [staticProperties] - Static properties for the collection
 * @returns {Collection} Registered collection constructor
 */
collection(name: string, Collection: CollectionConstructor | object, staticProperties?: object): Collection;

const Users = bookshelf.collection('Users', {
  model: bookshelf.model('User')
});

const users = bookshelf.collection('Users');

/**
 * Custom resolver function for model/collection names
 * Override this to define custom resolution logic
 * @param {string} name - The model/collection name to resolve
 * @returns {*} The resolved model/collection or any custom value
 */
resolve(name: string): any;

// Custom resolver
bookshelf.resolve = (name) => {
  if (name === 'SpecialUser') {
    return bookshelf.model('User');
  }
  // Return undefined for default behavior
};

/**
 * Execute operations within a database transaction
 * @param {Function} transactionCallback - Callback containing transaction logic
 * @returns {Promise} Promise resolving to callback return value
 */
transaction(transactionCallback: (transaction: Transaction) => Promise<any>): Promise<any>;

const result = await bookshelf.transaction(async (t) => {
  const user = await new User({name: 'Alice'}).save(null, {transacting: t});
  const post = await new Post({
    title: 'Hello World',
    user_id: user.id
  }).save(null, {transacting: t});
  
  return {user, post};
});

/**
 * Load a plugin into the Bookshelf instance
 * @param {string|Function|Array} plugin - Plugin to load (module name, function, or array)
 * @param {*} [options] - Options to pass to the plugin
 * @returns {Bookshelf} The bookshelf instance for chaining
 */
plugin(plugin: string | Function | Array, options?: any): BookshelfInstance;

// Load plugin by module name
bookshelf.plugin('bookshelf-uuid');

// Load plugin function
bookshelf.plugin(function(bookshelf, options) {
  // Plugin implementation
});

// Load multiple plugins
bookshelf.plugin(['plugin1', 'plugin2'], {option1: 'value'});

// Plugin with options
bookshelf.plugin('some-plugin', {
  option1: 'value1',
  option2: 'value2'
});

interface Transaction {
  // Knex transaction object - see Knex documentation
}

interface ModelConstructor {
  new(attributes?: object, options?: object): Model;
  forge(attributes?: object, options?: object): Model;
  // Additional static methods...
}

interface CollectionConstructor {
  new(models?: any[], options?: object): Collection;
  forge(models?: any[], options?: object): Collection;
  // Additional static methods...
}