def first(*args)
      first_arg = args.first
      last_arg  = args.last

      limit_specified = first_arg.kind_of?(Integer)
      with_query      = (last_arg.kind_of?(Hash) && !last_arg.empty?) || last_arg.kind_of?(Query)

      limit = limit_specified ? first_arg : 1
      query = with_query      ? last_arg  : {}

      query = self.query.slice(0, limit).update(query)

      # TODO: when a query provided, and there are enough elements in head to
      # satisfy the query.limit, filter the head with the query, and make
      # sure it matches the limit exactly.  if so, use that result instead
      # of calling all()
      #   - this can probably only be done if there is no :order parameter

      loaded = loaded?
      head   = self.head

      collection = if !with_query && (loaded || lazy_possible?(head, limit))
        new_collection(query, super(limit))
      else
        all(query)
      end

      return collection if limit_specified

      resource = collection.to_a.first

      if with_query || loaded
        resource
      elsif resource
        head[0] = resource
      end
    end
def first(*args)
      first_arg = args.first
      last_arg  = args.last

      limit_specified = first_arg.kind_of?(Integer)
      with_query      = (last_arg.kind_of?(Hash) && !last_arg.empty?) || last_arg.kind_of?(Query)

      limit = limit_specified ? first_arg : 1
      query = with_query      ? last_arg  : {}

      query = self.query.slice(0, limit).update(query)

      # TODO: when a query provided, and there are enough elements in head to
      # satisfy the query.limit, filter the head with the query, and make
      # sure it matches the limit exactly.  if so, use that result instead
      # of calling all()
      #   - this can probably only be done if there is no :order parameter

      loaded = loaded?
      head   = self.head

      collection = if !with_query && (loaded || lazy_possible?(head, limit))
        new_collection(query, super(limit))
      else
        all(query)
      end

      return collection if limit_specified

      resource = collection.to_a.first

      if with_query || loaded
        resource
      elsif resource
        head[0] = resource
      end
    end
Return the first Resource or the first N Resources in the Collection with an optional query

 When there are no arguments, return the first Resource in the
 Collection.  When the first argument is an Integer, return a
 Collection containing the first N Resources.  When the last
 (optional) argument is a Hash scope the results to the query.

 @param [Integer] limit (optional)
   limit the returned Collection to a specific number of entries
 @param [Hash] query (optional)
   scope the returned Resource or Collection to the supplied query

 @return [Resource, Collection]
   The first resource in the entries of this collection,
   or a new collection whose query has been merged

 @api public