Merge branch 'new-feats' into feature/cran-issue

Author: Cidree

.claude/CLAUDE.md

@@ -91,7 +91,18 @@ Tests use **testthat edition 3**. `tests/testthat/setup.R` loads shared spatial
 
 ## Adding a New Function
 
-When implementing a new exported function, complete **all four steps** before considering the task done.
+When implementing a new exported function, first write a plan (step 0), get it approved, then complete the remaining steps before considering the task done.
+
+### 0. Plan first (before writing any code)
+
+Present a short, written plan and wait for approval before implementing. The plan should cover:
+
+- **Name**: the proposed `ddbs_*` name, and whether it should follow an existing family convention (e.g. `ddbs_line_*` for linestring ops, `ddbs_get_n*` for counts) rather than a bare mirror of the `ST_*` name.
+- **R file**: which `R/` script it goes in (see Key File Map).
+- **pkgdown**: which `reference:` section in `_pkgdown.yml` it belongs to.
+- **Macro**: whether to also register a DuckDB macro (in `R/utils_not_exported.R`) so it works inside `dplyr::mutate()`/`summarise()`.
+
+Before presenting the plan, verify the DuckDB function empirically (signature, return type, CRS behaviour, edge cases) with a quick query rather than assuming.
 
 ### 1. Implementation and documentation
 

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: duckspatial
 Title: R Interface to 'DuckDB' Database with Spatial Extension
-Version: 1.1.3
+Version: 1.1.2.9000
 Authors@R: c(
     person(
         "Adrián", "Cidre González", 
@@ -56,6 +56,7 @@ Suggests:
     areal,
     bench,
     duckdbfs,
+    geojsonsf,
     ggplot2 (>= 3.3.1),
     knitr,
     lwgeom,

NAMESPACE

@@ -49,6 +49,7 @@ export(ddbs_affine)
 export(ddbs_area)
 export(ddbs_as_geojson)
 export(ddbs_as_hexwkb)
+export(ddbs_as_mvt_geom)
 export(ddbs_as_points)
 export(ddbs_as_text)
 export(ddbs_as_wkb)
@@ -80,6 +81,7 @@ export(ddbs_dump)
 export(ddbs_endpoint)
 export(ddbs_envelope)
 export(ddbs_equals)
+export(ddbs_extension_info)
 export(ddbs_exterior_ring)
 export(ddbs_filter)
 export(ddbs_flip)
@@ -89,8 +91,14 @@ export(ddbs_force_3d)
 export(ddbs_force_4d)
 export(ddbs_generate_points)
 export(ddbs_geom_col)
+export(ddbs_geom_from_geojson)
+export(ddbs_geom_from_hexewkb)
+export(ddbs_geom_from_hexwkb)
+export(ddbs_geom_from_text)
+export(ddbs_geom_from_wkb)
 export(ddbs_geometry_type)
 export(ddbs_get_ngeometries)
+export(ddbs_get_ninterior_rings)
 export(ddbs_get_npoints)
 export(ddbs_get_resources)
 export(ddbs_glimpse)
@@ -99,6 +107,7 @@ export(ddbs_has_z)
 export(ddbs_install)
 export(ddbs_interpolate_aw)
 export(ddbs_intersection)
+export(ddbs_intersection_agg)
 export(ddbs_intersects)
 export(ddbs_intersects_extent)
 export(ddbs_is_closed)
@@ -113,6 +122,7 @@ export(ddbs_line_endpoint)
 export(ddbs_line_interpolate)
 export(ddbs_line_locate_point)
 export(ddbs_line_merge)
+export(ddbs_line_node)
 export(ddbs_line_startpoint)
 export(ddbs_line_substring)
 export(ddbs_list_tables)
@@ -129,6 +139,7 @@ export(ddbs_minimum_rotated_rectangle)
 export(ddbs_mmax)
 export(ddbs_mmin)
 export(ddbs_multi)
+export(ddbs_normalize)
 export(ddbs_open_dataset)
 export(ddbs_options)
 export(ddbs_overlaps)
@@ -140,9 +151,11 @@ export(ddbs_quadkey)
 export(ddbs_read_meta)
 export(ddbs_read_table)
 export(ddbs_read_vector)
+export(ddbs_reduce_precision)
 export(ddbs_register_table)
 export(ddbs_register_vector)
 export(ddbs_remove_repeated_points)
+export(ddbs_reverse)
 export(ddbs_rotate)
 export(ddbs_rotate_3d)
 export(ddbs_scale)
@@ -165,6 +178,7 @@ export(ddbs_voronoi)
 export(ddbs_within)
 export(ddbs_within_properly)
 export(ddbs_write_dataset)
+export(ddbs_write_mbtiles)
 export(ddbs_write_table)
 export(ddbs_write_vector)
 export(ddbs_x)

NEWS.md

@@ -1,5 +1,35 @@
 
-# duckspatial 1.1.3
+
+
+# duckspatial (development version)
+
+## NEW FEATURES
+
+* `ddbs_extension_info()`: prints a `glimpse()` of a DuckDB extension's row from `duckdb_extensions()` (the spatial extension by default), showing its installed/loaded status, version, and install path.
+
+* `ddbs_reduce_precision()`: snaps geometry coordinates to a regular grid, reducing their precision.
+
+* `ddbs_line_node()`: nodes a set of line geometries, splitting them at every crossing and returning a fully noded `MULTILINESTRING`.
+
+* `ddbs_intersection_agg()`: computes the geometric intersection (common area) of a set of geometries, optionally grouped by one or more columns. The intersection counterpart to `ddbs_union_agg()`.
+
+* `ddbs_reverse()`: returns each geometry with the order of its vertices reversed.
+
+* `ddbs_normalize()`: returns each geometry in its normalized (canonical) form.
+
+* `ddbs_write_mbtiles()`: generates a Mapbox Vector Tile pyramid from a spatial dataset and writes it to an MBTiles file, ready to serve or convert to PMTiles.
+
+* `ddbs_as_mvt_geom()`: transforms geometries into Mapbox Vector Tile (MVT) coordinate space, clipping them to a tile's bounding box and mapping the coordinates into the tile's integer pixel space.
+
+* `ddbs_geom_from_text()`, `ddbs_geom_from_wkb()`, `ddbs_geom_from_hexwkb()`, `ddbs_geom_from_hexewkb()`, `ddbs_geom_from_geojson()`: parse serialized geometries (WKT, WKB, HEXWKB, HEXEWKB, GeoJSON) into a spatial object. These are the inverses of the `ddbs_as_*()` serializers.
+
+* `ddbs_get_ninterior_rings()`: returns the number of interior rings (holes) in a POLYGON geometry.
+
+## ENHANCEMENTS
+
+* `ddbs_install()`: gains a `repos` argument to install an extension from a specific DuckDB repository (e.g. `"core"`, `"core_nightly"`, `"community"`). When `NULL` (default), the previous behaviour is kept (core, then community) (#144).
+
+* `ddbs_as_geojson()`: now includes all non-geometry columns as feature `properties` instead of serializing only the geometry. By default it returns a single GeoJSON `FeatureCollection` (matching `geojsonsf::sf_geojson()`); pass `feature_collection = FALSE` for a vector with one `Feature` per row (#141).
 
 ## BUG FIXES
 

R/db_extension.R

@@ -7,6 +7,13 @@
 #' @param upgrade if TRUE, it upgrades the DuckDB extension to the latest version
 #' @template quiet
 #' @param extension name of the extension to install, default is "spatial"
+#' @param repos optional character string naming the repository to install the
+#' extension from (e.g. \code{"core"}, \code{"core_nightly"}, or
+#' \code{"community"}); a URL or path can also be supplied. If \code{NULL}
+#' (default), the \code{core} repository is tried first, then \code{community}.
+#' Switching an already-installed extension to a different repository requires
+#' \code{upgrade = TRUE}. See
+#' \url{https://duckdb.org/docs/stable/extensions/installing_extensions}.
 #'
 #' @returns TRUE (invisibly) for successful installation
 #' @export
@@ -32,10 +39,11 @@
 #' duckdb::dbDisconnect(conn)
 #' }
 ddbs_install <- function(
-    conn, 
-    upgrade = FALSE, 
-    quiet = FALSE, 
-    extension = "spatial"
+    conn,
+    upgrade = FALSE,
+    quiet = FALSE,
+    extension = "spatial",
+    repos = NULL
 ) {
 
     # 1. Get extensions list
@@ -44,6 +52,7 @@ ddbs_install <- function(
     # 2. Checks
     ## 2.1. Check connection
     dbConnCheck(conn)
+    if (!is.null(repos)) assert_character_scalar(repos, "repos")
     ## 2.2. Check if it's installed / needs upgrade
     target_ext <- ext[ext$extension_name == extension, ]
     if (nrow(target_ext) == 1 && target_ext$installed) {
@@ -66,7 +75,9 @@ ddbs_install <- function(
             isTRUE(result$install_mode == "repository" && !result$requires_version_upgrade)
         }, error = function(e) FALSE)
 
-        if (isTRUE(latest)) {
+        # Skip the short-circuit when an explicit repository is requested, so the
+        # forced install from `repos` still runs (e.g. switching core -> core_nightly)
+        if (isTRUE(latest) && is.null(repos)) {
             if (isFALSE(quiet)) {
                 cli::cli_alert_info(
                     "{extension} extension version {.val {target_ext$extension_version}} is already the latest version."
@@ -81,51 +92,56 @@ ddbs_install <- function(
         cli::cli_abort("{extension} is already loaded in the connection. Upgrading the version is only allowed in non-loaded connections.")
     }
 
-    # 3. For non-upgrade installs, try LOAD first — core extensions (like spatial
-    #    in DuckDB >= 1.5) are bundled and loadable without writing to disk.
-    #    This avoids filesystem writes that fail in read-only environments (e.g. CRAN).
-    if (!upgrade) {
-        load_ok <- tryCatch({
-            suppressMessages(DBI::dbExecute(conn, glue::glue("LOAD {extension};")))
-            TRUE
-        }, error = function(e) FALSE)
+    # 3. Install/upgrade extension
+    install_kw <- if (upgrade) "FORCE INSTALL" else "INSTALL"
 
-        if (load_ok) {
-            if (isFALSE(quiet)) {
-                cli::cli_alert_success("{extension} extension installed")
-            }
-            return(invisible(TRUE))
-        }
-    }
+    if (!is.null(repos)) {
+
+        ## 3a. Explicit repository chosen by the user (no fallback). Named repos
+        ## (core, core_nightly, community, ...) are bare identifiers; URLs/paths
+        ## must be single-quoted.
+        repos_sql <- if (grepl("^[A-Za-z0-9_]+$", repos)) repos else ddbs_quote_sql_string(conn, repos)
 
-    # 4. Install/upgrade extension - try core, then community, then error
-    install_sql <- if (upgrade) "FORCE INSTALL {extension};" else "INSTALL {extension};"
-    community_sql <- if (upgrade) "FORCE INSTALL {extension} FROM community;" else "INSTALL {extension} FROM community;"
-
-    installed <- tryCatch({
-        suppressMessages(DBI::dbExecute(conn, glue::glue(install_sql)))
-        "core"
-    }, error = function(e) {
-        tryCatch({
-            suppressMessages(DBI::dbExecute(conn, glue::glue(community_sql)))
-            "community"
-        }, error = function(e2) {
-            NULL
+        installed <- tryCatch({
+            suppressMessages(DBI::dbExecute(conn, glue::glue("{install_kw} {extension} FROM {repos_sql};")))
+            repos
+        }, error = function(e) {
+            cli::cli_abort(c(
+                "Failed to {if (upgrade) 'upgrade' else 'install'} the {extension} extension from the {.val {repos}} repository.",
+                "x" = conditionMessage(e),
+                "i" = "If {extension} is already installed from a different repository, set {.code upgrade = TRUE} to switch.",
+                "i" = "Check the repository name: {.url https://duckdb.org/docs/stable/extensions/installing_extensions}"
+            ))
         })
-    })
-
-    if (is.null(installed)) {
-        cli::cli_abort(c(
-            "Failed to {if (upgrade) 'upgrade' else 'install'} the {extension} extension.",
-            "i" = "It could not be found in the core or community repositories.",
-            "i" = "It might not be available for this version of DuckDB",
-            "i" = "Check that the extension name is correct: {.url https://duckdb.org/docs/extensions/overview}"
-        ))
+
+    } else {
+
+        ## 3b. Default: try core, then community, then error
+        installed <- tryCatch({
+            suppressMessages(DBI::dbExecute(conn, glue::glue("{install_kw} {extension};")))
+            "core"
+        }, error = function(e) {
+            tryCatch({
+                suppressMessages(DBI::dbExecute(conn, glue::glue("{install_kw} {extension} FROM community;")))
+                "community"
+            }, error = function(e2) {
+                NULL
+            })
+        })
+
+        if (is.null(installed)) {
+            cli::cli_abort(c(
+                "Failed to {if (upgrade) 'upgrade' else 'install'} the {extension} extension.",
+                "i" = "It could not be found in the core or community repositories.",
+                "i" = "It might not be available for this version of DuckDB",
+                "i" = "Check that the extension name is correct: {.url https://duckdb.org/docs/extensions/overview}"
+            ))
+        }
     }
 
     if (isFALSE(quiet)) {
         action <- if (upgrade) "upgraded" else "installed"
-        repo_note <- if (installed == "community") " (from community repository)" else ""
+        repo_note <- if (!identical(installed, "core")) glue::glue(" (from {installed} repository)") else ""
         cli::cli_alert_success("{extension} extension {action}{repo_note}")
     }
 
@@ -198,3 +214,57 @@ ddbs_load <- function(
     }
 
 }
+
+
+
+#' Glimpse the status of a DuckDB extension
+#'
+#' Retrieves the row from DuckDB's \code{duckdb_extensions()} catalog for a given
+#' extension (the spatial extension by default) and prints a transposed
+#' \code{\link[dplyr]{glimpse}} of it: whether it is installed and loaded, its
+#' version, install path, description, and so on.
+#'
+#' @template conn_null
+#' @param extension name of the extension to inspect, default is "spatial"
+#'
+#' @returns A one-row \code{tibble} with the extension's metadata (invisibly).
+#' Called mainly for the glimpse printed as a side effect.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' ## load package
+#' library(duckspatial)
+#'
+#' # inspect the spatial extension on the default connection
+#' ddbs_extension_info()
+#'
+#' # or pass an explicit connection
+#' conn <- ddbs_create_conn()
+#' ddbs_extension_info(conn)
+#' ddbs_stop_conn(conn)
+#' }
+ddbs_extension_info <- function(conn = NULL, extension = "spatial") {
+
+    # 1. Resolve and validate inputs
+    conn <- conn %||% ddbs_default_conn()
+    dbConnCheck(conn)
+    assert_character_scalar(extension, "extension")
+
+    # 2. Query the extension catalog
+    info <- DBI::dbGetQuery(
+        conn,
+        "SELECT * FROM duckdb_extensions() WHERE extension_name = ?",
+        params = list(extension)
+    )
+
+    if (nrow(info) == 0) {
+        cli::cli_abort(
+            "Extension {.val {extension}} was not found in {.fn duckdb_extensions}."
+        )
+    }
+
+    # 3. Glimpse and return the row invisibly
+    dplyr::glimpse(tibble::as_tibble(info))
+
+}